Django OpenTelemetry instrumentation

Instrument a Django project with OpenTelemetry using the opentelemetry-instrument wrapper. Requests, template rendering, ORM queries, cache calls, and outbound HTTP are traced with no changes to your application code.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument django

The agent installs the Django instrumentor and wires the exporter for your project.

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

Prerequisites

• A running Django project with a WSGI or ASGI entry point.
• Python 3.8 or newer.
• Your Osuite ingest token and region.

Install and configure

1. Install the distro and OTLP exporter, then let bootstrap add the Django instrumentor.

   pip install opentelemetry-distro opentelemetry-exporter-otlp
   opentelemetry-bootstrap -a install

2. Set the exporter environment variables. DJANGO_SETTINGS_MODULE must be exported so the instrumentor can read your settings.

   export DJANGO_SETTINGS_MODULE="myproject.settings"
   export OTEL_SERVICE_NAME="<service-name>"
   export OTEL_RESOURCE_ATTRIBUTES="service.environment=production"
   export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.osuite.io:443"
   export OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your-ingest-token>"
   export OTEL_LOGS_EXPORTER="otlp"
   export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED="true"

Run Django with instrumentation

Bare host

Run Gunicorn through the wrapper in production:

opentelemetry-instrument gunicorn myproject.wsgi:application --bind 0.0.0.0:8000

For the development server, disable the autoreloader so a single instrumented process serves requests:

opentelemetry-instrument python manage.py runserver --noreload

Docker

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt opentelemetry-distro opentelemetry-exporter-otlp \
    && opentelemetry-bootstrap -a install
COPY . .

ENV DJANGO_SETTINGS_MODULE="myproject.settings"
ENV OTEL_LOGS_EXPORTER="otlp"
ENV OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED="true"

CMD ["opentelemetry-instrument", "gunicorn", "myproject.wsgi:application", "--bind", "0.0.0.0:8000"]

Pass the exporter variables at runtime:

docker run \
  -e OTEL_SERVICE_NAME="<service-name>" \
  -e OTEL_RESOURCE_ATTRIBUTES="service.environment=production" \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.osuite.io:443" \
  -e OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your-ingest-token>" \
  myimage

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: django-app
spec:
  template:
    spec:
      containers:
        - name: web
          image: myimage
          command: ["opentelemetry-instrument", "gunicorn", "myproject.wsgi:application", "--bind", "0.0.0.0:8000"]
          env:
            - name: DJANGO_SETTINGS_MODULE
              value: "myproject.settings"
            - name: OTEL_SERVICE_NAME
              value: "<service-name>"
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "service.environment=production"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "https://ingest.<region>.osuite.io:443"
            - name: OTEL_EXPORTER_OTLP_HEADERS
              value: "x-osuite-ingest-token=<your-ingest-token>"
            - name: OTEL_LOGS_EXPORTER
              value: "otlp"
            - name: OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED
              value: "true"

Framework gotchas

Use --noreload with the development server

manage.py runserver runs a file-watching autoreloader that forks a child process to serve requests. Under opentelemetry-instrument this splits instrumentation across two processes and you may see no traces. Always pass --noreload when running the dev server through the wrapper. Production servers such as Gunicorn are not affected.

Gunicorn and uWSGI fork after startup

With multiple Gunicorn or uWSGI workers, the worker processes are forked from the master and the exporter’s background thread does not survive the fork. Initialize the SDK per worker with a post_fork hook. See Gunicorn and uWSGI in the troubleshooting guide.

DJANGO_SETTINGS_MODULE

The Django instrumentor reads DJANGO_SETTINGS_MODULE to locate middleware settings. If it is unset in the process environment, requests are not traced. manage.py sets it for you, but Gunicorn and uWSGI do not — export it explicitly as shown above.

Verify in Osuite

What you should see

Send a request to the app. The service appears in APM within a minute with a trace per request, showing the view, ORM queries, and any outbound calls as nested spans. Application logs appear in the Logs explorer with the matching trace ID.

Troubleshooting

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.

Next steps

Custom instrumentation Add manual spans and metrics for your business logic.

Explore traces Open the trace explorer and service map in Osuite.

Correlate logs with traces Link application logs to the traces that produced them.