All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading