fix(prometheus)!: default group_path to True to bound metric cardinality (#4925)

fix(prometheus): default group_path to True to bound metric cardinality

PrometheusMiddleware recorded the raw request path as the path metric
label. On a route with path parameters, every distinct value seen in
traffic became a new time series, so the metric set grew without bound.

group_path=True already avoided this by using the route template
instead of the raw path, but it was opt-in, so users hit the
cardinality trap silently by default.

Flip the default. Raw-path behavior stays available via
group_path=False for anyone who wants it.

Fixes #4891

Author: Bishwas-py

docs/examples/plugins/prometheus/using_prometheus_exporter.py

@@ -2,7 +2,7 @@
 from litestar.plugins.prometheus import PrometheusConfig, PrometheusController
 
 
-def create_app(group_path: bool = False) -> Litestar:
+def create_app(group_path: bool = True) -> Litestar:
     # Default app name and prefix is litestar.
     prometheus_config = PrometheusConfig(group_path=group_path)
 

litestar/plugins/prometheus/config.py

@@ -52,7 +52,7 @@ class PrometheusConfig:
     middleware_class: type[PrometheusMiddleware] = field(default=PrometheusMiddleware)
     """The middleware class to use.
     """
-    group_path: bool = field(default=False)
+    group_path: bool = field(default=True)
     """Whether to group paths in the metrics to avoid cardinality explosion.
     """
 

tests/unit/test_plugins/test_prometheus.py

@@ -10,6 +10,7 @@
 
 from litestar import get, post, websocket_listener
 from litestar.exceptions import HTTPException, NotAuthorizedException, PermissionDeniedException
+from litestar.params import FromPath
 from litestar.plugins.prometheus import PrometheusConfig, PrometheusController, PrometheusMiddleware
 from litestar.status_codes import HTTP_200_OK
 from litestar.testing import create_test_client
@@ -99,6 +100,31 @@ def handler_error() -> dict:
         )
 
 
+def test_prometheus_group_path_defaults_to_true() -> None:
+    assert PrometheusConfig().group_path is True
+
+
+def test_prometheus_group_path_default_uses_route_template_for_parameterized_routes() -> None:
+    config = create_config()
+
+    @get("/users/{user_id:int}")
+    def get_user(user_id: FromPath[int]) -> dict:
+        return {"user_id": user_id}
+
+    with create_test_client([get_user, PrometheusController], middleware=[config.middleware]) as client:
+        for user_id in range(1, 4):
+            client.get(f"/users/{user_id}")
+        metrics = client.get("/metrics").content.decode()
+
+        assert (
+            """litestar_requests_total{app_name="litestar",method="GET",path="/users/{user_id}",status_code="200"} 3.0"""
+            in metrics
+        )
+        assert 'path="/users/1"' not in metrics
+        assert 'path="/users/2"' not in metrics
+        assert 'path="/users/3"' not in metrics
+
+
 def test_prometheus_middleware_configurations() -> None:
     labels = {"foo": "bar", "baz": lambda a: "qux"}