# Add OpenTelemetry Tracing to a Flask App

Yes. An agent adds OpenTelemetry to your Flask app's factory, instruments Flask, SQLAlchemy, Redis and requests, proves spans with a test, and opens a PR.

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

## What the agent does

The agent starts from how the app is built and served. In a Flask app like CTFd/CTFd, `CTFd/__init__.py` holds `create_app()`, an application factory that reads `CTFd.config.Config`, initialises Flask-Caching, Flask-SQLAlchemy and Flask-Migrate, wraps the WSGI app in `ProxyFix` when `REVERSE_PROXY` is set, registers the view, API, auth, admin and other blueprints, then calls `init_logs`, `init_events`, `init_plugins` and `init_cli`. `pyproject.toml` pins `Flask==2.1.3`, `Werkzeug==2.2.3`, `SQLAlchemy==1.4.54`, `redis==4.5.5`, `requests==2.32.4`, `gunicorn==23.0.0` and `gevent==25.5.1`, and requires Python 3.11 exactly; `uv.lock` is the source of truth and `requirements.txt` is generated from it by `make requirements`, which the lint workflow checks is in sync. Any new dependency therefore goes into `pyproject.toml` first, then through `uv lock` and `make requirements`, or CI fails on the diff.

Serving matters because gevent is in the path. `wsgi.py` and `serve.py` call `gevent.monkey.patch_all()` before importing `create_app`, and `docker-entrypoint.sh` runs `gunicorn 'CTFd:create_app()' --worker-class gevent` after `flask db upgrade`. The agent checks that the OpenTelemetry Flask, SQLAlchemy, Redis and requests instrumentations it picks support Flask 2.1 and SQLAlchemy 1.4 before pinning them, and that context propagation holds across greenlets, which the SDK's contextvars-based context does once monkey patching happens first, as the repository already arranges.

The change itself is one new module, `CTFd/utils/telemetry.py`, with an `init_telemetry(app)` that does nothing unless `OTEL_EXPORTER_OTLP_ENDPOINT` is set, and otherwise builds a `TracerProvider` with a `service.name` resource from `OTEL_SERVICE_NAME` and an OTLP HTTP exporter, instruments the app with `FlaskInstrumentor().instrument_app(app, excluded_urls=...)` so the `/events` server-sent-events stream and `/themes/<theme>/static/<path>` do not become spans, instruments the SQLAlchemy engine inside the app context so every query is a child span with the statement, and instruments the `redis` client Flask-Caching uses when `CACHE_TYPE` is `redis` and the `requests` session behind `update_check`. `create_app` calls it after the blueprints are registered. The two variables are documented in `CTFd/config.ini` under `[optional]`, where the `EnvInterpolation` class already falls back to environment variables for empty keys.

Proof is a test, not a screenshot. `tests/utils/test_telemetry.py` uses the repository's `create_ctfd` helper with an `InMemorySpanExporter` wired into the provider, requests `/api/v1/challenges` with the test client, and asserts a server span named for that route with a database child span beneath it, and asserts that no span exists for `/events`. The agent runs `uv run make test`, which is `pytest -n auto` with coverage, and `uv run make lint`, which is `ruff check` and `ruff format --check`, and then starts the app with `python serve.py` and a console exporter to show a real request producing real spans.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add OpenTelemetry tracing to this Flask app. Read CTFd/__init__.py (create_app), wsgi.py, serve.py, docker-entrypoint.sh, CTFd/config.py, CTFd/config.ini, pyproject.toml, the Makefile and .github/workflows/lint.yml first. Choose opentelemetry-sdk, the OTLP HTTP exporter and the Flask, SQLAlchemy, redis and requests instrumentations at versions that support the pinned Flask 2.1.3 and SQLAlchemy 1.4.54, and say which versions and why. Add them to pyproject.toml, run uv lock and make requirements so requirements.txt stays in sync. Write CTFd/utils/telemetry.py with init_telemetry(app): a no-op unless OTEL_EXPORTER_OTLP_ENDPOINT is set, otherwise a tracer provider with a service.name resource from OTEL_SERVICE_NAME, Flask instrumentation that excludes /events and theme static files, SQLAlchemy instrumentation on the app's engine, redis instrumentation when CACHE_TYPE is redis, and requests instrumentation. Call it from create_app after the blueprints are registered. Document both variables in CTFd/config.ini. Add tests/utils/test_telemetry.py using create_ctfd and an in-memory span exporter that asserts a server span for GET /api/v1/challenges with a database child span and no span for /events. Run uv run make test and uv run make lint and fix what they report. Start python serve.py with a console exporter, make two requests, and quote the spans. Do not change the Dockerfile, docker-compose.yml, uv's Python pin or any workflow. Open a pull request with the files, the chosen versions, the test output and the quoted spans.",
  "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 on its own branch that adds `CTFd/utils/telemetry.py` and `tests/utils/test_telemetry.py`, adds one call in `create_app` in `CTFd/__init__.py`, adds the OpenTelemetry packages to `pyproject.toml` with matching changes to `uv.lock` and the generated `requirements.txt`, and documents `OTEL_SERVICE_NAME` and `OTEL_EXPORTER_OTLP_ENDPOINT` in `CTFd/config.ini`. The Dockerfile, compose file and workflows are untouched; with the endpoint variable unset the app runs exactly as before.

