Cardinalidade de métricas e boas práticas de rotulagem

Cardinality is the number of unique time series produced by a metric. Each distinct combination of a metric name and its label values is a separate series.

• http_requests_total{method="GET"} is one series
• Adding status="200" multiplies the count

Cardinality grows by the product of the number of values per label. Three methods times five status codes times ten endpoints equals 150 series for one metric.

Each series consumes memory, disk, and index space. Unbounded labels can explode a single metric into millions of series, slowing queries and crashing collectors.

• Memory pressure on the TSDB
• Slow dashboards and alerts
• Higher storage cost

Putting unbounded values like user IDs, request IDs, or full URLs into labels is the most common mistake. These create one series per unique value.

Good labels have a small, finite set of values.

• Bounded: method, status_class, region
• Unbounded: user_id, session_id, email

Keep unbounded data in logs or traces, not metric labels.

Reduce cardinality by bucketing values. Replace exact status codes with classes and template dynamic path segments.

Before adding a label, estimate its impact. Multiply the existing series count by the number of new label values.

When you query, aggregations like sum by (status_class) collapse series. Design labels so the dimensions you aggregate by are exactly the ones you need.

Most TSDBs let you cap cardinality.

• Prometheus: sample_limit per scrape
• OpenTelemetry: cardinality limit on aggregations
• Alert when series counts spike

If a noisy label slips in, drop or relabel it at ingestion rather than storing it.

Aim for a handful of bounded labels per metric. This example stays well under a few hundred series.

You learned that cardinality is the count of unique series, that labels multiply it, and that unbounded values like IDs must stay out of labels. Bucket and template values, estimate impact before adding labels, and enforce guardrails to keep metrics fast and cheap.