transparent-fastapi

Drop-in Prometheus metrics for FastAPI. One line of setup, no per-route changes, disciplined cardinality.

Why

FastAPI doesn't ship metrics, and the usual options leave gaps:

• Hand-rolled middleware is easy to start and easy to get wrong — raw URLs as labels turn /users/123 and /users/124 into separate time series, and a port scanner can balloon series count overnight.
• prometheus-fastapi-instrumentator covers HTTP nicely, but route-template grouping is opt-in and process-level signals (event-loop lag, threadpool saturation, BackgroundTasks) aren't in scope.

transparent-fastapi is the tool you reach for when you want one install(app) to give you HTTP metrics with safe-by-default cardinality, plus the runtime signals you need to debug "why is my async app slow" — event-loop lag, threadpool tokens, and BackgroundTasks outcomes — without per-route changes.

Install

pip install transparent-fastapi

Use

from fastapi import FastAPI
from transparent_fastapi import install

app = FastAPI()
install(app)

That's it. A /metrics endpoint is now exposed in Prometheus exposition format.

Call install(app) once, as early as possible after app = FastAPI(...). Any middleware you add afterwards (auth, CORS) wraps the metrics middleware, so route-handler latency isn't skewed by upstream concerns.

Compatibility: Python 3.10+, FastAPI 0.75+, asyncio (anyio default backend). Fully type-annotated — ships a py.typed marker.

Cardinality discipline

This is the whole point of the library — make it safe to leave running in production.

• Routes are FastAPI's path templates (/users/{id}), never raw URLs. /users/123, /users/124, /users/125 collapse into one series.
• Unmatched paths (port scans, vulnerability probes) collapse to route="<unmatched>" rather than leaking the raw path as a label.
• Methods are allowlisted (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS); anything else becomes OTHER.
• Status is the full numeric code ("200", "404"); fine-grained enough for "alert when 401 spikes vs 500 spikes" without exploding cardinality.

What it exports

Configuration

Two optional kwargs:

install(
    app,
    excluded_paths=["/health", "/readiness"],   # noisy probes don't pollute metrics
    background_task_metrics=True,                # default; opt-out of the BackgroundTasks patch
)

Useful queries

# Validation-failure rate by route — Pydantic 422s already live in the status label
sum by (route) (rate(http_requests_total{status="422"}[5m]))

# 5xx error ratio
sum(rate(http_requests_total{status=~"5.."}[5m])) /
  sum(rate(http_requests_total[5m]))

# p95 latency by route
histogram_quantile(0.95,
  sum by (route, le) (rate(http_request_duration_seconds_bucket[5m])))

# Threadpool saturation — non-zero means sync work is queuing
sum(threadpool_tasks_waiting)

# Background task backlog growth (positive = scheduling outpaces completion)
sum(rate(background_task_scheduled_total[1m]))
  - sum(rate(background_task_total[1m]))

# Process uptime in seconds
time() - process_start_time_seconds

Limitations

FastAPI(root_path=...) and app.include_router(router, prefix=...) are handled correctly — both produce clean, prefixed templates in the route label. A couple of app.mount(...) cases are worth knowing about:

• StaticFiles (and any Starlette Mount) records as route="<unmatched>". Starlette's Mount doesn't populate request.scope["route"] the way FastAPI's APIRoute does, so static-file requests share a single series with unmatched paths (port scans, typos). This is a feature for cardinality — a 100k-asset directory can't explode the time series — but it does mean static traffic isn't separately observable here. Per-asset metrics belong at the CDN / edge proxy.
• Mounted FastAPI sub-applications share series with top-level routes. app.mount("/api", sub_app) records traffic as route="/users/{user_id}", without the /api prefix. This is fine when you have one mount; two mounts of the same sub-app at different paths would collide on the same series. Prefer app.include_router(router, prefix="/api") for FastAPI-internal composition — its templates are baked with the prefix and stay distinct.

Local demo stack

The repo ships a docker-compose stack (app + Prometheus + Grafana with a provisioned dashboard) and locust load profiles under deploy/local/. From the project root:

docker compose -f deploy/local/docker-compose.yml up -d --build
deploy/local/scripts/deploy.sh status        # curl all three services
deploy/local/scripts/deploy.sh load-medium   # locust, realistic traffic mix

Grafana lands on http://localhost:3000 (admin/admin) with transparent-fastapi as the default dashboard. See deploy/local/CLAUDE.md for the full reference.

License

MIT