Skip to content

Django O11y

Test Supported Python versions PyPI Version License

What is django-o11y?

django-o11y is a drop-in observability library for Django. It gives you traces, logs, metrics, and optional profiling with one DJANGO_O11Y settings dict.

Why django-o11y?

In production, error tracking alone is not enough. You also need request latency, slow query visibility, background task health, and logs tied to traces. Wiring this stack by hand is repetitive and easy to get wrong.

django-o11y bundles the patterns from these blog posts into a single installable package:

Getting started

pip install django-o11y

Start with the Usage guide, then use the Configuration reference when you need to tune behavior. To see what the local observability stack looks like, check the Demo stack.

How it works

django-o11y wires up four observability pillars on AppConfig.ready():

  • Tracing — OpenTelemetry TracerProvider with OTLP gRPC export (set CONSOLE_EXPORTER: true for stdout instead). TracingMiddleware creates a root span per request; database, cache, and outbound HTTP calls are auto-instrumented.
  • Logging — Structlog with automatic trace_id/span_id injection so every log line links back to its trace. Colorized console output in development, JSON in production.
  • Metrics — django-prometheus instruments requests, database operations, and cache operations. A thin counter()/histogram() API is available for custom business metrics.
  • Profiling — Optional Pyroscope integration for continuous CPU/memory profiling with tag propagation from the active trace.

All signals share trace_id, so you can jump from a metric to its trace, then to logs from that same request.

Features

  • OpenTelemetry distributed traces for requests, database queries, cache operations, and Celery tasks
  • Structlog structured logging with colorized dev output, JSON production format, and automatic trace correlation
  • django-prometheus metrics with a simple counter()/histogram() API for custom business metrics
  • Pyroscope continuous profiling (optional)
  • Full Celery observability — per-task traces linked to originating requests, structured task logs, and metrics via celery-exporter
  • Pre-built Grafana dashboards and alerts from django-mixin and celery-mixin
  • manage.py o11y stack start/stop/logs spins up a local Docker Compose stack (Grafana, Tempo, Loki, Prometheus, Pyroscope, Alloy) wired to your app. manage.py o11y check verifies your config, tests OTLP connectivity, and sends a test trace.
  • Sensible defaults, overridable via DJANGO_O11Y settings or environment variables

Acknowledgments