The description names the instrumentation versions and the Flask and SQLAlchemy ranges they declare, quotes the `make test` summary and the `ruff` result, and pastes the console exporter's output for two requests: the server span with its route name and status, and the SQLAlchemy child span with its statement. It also says what was excluded from tracing and why.

A reviewer reads the module, checks that `init_telemetry` is a no-op without the endpoint, looks at the excluded URLs against the nginx `location /events` block, and merges when the lint and SQLite CI workflows pass. The transcript holds every command the agent ran, including the `uv lock` step.

## Run it on every Flask service without tracing

This is a one-time change per service, so it is usually started by hand: `POST /o/{org}/sessions` with this prompt and the repository in `resources`, once per Flask repository you own, each in its own sandbox. The sandbox parks when the turn ends, so a follow-up such as adding a metrics exporter wakes the same checkout.

If a saved agent holds the prompt as its `instructions`, the call is `{"agent": "<agent id>", "input": "<repository and any service-specific notes>"}` with the repository in `resources`; a key with a `webhook_url` gets `run.completed` with `data.session_url`, where the pull request URL is read.

## Why run it on Rush?

Adding tracing to a Flask app that runs under gevent and gunicorn is mostly about order: monkey patching before imports, provider setup once per worker, instrumentation of the engine inside the app context. Getting that wrong produces spans with no parents, which is only visible by running the app and looking. The sandbox installs the exact pins, runs the app and the test suite, and keeps the span output in the transcript.

The pull request carries the version reasoning and the proof, so the person who reviews it does not have to rebuild the environment to believe it. When the choice of versions is wrong for an app on an older Flask, the lock step fails in the run, not in production.

## Frequently asked questions

### Will tracing be on by default after the merge?

No. `init_telemetry` returns at once unless `OTEL_EXPORTER_OTLP_ENDPOINT` is set, following the same empty-means-environment convention `CTFd/config.ini` already uses, so a deployment that sets nothing behaves as before. Setting the endpoint on the container turns it on.

### Does it work with gevent workers?

Yes, provided monkey patching happens before the OpenTelemetry modules are imported, which `wsgi.py` and `serve.py` already guarantee by patching before importing `create_app`. The test suite does not patch, and the test still passes because the instrumentation does not depend on it.

### Why does the change touch requirements.txt and uv.lock?

Because `make requirements` generates `requirements.txt` from `uv.lock`, and `lint.yml` fails when the two differ. The agent edits `pyproject.toml`, runs `uv lock` and `make requirements`, and commits all three, which is what the Makefile comment asks for.

### What about the plugins under CTFd/plugins?

They are loaded by `init_plugins` after `init_telemetry`, so their routes are instrumented like the core blueprints. A plugin that installs its own `requirements.txt` in the Dockerfile is not changed; if one of them pins a conflicting package, the lock step reports it and the pull request says so.

## More Flask jobs

- [Rate Limit Password Reset in a Flask App from a Linear Issue](https://getrush.ai/run/add-password-reset-rate-limit/flask/)
- [Add Rate Limiting to a Flask API](https://getrush.ai/run/add-rate-limiting/flask/)
- [Add Structured Logging to a Flask App](https://getrush.ai/run/add-structured-logging/flask/)

## The same job on other stacks

- [Add OpenTelemetry Tracing to a Gin API](https://getrush.ai/run/add-opentelemetry/gin/)
- [Add OpenTelemetry Tracing to a Go Service](https://getrush.ai/run/add-opentelemetry/go/)
- [Add OpenTelemetry Tracing to GORM Queries in a Go Service](https://getrush.ai/run/add-opentelemetry/gorm/)

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