# Add OpenTelemetry Tracing to a Litestar App

Yes. An agent wires Litestar's OpenTelemetry plugin into your app behind the flag your settings already declare, instruments SQLAlchemy and adds trace ids to logs.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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.

## 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.

## More Litestar jobs

- [Add Prometheus Metrics to a Litestar App](https://getrush.ai/run/add-prometheus-metrics/litestar/)
- [Add Rate Limiting to a Litestar API](https://getrush.ai/run/add-rate-limiting/litestar/)
- [Add Request ID Logging to a Litestar App](https://getrush.ai/run/add-request-id-logging/litestar/)

## The same job on other stacks

- [Add OpenTelemetry Tracing to a Medusa Backend](https://getrush.ai/run/add-opentelemetry/medusa/)
- [Add OpenTelemetry Tracing to an Express and Mongoose API](https://getrush.ai/run/add-opentelemetry/mongoose/)
- [Add OpenTelemetry Tracing to a NestJS Service](https://getrush.ai/run/add-opentelemetry/nestjs/)

## 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/)
