{"id":1005,"library":"opentelemetry-instrumentation-django","title":"OpenTelemetry Instrumentation for Django","description":"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.","status":"active","version":"0.61b0","language":"python","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","django","instrumentation","tracing","metrics","observability","web-framework"],"install":[{"cmd":"pip install opentelemetry-instrumentation-django opentelemetry-distro opentelemetry-exporter-otlp","lang":"bash","label":"Full instrumentation setup"}],"dependencies":[{"reason":"The framework being instrumented.","package":"Django"},{"reason":"Core OpenTelemetry API definitions.","package":"opentelemetry-api"},{"reason":"Core OpenTelemetry SDK implementation.","package":"opentelemetry-sdk"},{"reason":"Provides auto-instrumentation bootstrap tool and common configurations.","package":"opentelemetry-distro","optional":true},{"reason":"Common exporter for sending telemetry data to an OTLP-compatible backend.","package":"opentelemetry-exporter-otlp","optional":true}],"imports":[{"symbol":"DjangoInstrumentor","correct":"from opentelemetry.instrumentation.django import DjangoInstrumentor"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter\nfrom opentelemetry.instrumentation.django import DjangoInstrumentor\n\n# Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": os.environ.get('OTEL_SERVICE_NAME', 'my-django-app')})\nprovider = TracerProvider(resource=resource)\n\n# For demonstration, export traces to console\n# In a real application, you'd use OTLPSpanExporter or similar\nprocessor = BatchSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# Instrument Django\nDjangoInstrumentor().instrument()\n\nprint(\"OpenTelemetry Django instrumentation initialized.\")\n# This code snippet would typically be placed in a Django app's __init__.py \n# or a settings-loaded module, ensuring it runs during application startup.\n# For a zero-code approach, use `opentelemetry-instrument python manage.py runserver`","lang":"python","description":"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`)."},"warnings":[{"fix":"Upgrade Django to version 2.0 or newer, or use `opentelemetry-instrumentation-django<0.61b0`.","message":"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.","severity":"breaking","affected_versions":">=0.61b0"},{"fix":"Stay updated with releases, review changelogs, and conduct thorough testing before deploying new beta versions.","message":"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.","severity":"gotcha","affected_versions":"All `b0` versions"},{"fix":"Place logic for adding middleware-dependent attributes into the `response_hook` callback of `DjangoInstrumentor().instrument()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Execute `opentelemetry-bootstrap -a install` after installing `opentelemetry-distro` and `opentelemetry-instrumentation-django` to ensure all detectable components are instrumented.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure Django is installed in your environment by running `pip install Django` before using `opentelemetry-instrumentation-django`.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure Django is installed in your environment, e.g., by running `pip install django`.","message":"The `opentelemetry-instrumentation-django` library requires Django to be installed. Without Django, the instrumentation library cannot function, leading to a `ModuleNotFoundError`.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T22:31:16.538Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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`. \nExample (shell): `export DJANGO_SETTINGS_MODULE=myproject.settings && opentelemetry-instrument python manage.py runserver`\nExample (code in manage.py): `os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')` before `DjangoInstrumentor().instrument()`","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.","error":"No traces or spans are generated for Django application"},{"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.","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.","error":"ModuleNotFoundError: No module named 'opentelemetry.instrumentation.django'"},{"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.","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.","error":"AttributeError: 'ResolverMatch' object has no attribute 'route'"},{"fix":"Install the OpenTelemetry ASGI instrumentation package: `pip install opentelemetry-instrumentation-asgi`. Additionally, ensure that `OpenTelemetryMiddleware` is correctly configured in your `asgi.py` file.","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.","error":"Django ASGI instrumentation silently ignored / no traces for ASGI requests"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.62b1","cli_name":"opentelemetry-instrument","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","installed_version":"0.62b1","pypi_latest":"0.62b1","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"52.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":5.7,"import_time_s":null,"mem_mb":null,"disk_size":"50M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"55.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.9,"import_time_s":null,"mem_mb":null,"disk_size":"54M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"47.4M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.1,"import_time_s":null,"mem_mb":null,"disk_size":"45M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"47.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.1,"import_time_s":null,"mem_mb":null,"disk_size":"45M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"51.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.3,"import_time_s":null,"mem_mb":null,"disk_size":"49M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-django","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}