Cardinality in Metrics

TL;DR

Explanation

Each unique label combination = one time series. 100 routes × 5 methods × 10 status codes = 5000 series (fine). 100 routes × 1M user_ids = 100M series (crash). High-cardinality labels: user_id, request_id, URL with query params, IP address, session_id. Solutions: don't use high-cardinality fields as labels (they belong in logs/traces). Aggregate high-cardinality dimensions in application code before recording. Prometheus native histograms (v0.16+): improve cardinality for latency. Grafana Tempo/Honeycomb: handle high cardinality natively. Use Prometheus for low-cardinality aggregate metrics; logs/traces for high-cardinality detail.

Common Misconception

Why It Matters

Common Mistakes

• User ID or session ID as a Prometheus label.
• Full URL (including query params) as label — unbounded.
• Not auditing cardinality before adding new labels.

Code Examples

// HIGH cardinality — one series per user:
$histogram->labels([
    'user_id' => $userId, // Unbounded
    'url' => $request->fullUrl(), // Includes query params
])->observe($duration);

// LOW cardinality — bounded dimensions only:
$histogram->labels([
    'route' => $request->route()->getName(), // e.g. 'api.orders.show'
    'method' => $request->method(),
])->observe($duration);

// user_id → goes in logs and traces, not metrics

References

• ↗ https://www.robustperception.io/cardinality-is-key

Tags

Related Terms