DeployAngel

DeployAngel for Python

The DeployAngel agent for Django, FastAPI, Starlette, and Flask, with Celery and RQ jobs. It watches what your app does in production and reports one small aggregated payload per process per minute. DeployAngel uses that to verify every deployment, and to tell you (or your coding agent) when a release is cleared and you can stop watching it.

Install

Requires Python 3.10 or later. The package has no dependencies of its own.

pip install deployangel

Set this in production, for every process (web servers and job workers alike):

DEPLOYANGEL_TOKEN=da_live_...           # an ingestion token with the telemetry scope

On Heroku, the DeployAngel add-on sets it for you.

Django

Supports Django 4.2 or later.

# settings.py

INSTALLED_APPS = [

...

"deployangel.django", ]

That's all. The app puts DeployAngel's middleware at the top of MIDDLEWARE (list it yourself to place it), records requests under WSGI and ASGI, and instruments Celery when it's installed. Reporting is on when DEBUG is off.

FastAPI and Starlette

Supports FastAPI 0.100 and Starlette 0.27 or later.

import deployangel.fastapi

app = FastAPI() deployangel.fastapi.init(app) # deployangel.starlette.init(app) for Starlette

Call it where the app is created, before it serves requests.

Flask

Supports Flask 2.3 or later.

import deployangel.flask

app = Flask(name) deployangel.flask.init_app(app)

Celery

Supports Celery 5.3 or later. In Django it's automatic. Elsewhere, call init where the Celery app is created, so worker processes start the agent:

import deployangel.celery

app = Celery("shop") deployangel.celery.init(app)

RQ

Supports RQ 1.16 or later. Run workers with DeployAngel's worker class:

rq worker -w deployangel.rq.Worker               # or deployangel.rq.SimpleWorker

python manage.py rqworker --worker-class deployangel.rq.Worker # django-rq

RQ runs each job in a forked process that exits as soon as the job ends, so the worker records each job after it finishes, from what RQ saved in Redis. That includes a failed job's traceback, but not the exception of an attempt RQ retries.

Which release is running

The agent must know which release it's running. It finds it in this order:

1. DEPLOYANGEL_REVISION (the commit SHA) and DEPLOYANGEL_RELEASE_VERSION, if you set them
2. Heroku dyno metadata. Enable it with heroku labs:enable runtime-dyno-metadata and heroku labs:enable runtime-dyno-build-metadata; both take effect on the next deploy
3. Kamal: KAMAL_VERSION
4. Render: RENDER_GIT_COMMIT
5. Fly.io: the deploy's image tag, from FLY_IMAGE_REF. Fly.io sets no commit, so pass one in for commit-level change tracking (ENV DEPLOYANGEL_REVISION=$GIT_SHA in the Dockerfile, with --build-arg GIT_SHA=$(git rev-parse HEAD))
6. Railway: RAILWAY_GIT_COMMIT_SHA, or RAILWAY_DEPLOYMENT_ID
7. Coolify: SOURCE_COMMIT. Dokku: GIT_REV
8. a REVISION file in the app's root
9. a git checkout: the commit HEAD names, read from .git in the app's root or up to 3 directories above it, without running git. This covers servers deployed by git pull, Fabric, or Ansible
10. ECS, including Fargate: the container's image, from the metadata endpoint ECS provides (one local request at boot)
11. a code fingerprint: code: and the first 12 characters of the hash of the file digests the agent already sends (below), with no commit. The same code gives the same fingerprint, so a redeploy of unchanged code isn't a new release. It's computed in the background when the reporter starts, not at boot, and needs file digests on. Without a commit DeployAngel still shows which files changed in a release, but not its commits and pull requests, so the agent logs a warning: set DEPLOYANGEL_REVISION when you can

For other Docker deploys, bake the commit into the image: deployangel install docker adds ARG GIT_SHA and ENV DEPLOYANGEL_REVISION=$GIT_SHA to the end of your Dockerfile, where it doesn't invalidate cached layers, and you build with --build-arg GIT_SHA=$(git rev-parse HEAD). On DigitalOcean App Platform, set DEPLOYANGEL_REVISION: ${_self.COMMIT_HASH} in the app spec.

What it sends

• HTTP request counts, 4xx/5xx counts by status code, unhandled exceptions, and a latency histogram, both per app and per route.
• Routes are recorded as the pattern the framework matched (GET /users/ /, GET /items/{item_id}), never the raw path. At most 100 routes are sent per payload; the rest are folded into __other__.
• Background jobs: attempts, failed attempts, discarded jobs, duration, and queue latency, per task. For queue latency, Celery task messages carry one extra header, deployangel_published_at, the time they were sent.
• Tasks still running at the end of each minute, and how long the oldest of each has been running, so a task that hangs is noticed.
• Release identity, runtime versions, and a per-process instance ID.
• Exceptions: a stable fingerprint, the exception class, the first line of the message, and application frames only (file paths and function names), or the first library frames (package paths) when none is the app's. In the message, numbers, IDs, emails, UUIDs, long hex strings, quoted values, and the request's host are replaced with placeholders. Other words are kept: Payment failed for Jane Doe is sent as it is. If your app's messages might hold personal or health data, turn messages off.
• Once per process: the route table (with each view's module and file), task names and files, recurring schedules declared for Celery Beat (in settings or in django-celery-beat's tables), critical flows, and file digests (relative paths and hashes, never file contents) so DeployAngel can tell which routes changed in a release. Disable digests with DEPLOYANGEL_FILE_DIGESTS=false.

