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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.