How to monitor Django

What can go wrong with Django

• Migrations not applied. A deploy ships code that expects a new column; every view touching that model returns 500 until migrate runs.
• Gunicorn worker timeouts. A view that takes longer than Gunicorn's timeout (30 s by default) gets its worker killed: [CRITICAL] WORKER TIMEOUT in the log and a 502 from the proxy.
• Database connections. With CONN_MAX_AGE and many workers, connections can exceed the database's limit; without it, every request pays for a new connection.
• Static files missing. collectstatic did not run or the storage is wrong: pages load without CSS and JavaScript but still return 200.
• DEBUG left on. A deploy with DEBUG=True leaks settings and stack traces and keeps every SQL query in memory.

The signals that matter, with alert thresholds

Thresholds are starting points. Tune them after a week of data: an alert nobody acts on should be raised or removed.

How to check Django by hand

python manage.py check --deploy
python manage.py migrate --check   # non-zero exit if unapplied

curl -s https://example.com/healthz

journalctl -u gunicorn --since today | grep 'WORKER TIMEOUT'

curl -sI https://example.com/static/admin/css/base.css | head -1

How to watch Django with Vigil

1. Add the health view below and create an App health monitor on it in New monitor. Vigil reads each named check and alerts per check ("database is failed"), not just "the page is down". Add a secret and check it in the view if the endpoint is public (Vigil sends it as vigil-health-secret).
2. Add an Uptime monitor on the home page and a Keyword monitor for text that only renders when the page works.
3. Create a project under Errors and pass its DSN to sentry_sdk.init(); the Django integration is enabled automatically, with the request, user and release on every issue.
4. For traces, use opentelemetry-instrumentation-django plus the instrumentation for your database driver and send to the OTLP endpoint (quick start). You get views with latency histograms, slow queries and N+1 detection.
5. Install the server agent, add the Gunicorn unit to the services to watch and a log_watch for WORKER TIMEOUT. For cron-run management commands, see monitoring cron jobs.

from django.core.cache import cache
from django.db import connection
from django.http import JsonResponse


def healthz(request):
    checks = {}
    try:
        connection.ensure_connection()
        checks["database"] = {"status": "ok"}
    except Exception as e:
        checks["database"] = {"status": "failed", "message": str(e)[:200]}
    try:
        cache.set("healthz", 1, 5)
        checks["cache"] = {"status": "ok" if cache.get("healthz") == 1 else "failed"}
    except Exception as e:
        checks["cache"] = {"status": "failed", "message": str(e)[:200]}
    ok = all(c["status"] == "ok" for c in checks.values())
    # 200 either way: Vigil reads the per-check status from the body
    return JsonResponse({"status": "ok" if ok else "failed", "checks": checks})

Every alert goes to the channels you pick: email, Slack, Telegram, Discord, Microsoft Teams, Pushover, webhooks or on-call paging. Failures are confirmed by a second check before anyone is woken up.

Django monitoring FAQ