# Add OpenTelemetry Tracing to a Django REST Framework API

Yes. An agent instruments a DRF API with the OpenTelemetry SDK for Django, psycopg2 and Celery, links trace ids into your structlog lines, tests it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-opentelemetry/django-rest-framework/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the project is wired before it adds a dependency. In an API laid out like HackSoftware/Django-Styleguide-Example, `requirements/base.txt` pins Django 5.2.7, `djangorestframework` 3.16.1, `psycopg2` 2.9.11, `celery` 5.5.3 and `gunicorn` 23.0.0, and the settings are composed: `config/django/base.py` builds `INSTALLED_APPS` and `MIDDLEWARE`, then imports `config/settings/celery.py`, `cors.py`, `sentry.py`, `sessions.py` and the rest, and `config/settings/loggers/setup.py` adds `django_structlog` and its `RequestMiddleware`. There is already a model for an optional integration: `sentry.py` reads `SENTRY_DSN` with `django-environ` and calls `sentry_sdk.init` with `DjangoIntegration` and `CeleryIntegration` only when it is set. The web process is `gunicorn config.wsgi:application` (the `Procfile` and `docker/web_entrypoint.sh` agree), the worker is `celery -A styleguide_example.tasks worker` whose app lives in `styleguide_example/tasks/celery.py`, and `gunicorn.conf.py` already configures logging through structlog. Nothing emits traces today.

The change follows that model. The agent adds `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http`, `opentelemetry-instrumentation-django`, `opentelemetry-instrumentation-psycopg2`, `opentelemetry-instrumentation-celery` and `opentelemetry-instrumentation-requests` to `requirements/base.txt` at pinned versions, and writes `config/settings/opentelemetry.py`, which reads `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_SERVICE_NAME` through `env` and does nothing when the endpoint is unset, so local development, the test settings in `config/django/test.py` and the Docker Compose stack behave as before. When it is set, a `setup_tracing()` function builds a `TracerProvider` with a `Resource` carrying the service name and the environment, attaches a `BatchSpanProcessor` around the OTLP HTTP exporter, and calls `DjangoInstrumentor().instrument()`, `Psycopg2Instrumentor().instrument()` and `RequestsInstrumentor().instrument()`. Because gunicorn forks workers after importing the config, the call goes in a `post_fork` hook in `gunicorn.conf.py` rather than at import time in `config/wsgi.py`, and the Celery side registers `CeleryInstrumentor().instrument()` on the `worker_process_init` signal in `styleguide_example/tasks/celery.py`, next to the `setup_logging` receiver already there.

Logs and traces are joined where the project already does its logging. `LoggersSetup.setup_structlog()` configures the processor chain, and the agent adds one processor that reads the current span's context and puts `trace_id` and `span_id` into the event dict in hex, after `merge_contextvars` so the `request_id` django-structlog sets stays beside them. The `JSON` and `LOGFMT` formats in `config/settings/loggers/settings.py` then carry both ids on every line a request or task writes, which is what makes a trace in the collector findable from a log line and the other way round.

Tests follow the repository's pytest setup. With `DJANGO_SETTINGS_MODULE=config.django.test` from `pytest.ini`, the agent adds a test module beside `styleguide_example/api/tests/` that installs an `InMemorySpanExporter` on a tracer provider, calls `GET /api/users/` through DRF's `APIClient`, and asserts one server span whose `http.route` attribute is the `users/` pattern and a child span for the `SELECT` psycopg2 issued, plus a structlog capture showing `trace_id` set during the request. It then runs what `.github/workflows/django.yml` runs: `ruff check .`, `mypy --config mypy.ini styleguide_example/` (adding an `ignore_missing_imports` block for `opentelemetry.*` to `mypy.ini` in the style of the existing ones if the stubs are incomplete) and `pytest` against a PostgreSQL started in the sandbox, since the test settings keep the real database and only make Celery eager.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add OpenTelemetry tracing to this Django REST Framework API and open a pull request. Read requirements/base.txt, config/django/base.py, config/django/test.py, config/settings/sentry.py, config/settings/loggers/setup.py, config/settings/loggers/settings.py, config/env.py, gunicorn.conf.py, styleguide_example/tasks/celery.py, pytest.ini, mypy.ini and .github/workflows/django.yml first. Add pinned opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http and the Django, psycopg2, Celery and requests instrumentation packages to requirements/base.txt. Write config/settings/opentelemetry.py with a setup_tracing() that reads OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME through env, returns early when the endpoint is unset, and otherwise builds a TracerProvider with a Resource and a BatchSpanProcessor over the OTLP HTTP exporter and instruments Django, psycopg2 and requests. Call it from a post_fork hook in gunicorn.conf.py, and instrument Celery on worker_process_init in styleguide_example/tasks/celery.py. Add a structlog processor in LoggersSetup.setup_structlog that adds trace_id and span_id in hex when a span is recording. Add a pytest module that uses an InMemorySpanExporter to assert a server span for GET /api/users/ with the route attribute and a psycopg2 child span. Run ruff check ., mypy --config mypy.ini styleguide_example/ and pytest against PostgreSQL, and put their output in the pull request description. Do not change sentry.py.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `config/settings/opentelemetry.py` and a test module, and changes `requirements/base.txt`, `config/django/base.py` (one import line in the block that pulls in the other settings modules), `gunicorn.conf.py`, `styleguide_example/tasks/celery.py`, `config/settings/loggers/setup.py` and, if needed, `mypy.ini`. The description shows the `ruff`, `mypy` and `pytest` output from the sandbox, the span the test captured with its name and attributes, and one JSON log line with `request_id`, `trace_id` and `span_id` side by side. The session keeps every command with its output, and `GET /o/{org}/p/{project}/sessions/{id}/changes` returns the diff per file.

