Registry /
observability / opentelemetry-instrumentation-django
Install & Compatibility
Where this runs
tested against v0.65b0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 52.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 0.000s · 51MB
50MB installed
● package 50MB
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
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
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.