OpenTelemetry Instrumentation for Django

0.61b0 verified Tue May 12 auth: no python install: stale

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.

pip install opentelemetry-instrumentation-django opentelemetry-distro opentelemetry-exporter-otlp

Common errors

error No traces or spans are generated for Django application ↓

cause The `DJANGO_SETTINGS_MODULE` environment variable is not set before the OpenTelemetry Django instrumentation is applied, preventing Django's internals from being properly initialized and leading to a silent failure in trace generation.

fix

Ensure DJANGO_SETTINGS_MODULE is set as an environment variable before running your application with opentelemetry-instrument or before calling DjangoInstrumentor().instrument() in your code, typically in manage.py or wsgi.py/asgi.py. Example (shell): export DJANGO_SETTINGS_MODULE=myproject.settings && opentelemetry-instrument python manage.py runserver Example (code in manage.py): os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings') before DjangoInstrumentor().instrument()

error ModuleNotFoundError: No module named 'opentelemetry.instrumentation.django' ↓

cause The `opentelemetry-instrumentation-django` package is either not installed, or it is installed in a different Python environment than the one running the application, or there is a namespace package conflict.

fix

Install the package using pip: pip install opentelemetry-instrumentation-django. Verify that all OpenTelemetry packages are installed in the correct Python environment and consider using pip freeze to check installed versions or opentelemetry-bootstrap to detect missing packages.

error AttributeError: 'ResolverMatch' object has no attribute 'route' ↓

cause This error can occur with older Django versions (e.g., Django 2.1) when using `opentelemetry-instrumentation-django`, indicating a compatibility issue with how the instrumentation middleware accesses routing information.

fix

Update opentelemetry-instrumentation-django and potentially Django itself to compatible versions. This specific error was addressed in a pull request, so upgrading the instrumentation library should resolve it. If upgrading Django is not an option, check the library's release notes for version compatibility.

error Django ASGI instrumentation silently ignored / no traces for ASGI requests ↓

cause When using `opentelemetry-instrumentation-django` with an ASGI application (e.g., Django Channels), tracing for ASGI requests is silently ignored if `opentelemetry-instrumentation-asgi` is not also installed.

fix

Install the OpenTelemetry ASGI instrumentation package: pip install opentelemetry-instrumentation-asgi. Additionally, ensure that OpenTelemetryMiddleware is correctly configured in your asgi.py file.

Warnings

breaking As 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. ↓

fix Upgrade Django to version 2.0 or newer, or use `opentelemetry-instrumentation-django<0.61b0`.

gotcha The 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. ↓

fix Stay updated with releases, review changelogs, and conduct thorough testing before deploying new beta versions.

gotcha When 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. ↓

fix Place logic for adding middleware-dependent attributes into the `response_hook` callback of `DjangoInstrumentor().instrument()`.

gotcha For 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. ↓

fix Execute `opentelemetry-bootstrap -a install` after installing `opentelemetry-distro` and `opentelemetry-instrumentation-django` to ensure all detectable components are instrumented.

breaking The `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. ↓

fix Ensure Django is installed in your environment by running `pip install Django` before using `opentelemetry-instrumentation-django`.

breaking The `opentelemetry-instrumentation-django` library requires Django to be installed. Without Django, the instrumentation library cannot function, leading to a `ModuleNotFoundError`. ↓

fix Ensure Django is installed in your environment, e.g., by running `pip install django`.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 52.3M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 5.7s - 50M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 55.8M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 4.9s - 54M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 47.4M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 4.1s - 45M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 47.1M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 4.1s - 45M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 51.5M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 6.3s - 49M

3.9 slim (glibc) - - - -

Imports

DjangoInstrumentor

from opentelemetry.instrumentation.django import DjangoInstrumentor

Quickstart last tested: 2026-04-24

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`