← Back

OpenTelemetry Cardinality: Budget Your Metric Labels

Control OpenTelemetry metric cardinality with bounded attributes, useful views, and overflow monitoring while keeping enough context to diagnose real problems.

OpenTelemetry metric cardinality is a schema design problem before it becomes a storage bill. Each additional attribute invites another way to divide measurements. That division is useful only when someone can name the operational question it answers and bound the values it produces.

My default is to keep metrics suitable for aggregation, put detailed investigation context in appropriately controlled traces or logs, and review every new metric attribute as a long-lived interface.

Count combinations, not attribute names

The OpenTelemetry Metrics SDK specification defines cardinality in terms of distinct attribute combinations. It describes configurable limits, attribute filtering through views, and an overflow aggregation identified by otel.metric.overflow. SDK behavior and configuration support must be checked for the language and version in use. OpenTelemetry Metrics SDK.

Suppose a hypothetical metric records 8 operation types, 5 outcome classes, and 3 deployment regions. The simple maximum combination count is 8 × 5 × 3 = 120 if all combinations occur. Add 10,000 customer identifiers and that theoretical space becomes 1,200,000.

These numbers illustrate multiplication; they are not a backend cost estimate. Actual series counts depend on observed combinations, resource dimensions, metric type, export format, and the backend's data model. The arithmetic is still a useful design warning: an attribute that looks harmless in one request can dominate the aggregate.

Ask what the label lets you decide

For every proposed attribute, write an intended query and a bound:

AttributeUseful questionReview decision
Operation typeWhich supported operation is failing?Keep a documented finite set
Outcome classAre failures concentrated in one class?Normalize to known values
Raw URLWhich specific request failed?Prefer route template for metrics
Request identifierWhich single request was this?Keep out of ordinary metric dimensions

Prometheus guidance warns against labels with high or unbounded cardinality, using identifiers such as user IDs and email addresses as examples. It also recommends consistent metric naming and units. Prometheus metric and label naming.

The table above is my suggested review framework. A bounded customer tier might answer a capacity question more economically than individual customer IDs. That choice should be explicit, with any lost visibility documented.

Do not normalize away distinctions that the on-call team genuinely needs. If one operation has a different reliability promise, combining it into a generic “other” bucket can hide harm. The aim is a useful schema, not the smallest possible number of series.

Put controls near the source

Review instrumentation at creation time. Prefer a known route pattern over an arbitrary path, a fixed failure category over an exception message, and a documented operation name over dynamically generated text.

Use views or equivalent SDK configuration to retain only the attributes required for a metric stream. Then test emitted data from the actual SDK. A configuration that looks right in one language's documentation may not map directly to another implementation or version.

Collector-side transformations can help protect the backend, but I would not assume they eliminate costs already incurred inside the application. Inspect where the aggregation occurs and where attributes are removed. Controls should address the stage that is actually under pressure.

Make the default behavior visible when unexpected values arrive. Silently converting every unknown operation into a new label defeats the budget; silently dropping every unfamiliar value can conceal deployment mistakes. An explicit bounded “unknown” category plus a diagnostic signal is often a useful compromise.

Treat overflow as lost detail

An overflow aggregate is a protection mechanism with an observability trade-off. Once several distinct contexts share that aggregate, the detailed breakdown is no longer available in that metric stream. A healthy total can coexist with reduced diagnostic value.

I would alert or report on unexpected overflow according to its effect on the service's operational queries. Do not simply raise the limit until the signal disappears. Determine which attribute expanded, whether the expansion was intended, and whether the retained dimensions still answer the important questions.

A controlled test can generate synthetic values beyond the expected bound. Inspect the output, application memory behavior, collector load, and backend acceptance. Record what remains queryable after the limit is reached. This article proposes the exercise; it does not claim measured results for a particular SDK or backend.

Keep debugging context without making metrics a database

When an aggregate reveals a problem, responders may need individual examples. Design a path from the metric's bounded dimensions to traces or logs with appropriate access controls and retention. Detailed telemetry still needs cost and privacy review; moving an identifier between signals does not make it free or automatically appropriate.

Choose attributes based on incident workflows. If responders always ask for the deployment revision and operation type, make those available in the relevant telemetry model. If nobody can explain how an attribute helps a decision, remove it before it becomes a compatibility obligation.

Finally, assign ownership. A metric without an owner can accumulate labels through unrelated feature work until nobody knows which dashboards depend on them. Review schema changes alongside the queries and alerts they affect.

Start with the queries needed by the SLO policy and operational investigations such as connection-pool diagnosis. Keep only metric dimensions that help answer those questions with a bounded set of values.