It does not send request bodies, parameters, headers, cookies, SQL, logs, or user data.

Data and pricing

• Everything goes to DeployAngel's hosted service, which runs on DigitalOcean in the United States. There's no self-hosted version, and no choice of region.
• Telemetry is kept for 21 days, and release history for 7, 30, or 90 days depending on the plan. The privacy policy has the details and the services DeployAngel uses.
• DeployAngel is free during the beta, with notice before paid plans start. See pricing.

Safety

• Nothing runs on the network during a request or job. Recording only updates in-memory counters.
• Payloads are sent from a background thread, once a minute, with short timeouts.
• When DeployAngel is unreachable, the buffer is bounded (60 payloads, an hour, kept as gzipped JSON) and the oldest are dropped. Your app is never blocked or failed.
• Safe across forks (Gunicorn, Celery's prefork pool, uWSGI), and the minute in progress is flushed at shutdown. Under uWSGI, enable threads (enable-threads = true).

python bench/overhead.py measures this. On an Apple M-series laptop with Python 3.14, recording a request adds about 1.7 µs, and with every route, job, checkpoint, and exception list at its cap the agent holds under 1 MB (0.73 MB at peak), including an hour (60) of unsent minutes.

Configuration

Environment variables are enough for most apps. In Django, settings go in a DEPLOYANGEL dict; elsewhere, call deployangel.configure before init:

# settings.py

DEPLOYANGEL = { "environments": ["production", "staging"], # default: production only }

or anywhere else

deployangel.configure(environments=["production", "staging"])

The agent reports in the environments listed. Python frameworks don't name an environment, so it's DEPLOYANGEL_ENVIRONMENT if set, otherwise development when the framework's debug mode is on and production when it's off. DEPLOYANGEL_ENABLED=true|false forces reporting on or off anywhere. DEPLOYANGEL_URL overrides the API endpoint (default https://api.deployangel.com).

File paths are relative to the app's root, the working directory by default (on Heroku and in most containers, the repository's root). Set DEPLOYANGEL_ROOT if your processes start somewhere else.

Critical flows (for example sign-up or password reset) are always listed in clearance reports:

DEPLOYANGEL = {

"critical_flows": {"password_reset": ["POST /password-reset/", "job:accounts.tasks.send_reset_email"]}, }

Health checks aren't recorded: load balancers and uptime monitors call them all the time and they always answer fast, so they would make your app look busier and healthier than its real pages. The agent recognizes django-health-check, django-alive, and django-watchman wherever they're mounted, and any route at a conventional path (/up, /health, /healthz, /healthcheck, /health_check, /livez, /readyz, /statusz, /ping, /ht, /alive). If yours is somewhere else, list it the way the dashboard shows it. HEAD requests to it are left out too:

DEPLOYANGEL = {"ignored_routes": ["GET /status/"]}

Exception messages

To send exceptions without any message, only their class, fingerprint, and stack frames:

DEPLOYANGEL = {"exception_messages": False}   # or DEPLOYANGEL_EXCEPTION_MESSAGES=false

Grouping, new-exception detection, and verdicts work the same, since the fingerprint never uses the message. You lose the message text in the dashboard, notifications, and AI investigation.

Handled exceptions

Exceptions your code catches aren't seen. To report one for context (handled exceptions never fail a release):

try:

sync_inventory() except UpstreamError as error: deployangel.notify(error)

Recurring jobs

DeployAngel expects declared recurring tasks on schedule. It reads Celery Beat's beat_schedule (crontabs, and intervals, which repeat from when Beat starts) in the zone Celery uses, and, when django_celery_beat is installed, its enabled periodic tasks. Solar schedules aren't read, and neither are RQ's schedulers, whose jobs live only in Redis. DeployAngel also learns recurring jobs from their history.

Cron, Heroku Scheduler, and django-crontab

Work that something outside the app starts on a schedule, such as cron, Heroku Scheduler, or a Kubernetes CronJob, is invisible to Celery Beat. Declare it by the name it runs under, with a cron line or words like "every day at 4am", in the server's time zone unless you add one ("0 3 * * * America/New_York"):

DEPLOYANGEL = {

"recurring_jobs": { "shop.tasks.send_receipts": "0 3 * * *", # a Celery or RQ task "manage.py send_invoices": "every day at 4am", # python manage.py send_invoices "nightly import": "30 2 * * *", # deployangel.task("nightly import") }, }

• A task is recorded wherever it runs.
• A Django management command named "manage.py " is recorded with no code change.
• Any other code is recorded when you wrap it. Exceptions are recorded and re-raised:

  with deployangel.task("nightly import"):

run_import()

@deployangel.task("nightly import") def run_import(): ...

django-crontab's CRONJOBS setting is read automatically when django_crontab is installed: each job is expected on its schedule in the server's zone, and its runs are recorded with no change to the job (a job that calls call_command is recorded as manage.py ).

Checkpoints

Errors and latency don't catch work that silently stops happening. Count the business events that matte