feat(litestar): default prometheus group_path=True to bound cardinality

[lesnik512]

Problem

Litestar's PrometheusConfig defaults group_path=False, so the path metric label records the raw URL. Any route with path parameters then mints one time series per distinct value, growing the registry without bound. In production this shows up as steadily climbing memory / OOM on the scraping Prometheus. It hits users silently because it is the default.

Reproduced (isolated processes so the global prometheus_client registry doesn't leak series between runs), 5 requests to one parameterized route:

group_path=False: 5 distinct app path series -> ['/users/1', '/users/2', '/users/3', '/users/4', '/users/5']
group_path=True:  1 distinct app path series -> ['/users/{user_id}']

Change

• New LitestarConfig.prometheus_group_path: bool = True — the path label uses the route template (/users/{id}), bounding cardinality.
• LitestarPrometheusInstrument.bootstrap merges {"group_path": <field>, **prometheus_additional_params}. Precedence: prometheus_additional_params["group_path"] > prometheus_group_path > Litestar's own False. The merge (not a plain group_path= kwarg) avoids a "multiple values for keyword argument" crash for anyone already passing group_path via the dict — the documented workaround keeps working.
• FastAPI is untouched: prometheus_fastapi_instrumentator already labels by route template.

Compatibility

Behavior-changing default: the path label now holds the route template instead of the raw URL. Dashboards keyed on raw paths will shift. Revert per-app with prometheus_group_path=False.

Tests

TDD (red before green), unique route prefixes per test to avoid global-registry contamination:

• default -> path label is the route template, raw path absent
• prometheus_group_path=False -> raw path recorded
• prometheus_additional_params={"group_path": False} overrides the True default

just lint-ci clean (ruff + ty + planning validator); full suite 204 passed, 100% coverage.

Docs

• architecture/instruments.md — new "Prometheus path-label cardinality (Litestar)" subsection.
• docs/integrations/litestar.md — user-facing Prometheus section.

Upstream

Filed litestar-org/litestar#4891 proposing a warning (2.x) and default flip (next major). This PR gives lite-bootstrap users the safe default now, regardless of upstream.

🤖 Generated with Claude Code