What the agent does
The agent reads the app's own wiring first, because this is a project with a plugin architecture rather than a single main.py. In an application like litestar-org/litestar-fullstack, src/py/app/server/asgi.py builds Litestar(plugins=[ApplicationCore()]), and ApplicationCore.on_app_init in server/core.py sets the OpenAPI config, applies auth, assigns cors_config and extends app_config.plugins with the instances defined in server/plugins.py: structlog, granian, the Advanced Alchemy SQLAlchemy plugin, Vite, SAQ, problem details, OAuth2, email and the domain plugin. lib/settings.py has an AppSettings dataclass whose other fields read the environment through get_env, and among them ENABLE_INSTRUMENTATION: bool = False with the docstring Enable OpenTelemetry instrumentation, which nothing in src/py/app reads; LogSettings already quiets the opentelemetry.sdk.metrics._internal logger. pyproject.toml depends on litestar[jinja,jwt,structlog,cryptography,pydantic] without the opentelemetry extra, and uv.lock pins Litestar 2.19.0 and contains no OpenTelemetry package. CI in .github/workflows/ci.yaml runs pre-commit, then pytest src/py/tests --cov=src/py/app on Python 3.12 and 3.13 with uv sync --all-groups; the test suite uses pytest-databases to start PostgreSQL.
Litestar 2.19 ships litestar.contrib.opentelemetry with OpenTelemetryConfig and OpenTelemetryPlugin, and the opentelemetry extra pulls in opentelemetry-instrumentation-asgi. The agent adds that extra to the Litestar dependency, plus opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http and opentelemetry-instrumentation-sqlalchemy, and runs uv lock so the lockfile and the --frozen installs in CI agree. It writes lib/telemetry.py, which builds a TracerProvider with a Resource whose service.name is the slugged settings.app.NAME, an OTLP HTTP span exporter that reads OTEL_EXPORTER_OTLP_ENDPOINT, and a BatchSpanProcessor, and returns an OpenTelemetryConfig with that provider and exclude set to /health and the static path so health checks and assets do not become traces.
The flag becomes real: ENABLE_INSTRUMENTATION gets a get_env default like its neighbours, config.py builds the telemetry config from it, and core.py appends plugins.otel only when it is true, so a deployment without a collector is byte-for-byte the current app. Because Advanced Alchemy owns the engine, the agent registers a startup hook that calls SQLAlchemyInstrumentor().instrument on that engine, giving every request span child spans per statement with the SQL in db.statement. For logs it adds a structlog processor that reads the current span context and binds trace_id and span_id to each event, placed before the renderer in the existing processor chain in lib/log.py, so a request's structlog lines and its trace share an id.
To prove it, the agent writes src/py/tests/unit/lib/test_telemetry.py, which builds the app with the flag on and an InMemorySpanExporter, calls /api/config/oauth through the test client and asserts one server span with the route in its attributes and no span for /health. pytest-databases starts PostgreSQL in Docker, and the sandbox has none, so it installs Docker first (sudo apt-get install -y docker.io, then starts dockerd) before uv run pytest src/py/tests --cov=src/py/app. It also runs make lint, which covers ruff, mypy, pyright, slotscheck, biome and codespell, after bun install in src/js/web as CI does, and commits with a conventional message because the repository's pre-commit configuration checks commit messages.
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 Litestar app and open a pull request. Read pyproject.toml, uv.lock for the pinned litestar version, .github/workflows/ci.yaml, .pre-commit-config.yaml, Makefile, .env.local.example, src/py/app/server/asgi.py, server/core.py, server/plugins.py, config.py, lib/settings.py, lib/log.py, domain/system/controllers.py and src/py/tests/conftest.py first. Use litestar.contrib.opentelemetry: add the opentelemetry extra, the SDK, the OTLP HTTP exporter and the SQLAlchemy instrumentation, and run uv lock. Build the tracer provider and OpenTelemetryConfig in a telemetry module with the service name from settings and the endpoint from the environment, exclude the health and static paths, and register the plugin only when the existing ENABLE_INSTRUMENTATION setting is true, reading it from the environment like the other settings. Instrument the Advanced Alchemy engine at startup and bind trace_id and span_id into structlog events. Add a unit test with an in-memory exporter that asserts a span for an API route and none for health. The tests need Docker for PostgreSQL, so install it in your sandbox first. Run the test suite with coverage and make lint, and open a pull request with the output.",
"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
The pull request adds src/py/app/lib/telemetry.py and src/py/tests/unit/lib/test_telemetry.py, and changes pyproject.toml, uv.lock, lib/settings.py, config.py, server/plugins.py, server/core.py, lib/log.py and .env.local.example, where ENABLE_INSTRUMENTATION and OTEL_EXPORTER_OTLP_ENDPOINT are documented. Its description shows the new test's assertions, the full pytest run with the coverage total, and the make lint output across every linter the Makefile runs.
With the flag on and an endpoint set, every request produces a server span with the route, the status and the SQL statements beneath it, and every structlog line carries the ids to find that span. With the flag off, which is the default, the plugin is not registered and no OpenTelemetry code runs on the request path.
Before merging, a reviewer sets the collector endpoint and any headers it needs, decides whether the SAQ worker process should get the same provider in a follow-up, and checks that the sampler the agent left at the SDK default suits their traffic.
Run it on every service without tracing
A team with several Litestar services sends this body once per repository to POST /o/{org}/sessions, each with its own repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own plugin list and settings and places the plugin where that app builds its config, and the key's webhook_url receives one run.completed per repository with the pull request in result.
A team that prefers to start it from an issue adds a Rush automation with a linear trigger on a label, in the Project that has the repository; the trigger appends the issue's title and description after this prompt, and an automation run is not tied to a key and has its own max_runs_per_hour cap.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
In an app built from plugins, tracing is a question of where things are registered: the flag that exists but is never read, the engine that belongs to another plugin, the processor chain that decides what a log line carries. The agent reads that wiring in its own sandbox, puts each piece where the app already puts its configuration, and keeps the default path unchanged so turning it on is one variable.
The test with the in-memory exporter, the suite with PostgreSQL, and every linter the Makefile runs are kept with the run and pasted into the pull request, so review is about endpoints and sampling rather than whether spans appear. Several services can be done at once, each in its own sandbox.
Frequently asked questions
Why is the plugin behind a flag?
Because the settings already declare ENABLE_INSTRUMENTATION and default it to false. The agent makes that flag real and reads it from the environment like the neighbouring settings, so a deployment without a collector runs exactly the current app and one variable turns tracing on.
Does it trace database queries?
Yes. The SQLAlchemy instrumentation is attached to the engine that the Advanced Alchemy plugin creates, at startup, so each statement becomes a child span with its SQL and the connection details under the request span.
What about the SAQ worker?
Jobs run in the worker process, which does not go through the ASGI middleware. The pull request leaves it untraced and says so; a follow-up can build the same provider there and start a span per job.
Why does the run need Docker?
The repository's tests use pytest-databases to start PostgreSQL in a container, so the agent installs Docker in its sandbox before running the suite. The tracing code itself needs no container.