On a repository with this `django.yml`, the pull request's two jobs run again: the `docker_build` job builds the Compose images and runs ruff, mypy and `py.test` inside them, and the `build` job runs the same three against the PostgreSQL service on Python 3.12.4, so the new requirement is installed both ways.

A reviewer checks three things: that with `OTEL_EXPORTER_OTLP_ENDPOINT` unset nothing changes, which the early return and the unchanged test settings guarantee; that the exporter is created after the fork and not before, since a `BatchSpanProcessor` thread created in the gunicorn master would not survive into the workers; and that the Sentry setup is untouched, because both can run together and the pull request does not decide which one the team keeps.

## Run it on every service without tracing

Run it once per API a team owns rather than once: a script that walks `GET /o/{org}/github` for the installation's repositories and calls `POST /o/{org}/sessions` with this body and each repository's URL in `resources`, with a `request_id` per repository so a retry returns the run already started. Each repository gets its own sandbox and its own pull request.

Give the key a `webhook_url` and Rush POSTs `run.completed`, `run.failed` or `run.cancelled` when each turn ends, signed per Standard Webhooks, with `data.session_url` to read for the pull request. A key runs at most `max_concurrent` sessions at once, 4 by default; a batch over many DRF services can still go out together, because each one past that number is queued (`202`, `status: "queued"`) and instrumented when a slot frees.

## Why run it on Rush?

Instrumenting a Django app is less about the SDK calls than about where they run: before or after gunicorn forks, in the Celery worker process or in the parent, and whether a test can see the spans without a collector. The agent settles each of those by reading the repository's own `gunicorn.conf.py`, Celery app and test settings, then proves the placement with a test that captures spans in memory and a log line with the ids in it, all in its own sandbox with PostgreSQL running, and the output stays on the session.

What arrives is a pull request whose checks have run, with a diff a reviewer can read in a few minutes because it follows the shape the project already uses for Sentry. The same body applies to every DRF service a team owns, each in its own sandbox, and a change of exporter or a sampling rule is a follow-up on the same parked session rather than a fresh setup.

## Frequently asked questions

### Does it replace Sentry?

No. `config/settings/sentry.py` is untouched and still initialises when `SENTRY_DSN` is set. The OpenTelemetry setup is a second, independent switch on `OTEL_EXPORTER_OTLP_ENDPOINT`; which one the team keeps for performance data is a decision the pull request leaves open.

### Why a post_fork hook instead of calling it in wsgi.py?

Because `BatchSpanProcessor` starts a background thread to export spans, and a thread started in the gunicorn master before `fork()` does not exist in the workers. `gunicorn.conf.py` already exists for logging, so the hook sits beside configuration the project owns.

### Will the trace ids show up in logs?

Yes. The added structlog processor puts `trace_id` and `span_id` into every event logged while a span is recording, and the existing `JSON` and `LOGFMT` renderers write them out beside django-structlog's `request_id`. With the `DEV` format they appear in the key-value tail of the console line.

### Does the test need a collector?

No. It swaps the exporter for `InMemorySpanExporter` from the SDK's test utilities, so `pytest` runs in CI exactly as before and asserts on captured spans. No endpoint is contacted during tests.

### Does it work with the Celery worker in Docker Compose?

Yes. The `celery` and `beats` services use the same image and settings, and the instrumentation registers on `worker_process_init`, so each worker process exports its own task spans when the endpoint variable is set in the Compose environment. Without it the worker runs as it does today.

## More Django REST Framework jobs

- [Add a Password Change Endpoint to a Django REST Framework API from a Linear Issue](https://getrush.ai/run/add-password-change/django-rest-framework/)
- [Add a Password Reset API to a Django REST Framework Project](https://getrush.ai/run/add-password-reset/django-rest-framework/)
- [Add Prometheus Metrics to a Django REST Framework API](https://getrush.ai/run/add-prometheus-metrics/django-rest-framework/)

## The same job on other stacks

- [Add OpenTelemetry Tracing to an Echo API](https://getrush.ai/run/add-opentelemetry/echo/)
- [Add OpenTelemetry Tracing to an Express Service](https://getrush.ai/run/add-opentelemetry/express/)
- [Add OpenTelemetry Tracing to a FastAPI Service](https://getrush.ai/run/add-opentelemetry/fastapi/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
