fix(prometheus)!: default group_path to True to bound metric cardinality#4925
Merged
provinzkraut merged 3 commits intoJul 16, 2026
Merged
Conversation
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 litestar-org#4891
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4925 +/- ##
=======================================
Coverage 67.30% 67.30%
=======================================
Files 293 293
Lines 15230 15230
Branches 1728 1728
=======================================
Hits 10251 10251
Misses 4832 4832
Partials 147 147 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
provinzkraut
approved these changes
Jul 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Fixes #4891.
PrometheusMiddlewarerecords thepathmetric label from the raw requestpath by default. On a route with path parameters, every distinct value seen
in traffic becomes a new time series, so the metric set grows without bound
as traffic hits distinct parameter values, for example
/users/1,/users/2,/users/3, ... each get their own series.group_path=Truealready avoids this by using the route template(
/users/{user_id}) instead of the raw path. The mechanics of that optionwere made robust in #3533, #3687 and #3784. The remaining gap was that the
safe behavior was opt-in, so users hit the cardinality trap silently by
using the default.
Fix
Flip the default to
True. Raw-path behavior stays fully available viagroup_path=Falsefor anyone who wants it. Also updated the docs example'slocal default to match, so the snippet shown in the Prometheus docs page
reflects the new default rather than silently diverging from it.
How was this tested
Added two tests in
tests/unit/test_plugins/test_prometheus.py:PrometheusConfig().group_path is Truesingle
path="/users/{user_id}"series, not three separate raw-pathseries
Both fail on
main(raw paths leak through) and pass with this change.Also ran the reproduction script from the issue directly:
With this change, calling
PrometheusConfig()with no arguments nowproduces the
group_path=Trueresult above instead of theFalseone.Full suite:
tests/unit/test_plugins/andtests/examples/test_contrib/prometheus/pass (491 tests), no existing test asserted raw-path grouping since none of them use parameterized routes.📚 Documentation preview 📚: https://litestar-org.github.io/litestar-docs-preview/4925