{"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,"search_vec":"'0.61':62 'applic':18 'automat':10 'b0':63 'cach':35 'capabl':14 'captur':20 'comprehens':38 'contrib':51 'current':59 'databas':30 'distribut':21 'django':4,8,16,65 'enabl':37 'framework':72 'frequent':55 'http':28 'instrument':2,6,13,66 'log':25 'maintain':43 'manual':12 'metric':23,68 'monitor':42 'observ':39,69 'opentelemetri':1,5,49,64 'opentelemetry-python-contrib':48 'oper':36 'part':45 'perform':41 'project':52 'provid':9 'python':50 'queri':31 'receiv':54 'relat':26 'render':33 'request':29 'templat':32 'trace':22,67 'updat':56 'version':61 'web':17,71 'web-framework':70","created_at":"2026-03-29T08:38:27.304254+00:00","updated_at":"2026-04-16T17:41:02.188069+00:00","problems":{"verify_error":"error: Failed to parse: `opentelemetry-instrumentation-django opentelemetry-distro opentelemetry-exporter-otlp`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `o`\nopentelemetry-instrumentation-django opentelemetry-distro opentelemetry-exporter-otlp\n                       "},"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.63b1","cli_name":"opentelemetry-instrument","cli_version":"opentelemetry-instrument 0.62b1","type":"library","homepage":"https://opentelemetry.io","github":"https://github.com/open-telemetry/opentelemetry-python-contrib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opentelemetry-instrumentation-django/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","web-framework","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":"stale"}}