Add prometheus-fastapi-instrumentator for HTTP metrics

forgejo_admin commented

2026-03-14 18:57:44 +00:00

Owner

Lineage

plan-pal-e-platform → Phase 4 (Dashboard) — prerequisite for golden signals dashboard

Repo

forgejo_admin/pal-e-docs

User Story

As a platform operator
I want real HTTP request metrics from pal-e-docs
So that the golden signals dashboard can display latency, traffic, errors, and saturation

Context

The current /metrics endpoint in routes/health.py is a stub that returns only pal_e_docs_up 1. We need real HTTP request instrumentation to power the Grafana dashboard being created in pal-e-platform.

prometheus-fastapi-instrumentator is a well-maintained library that automatically instruments FastAPI apps with:

http_request_duration_seconds histogram (method, status, handler labels)
http_requests_total counter
http_response_size_bytes histogram
Standard Prometheus text format output

The app already has prometheus-client>=0.20 as a dependency. The instrumentator builds on top of it.

File Targets

Files to modify:

src/pal_e_docs/main.py — add instrumentator initialization and middleware
src/pal_e_docs/routes/health.py — replace stub /metrics endpoint with prometheus client generate_latest() output
pyproject.toml — add prometheus-fastapi-instrumentator dependency

Files NOT to touch:

Any route files besides health.py
Database models or migrations
Test files (no new tests needed — instrumentator is middleware, tested by its own library)

Acceptance Criteria

/metrics returns Prometheus text format with http_request_duration_seconds histogram
/metrics returns http_requests_total counter with method/status/handler labels
/metrics still includes pal_e_docs_up 1 custom gauge
/healthz still returns {"status": "ok"}
The instrumentator excludes /healthz and /metrics from instrumentation (avoid recursion)
App starts successfully with the new middleware

Test Expectations

Existing tests pass: pytest tests/ -v
Manual: curl localhost:8000/metrics returns Prometheus format with HTTP histograms
Run command: cd ~/pal-e-docs && source .venv/bin/activate && pytest tests/ -v

Constraints

Use prometheus-fastapi-instrumentator (not manual prometheus_client instrumentation) — it's the standard approach for FastAPI
Exclude health/metrics paths from instrumentation to avoid noise
Keep the existing pal_e_docs_up gauge as a custom metric alongside the auto-instrumented ones
The /metrics endpoint must return text/plain content type (Prometheus scrape format)

Checklist

PR opened
Tests pass
No unrelated changes

plan-pal-e-platform — dashboard depends on these metrics
project-page-pal-e-docs — project page

### Lineage `plan-pal-e-platform` → Phase 4 (Dashboard) — prerequisite for golden signals dashboard ### Repo `forgejo_admin/pal-e-docs` ### User Story As a platform operator I want real HTTP request metrics from pal-e-docs So that the golden signals dashboard can display latency, traffic, errors, and saturation ### Context The current `/metrics` endpoint in `routes/health.py` is a stub that returns only `pal_e_docs_up 1`. We need real HTTP request instrumentation to power the Grafana dashboard being created in pal-e-platform. `prometheus-fastapi-instrumentator` is a well-maintained library that automatically instruments FastAPI apps with: - `http_request_duration_seconds` histogram (method, status, handler labels) - `http_requests_total` counter - `http_response_size_bytes` histogram - Standard Prometheus text format output The app already has `prometheus-client>=0.20` as a dependency. The instrumentator builds on top of it. ### File Targets Files to modify: - `src/pal_e_docs/main.py` — add instrumentator initialization and middleware - `src/pal_e_docs/routes/health.py` — replace stub `/metrics` endpoint with prometheus client `generate_latest()` output - `pyproject.toml` — add `prometheus-fastapi-instrumentator` dependency Files NOT to touch: - Any route files besides `health.py` - Database models or migrations - Test files (no new tests needed — instrumentator is middleware, tested by its own library) ### Acceptance Criteria - [ ] `/metrics` returns Prometheus text format with `http_request_duration_seconds` histogram - [ ] `/metrics` returns `http_requests_total` counter with method/status/handler labels - [ ] `/metrics` still includes `pal_e_docs_up 1` custom gauge - [ ] `/healthz` still returns `{"status": "ok"}` - [ ] The instrumentator excludes `/healthz` and `/metrics` from instrumentation (avoid recursion) - [ ] App starts successfully with the new middleware ### Test Expectations - [ ] Existing tests pass: `pytest tests/ -v` - [ ] Manual: `curl localhost:8000/metrics` returns Prometheus format with HTTP histograms - Run command: `cd ~/pal-e-docs && source .venv/bin/activate && pytest tests/ -v` ### Constraints - Use `prometheus-fastapi-instrumentator` (not manual prometheus_client instrumentation) — it's the standard approach for FastAPI - Exclude health/metrics paths from instrumentation to avoid noise - Keep the existing `pal_e_docs_up` gauge as a custom metric alongside the auto-instrumented ones - The `/metrics` endpoint must return `text/plain` content type (Prometheus scrape format) ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `plan-pal-e-platform` — dashboard depends on these metrics - `project-page-pal-e-docs` — project page