What Is Cardinality in Metrics? The Series Explosion Explained
Cardinality in metrics is the number of distinct time series a metric generates, driven by how many unique combinations of its label values exist.
Cardinality is the concept that most often blows up a metrics system, and the one beginners least expect. Every unique set of labels on a metric creates a separate time series to store and query. Add the wrong label and that count explodes from hundreds to millions, with serious cost and performance consequences.
What cardinality means
A metric with labels produces one time series per unique combination of label values. A request-count metric labeled by method and status code with a handful of each might be a few dozen series. Cardinality is simply that total count of distinct series, and it grows multiplicatively with each label dimension.
How it explodes
Trouble comes from high-variety labels. Add a user ID, a request ID, or a raw URL as a label, and each unique value creates its own series. A label with a million possible values multiplies your series count by a million. This is the cardinality explosion that overwhelms metrics backends.
Why high cardinality is costly
Each time series consumes memory and storage and must be indexed. As cardinality grows, ingestion slows, queries get expensive, and the monitoring system itself can fall over. High cardinality is the leading cause of metrics systems becoming slow, unreliable, or unaffordable.
Controlling cardinality
The discipline is to keep labels low-variety: use bounded, enumerable values like status code or region, and never put unbounded identifiers in metric labels. When you genuinely need per-entity detail, that belongs in logs or high-cardinality-friendly event tools, not in metrics.
Cardinality in CI/CD metrics
The same trap applies to pipeline metrics. Labeling a build metric by stable dimensions, repository, workflow, runner type, is fine; labeling it by commit SHA or run ID creates a new series for every build and explodes cardinality. Keep pipeline metric labels bounded and push unique identifiers into logs.
Key takeaways
- Cardinality is the count of unique time series from label combinations.
- Unbounded labels like IDs cause a cardinality explosion.
- High cardinality drives up cost and degrades metrics systems.
- Keep labels low-variety; put unique IDs in logs, not metrics.