Registry /
observability / opentelemetry-instrumentation-django
OpenTelemetry Instrumentation for Django provides automatic and manual instrumentation capabilities for Django web applications. It captures distributed traces, metrics, and logs related to HTTP requests, database queries, template rendering, and cache operations, enabling comprehensive observability and performance monitoring. Maintained as part of the `opentelemetry-python-contrib` project, it receives frequent updates and is currently at version 0.61b0.
Install & Compatibility
Where this runs
tested against v0.63b1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DjangoInstrumentor
✓ from opentelemetry.instrumentation.django import DjangoInstrumentor
This quickstart demonstrates how to manually initialize OpenTelemetry and instrument a Django application. The `DjangoInstrumentor().instrument()` call sets up automatic tracing for HTTP requests, database queries, and other Django components. For a zero-code setup, `opentelemetry-instrument` wrapper is commonly used (e.g., `opentelemetry-instrument python manage.py runserver`).
import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.instrumentation.django import DjangoInstrumentor
# Configure OpenTelemetry SDK
resource = Resource.create({"service.name": os.environ.get('OTEL_SERVICE_NAME', 'my-django-app')})
provider = TracerProvider(resource=resource)
# For demonstration, export traces to console
# In a real application, you'd use OTLPSpanExporter or similar
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Instrument Django
DjangoInstrumentor().instrument()
print("OpenTelemetry Django instrumentation initialized.")
# This code snippet would typically be placed in a Django app's __init__.py
# or a settings-loaded module, ensuring it runs during application startup.
# For a zero-code approach, use `opentelemetry-instrument python manage.py runserver`
opentelemetry-instrument --version
Debug
Known issues
breakingAs of version 0.61b0, support for Django versions older than 2.0 has been dropped. Applications using older Django versions will need to upgrade Django or pin to an older `opentelemetry-instrumentation-django` version.fixUpgrade Django to version 2.0 or newer, or use `opentelemetry-instrumentation-django<0.61b0`.
affects: >=0.61b0
gotchaThe library is in a beta (`b0`) release stage, indicating potential API changes or instability. While widely used, be aware of this when deploying to production and monitor for updates.fixStay updated with releases, review changelogs, and conduct thorough testing before deploying new beta versions.
affects: All `b0` versions
gotchaWhen using `request_hook` to add attributes to spans, attributes dependent on Django's middleware (e.g., `request.user`, `request.site`) will not be available. These should be attached in the `response_hook` instead, which executes after all middlewares have run.fixPlace logic for adding middleware-dependent attributes into the `response_hook` callback of `DjangoInstrumentor().instrument()`.
affects: All versions
gotchaFor comprehensive automatic instrumentation (e.g., database drivers like psycopg2, redis, requests), the `opentelemetry-bootstrap -a install` command should be run in your environment. This command scans installed packages and installs appropriate instrumentation libraries.fixExecute `opentelemetry-bootstrap -a install` after installing `opentelemetry-distro` and `opentelemetry-instrumentation-django` to ensure all detectable components are instrumented.
affects: All versions
breakingThe `opentelemetry-instrumentation-django` library requires Django to be installed in the environment for it to be imported and used. This error indicates that Django is missing.fixEnsure Django is installed in your environment by running `pip install Django` before using `opentelemetry-instrumentation-django`.
affects: All versions
breakingThe `opentelemetry-instrumentation-django` library requires Django to be installed. Without Django, the instrumentation library cannot function, leading to a `ModuleNotFoundError`.fixEnsure Django is installed in your environment, e.g., by running `pip install django`.
affects: All versions
Audit
Dependencies
DjangorequiredThe framework being instrumented.
opentelemetry-apirequiredCore OpenTelemetry API definitions.
opentelemetry-sdkrequiredCore OpenTelemetry SDK implementation.
opentelemetry-distrooptionalProvides auto-instrumentation bootstrap tool and common configurations.
opentelemetry-exporter-otlpoptionalCommon exporter for sending telemetry data to an OTLP-compatible backend.