Metrics Cardinality
Metrics cardinality is the number of unique label-combination time series a metric produces — user ids and request paths multiply it into millions — the primary cost limit of metrics systems.
Definition
Each unique combination of label values creates one distinct time series. Cardinality is the count of these combinations per metric name. Labels like user id, session id, full URL, or container instance turn thousands of series into millions, inflating memory, query cost, and storage. High-cardinality context belongs in traces and logs; metrics labels should stay bounded.
Context and scope
Managed via label discipline, cardinality limits with drop-or-replace policies, and periodic cardinality audits in Prometheus, Mimir, VictoriaMetrics. The classic production incident is a new label exploding a fleet-wide metric.
Common misconceptions
- More labels mean better monitoring — labels partition the metric; each partition costs a series, and unbounded partitions cost the platform
- Cardinality limits are a tooling limitation — they are the economics of the data model; even infinite resources would make high-cardinality queries slow
- Hashing label values fixes cardinality — hashing preserves cardinality while destroying queryability — the worst of both
Anti-patterns
- Adding a user_id label to a request counter and creating millions of series within hours
- Labeling by full request path with embedded ids and exploding route-based series
- Ignoring cardinality dashboards until query timeouts and OOM crashes deliver the audit
Related concepts
Related examples
Authoritative source
What it is
A metric is not one number — it is one number per label combination. Cardinality is how many numbers you actually created. The gap between the intended metric and the produced series count is where monitoring platforms die.
How it works
Scraped targets expose series per label set; the server indexes every distinct combination in memory and writes each as storage. A counter with two labels of 100 values each is ten thousand series; adding an unbounded third label multiplies by its distinct count. Limits and relabeling rules drop or bucket offending labels at ingestion.
When to manage
Continuously: alert on per-metric series counts, review new labels like schema changes, and route genuinely high-cardinality questions to traces and logs, which store per-event context without pre-aggregation. A cardinality budget reviewed at design time is far cheaper than an outage discovered at scrape time.
Pitfalls
Cardinality explosions arrive through dependency upgrades — a library version label meets a fleet of pods. Exemplars provide the bridge: keep metrics bounded while linking to per-request traces. Bucketing labels — path templates instead of raw URLs, status classes instead of full messages — requires deliberate normalization early, or the raw label leaks in through one endpoint and spreads.