Before we can count combinations, we need to know what is being combined.

A metric is a number that describes the behaviour of a running system, measured again and again over time. How many requests did the server handle? How many items are waiting in the queue? How long did the checkout page take to respond? Each of these questions is answered with a number, and the number keeps changing as the system works. Collecting these numbers lets engineers draw graphs, set alerts, and notice trouble before customers do.

How OpenTelemetry captures metrics

OpenTelemetry is an open standard, supported by the Cloud Native Computing Foundation, that defines how applications produce telemetry data such as metrics, traces and logs. For metrics, your code uses a small set of tools called instruments. You pick the instrument that matches the kind of thing you are measuring, and then you record values through it.

Meet the attributes

A bare number is rarely enough. Knowing that the server handled one million requests is nice, but knowing that 900,000 were successful and 100,000 failed is far more useful. To make that possible, every measurement can carry attributes. An attribute is a simple key-value pair that describes the circumstances of the measurement: for example, the HTTP method is GET, the route is the checkout page, the status code is 200.

You may also hear these called labels (the word used by Prometheus, a popular monitoring system) or tags (used by some commercial tools). They all mean roughly the same thing. OpenTelemetry uses the word attributes, so we will use it throughout.

From measurements to data points to streams

Your application may record millions of measurements, but it does not send millions of numbers to the backend. Instead, a part of the OpenTelemetry software development kit (the SDK, which is the library running inside your application) aggregates them. Aggregating means combining many small values into one summary. A counter, for instance, simply adds up the values. A histogram counts how many values fell into each range.

The result of aggregation is a data point: one summary value for one unique set of attributes. All the data points that belong to one instrument (after any customisation) form a metric stream. Hold on to this idea, because the entire topic of cardinality lives right here: one data point exists for every unique set of attributes in a stream.

flowchart LR
  A["Your code records a measurement"] --> B["Instrument"]
  B --> C["SDK aggregation: one data point per unique attribute set"]
  C --> D["Metric stream"]
  D --> E["Exporter sends data"]
  E --> F["Collector or backend"]
        

Cardinality is simply the count of unique attribute combinations in a metric.

The word cardinality comes from mathematics, where it means the number of items in a set. In the metrics world, it means the number of different attribute combinations that have been reported for one metric. Because the SDK keeps a separate summary in memory for every unique combination, cardinality is the number that drives the memory cost of a metric.

A tiny worked example

Suppose you measure how long your web server takes to answer requests. You attach two attributes to every measurement. The first is the HTTP method, which can be GET or POST. The second is the status code, which in your small example can be 200 or 404. How many unique combinations can you see?

• GET with 200
• GET with 404
• POST with 200
• POST with 404

That is four combinations, so the cardinality of this metric stream is four. The SDK keeps four data points, the exporter sends four data points, and the backend stores four time series. Four is tiny and perfectly healthy.

What cardinality is not

Beginners often mix cardinality up with other numbers. It is worth separating them clearly, because each one answers a different question.

The order does not matter, the values do

An attribute set is a collection of pairs. Reporting method first and status second gives the same set as reporting status first and method second, so it is counted once. But the moment any single value is different, such as a new status code or a new route, you have a brand-new combination and a brand-new data point.

Attributes do not add up. They multiply, and that is where trouble begins.

If one attribute has 2 possible values and another has 2 possible values, you get 2 × 2 = 4 combinations. This is the multiplication rule, and it is the single most important idea for understanding cardinality. The theoretical maximum number of data points for a metric is the number of distinct values of the first attribute, multiplied by the number of distinct values of the second, multiplied by the third, and so on.

Watching the numbers grow

Let us follow a realistic web-service metric as a team keeps adding attributes with good intentions. Each row below adds one more detail to the same metric.

Look at how calm the first three rows are, and how violent the last one is. Method, route and status together give 2,000 combinations, which is manageable. Adding region and tier raises it to 24,000, which is still survivable for one metric. But adding a single user ID attribute turns a modest metric into a theoretical 2.4 billion data points. One careless attribute outweighed everything that came before it.

Theory versus reality

The multiplication gives you the upper bound, the most that could ever happen. In real life, not every combination occurs. Perhaps only 12 of your 40 routes ever return a 404, or only some regions serve some customer tiers. The actual cardinality is the count of combinations that really show up in recorded measurements. Still, the upper bound is a great way to reason about risk before you write any code, and a high-cardinality attribute like a user ID can get close to its upper bound surprisingly fast.

flowchart TD
  A["Method: 5 values"] --> D["x"]
  B["Route: 40 values"] --> D
  C["Status: 10 values"] --> D
  D --> E["2,000 data points"]
  E --> F["Add region: x 4 = 8,000"]
  F --> G["Add user ID: x 100,000 = 800 million"]
        

How to estimate cardinality before you ship

Not all attributes are equal. Learning to recognise the dangerous ones is a core skill.

An attribute’s cardinality is the number of different values it can take. Engineers loosely group attributes into low, medium, high and unbounded. These labels are not official thresholds. They are a mental shortcut, and what counts as “high” depends on your limit and your budget. A good test is to ask: can I list every possible value of this attribute on a single page? If yes, it is probably safe. If the list would fill a phone book, it is not.

A practical comparison

Not every label on a metric is chosen by the developer who wrote the recording line.

When you look at a metric in a dashboard, you see a set of labels. They look like one flat list, but they actually come from three different places inside OpenTelemetry. Knowing which is which helps you understand what the SDK limit protects and what it does not.

What the SDK limit actually covers

The SDK cardinality limit, which we meet in detail in Chapter 8, applies to the attributes your code supplies when it records measurements through the metrics API. Resource attributes do not count against it, because they are the same for every measurement from that process.

That does not mean resources are free. In your backend, every unique measurement attribute set is repeated for every resource that reports it. If one application runs on 200 pods, each pod has its own instance identity, so the backend sees 200 copies of every combination. A metric with 2,000 combinations per process can therefore become 400,000 series across the fleet. We will return to this fleet effect in Chapter 12.

High cardinality is rarely a bug that crashes something on day one. It is a slow leak that shows up as a surprising invoice or a sluggish dashboard.

It is tempting to think of a metric as a tiny, weightless thing. A single number sounds free. But the number is only free when it is alone. Every unique attribute combination turns into a separate piece of state that must be stored, moved, indexed and queried. Cardinality is therefore a cost multiplier that touches every stage of the metrics pipeline.

flowchart LR
  A["Application SDK: memory per data point"] --> B["Network: bytes per export"]
  B --> C["Collector: processing and memory"]
  C --> D["Backend: storage and indexing"]
  D --> E["Dashboards and alerts: query time"]
  E --> F["Your invoice"]
        

The five places you pay

Why it often hides until it hurts

Cardinality problems are sneaky because they depend on real traffic. During development, you test with a handful of users, so a user ID attribute looks harmless: only a few values appear. After launch, thousands of real users arrive, and the number of combinations rises with them. Some teams discover the problem only when a billing alert fires, a dashboard stops loading, or an application starts using much more memory than before.

How your metrics are reported over time changes how long each combination stays alive in memory.

When the SDK exports a metric, it has to decide what the numbers mean. There are two styles, called aggregation temporality. This sounds technical, but the idea is easy once you see it in everyday terms.

Why this matters for cardinality

Under cumulative temporality, a running total must be continuously reported for every combination ever seen since start-up. If a combination appeared once an hour ago and never again, the SDK still has to keep its total and keep reporting it. Memory is therefore tied to everything the process has ever seen, which means old, no-longer-used combinations keep taking space.

Under delta temporality, the SDK only needs to report combinations that received measurements during the current interval. A combination that stops appearing can drop out of memory and out of the next export. Memory is therefore tied to what is active right now rather than to the full history.

sequenceDiagram
  participant App as Application
  participant SDK as SDK
  participant Back as Backend
  App->>SDK: Measurements with attribute set A
  SDK->>Back: Interval 1 report: A
  App->>SDK: Measurements with attribute set B only
  SDK->>Back: Interval 2 delta report: B only
  SDK->>Back: Interval 2 cumulative report: A and B
        

The metrics SDK protects your application by refusing to track an unlimited number of combinations.

Because every unique combination consumes memory, an unbounded attribute could in the worst case make an application run out of memory. To prevent that, the OpenTelemetry metrics SDK enforces a cardinality limit: a maximum number of unique attribute combinations that it will track for each metric stream. The default value is 2000, and it can be changed through a View, which we cover in the next chapter.

What happens when the limit is reached

Once a metric stream has reached its limit, new unique combinations are not tracked individually. Instead, their measurements are folded into one special overflow data point. This point carries a single attribute, otel.metric.overflow, set to true. Every language implementation uses the same marker, so one query in your backend can detect overflow across all your services, whatever language they are written in.

flowchart TD
  A["Measurement arrives with attributes"] --> B{"Combination already tracked?"}
  B -- Yes --> C["Update its data point"]
  B -- No --> D{"Room left under the limit?"}
  D -- Yes --> E["Create a new data point"]
  D -- No --> F["Add to the overflow data point"]
        

What you keep and what you lose

The overflow design is deliberately gentle. Totals are preserved: the overflow point still adds up all the measurements that did not fit, so the metric’s overall sum stays correct. What you lose is detail. You can no longer say which route, user or tenant the folded measurements belonged to, because the overflow point has none of those attributes.

An important detail about what the limit covers

The limit applies to attributes supplied when recording measurements through the metrics API. Resource attributes, which describe the producing service, are not counted against it. That makes the limit a precise guard for the attributes your own code adds, which are the ones most likely to explode.

A View lets you reshape a metric inside the SDK without touching the code that records it.

A View is a rule you give the SDK that says how a particular instrument’s data should be presented. Views are a powerful feature because they separate two jobs that are often tangled together: the people writing instrumentation decide what to record, and the people operating the system decide what actually leaves the application. You can use a View without changing a single line of the code that records measurements.

What a View can do for cardinality

The power of removing an attribute

Dropping an attribute is the most effective way to reduce cardinality. Imagine a request metric carrying method, route, status and a noisy user-agent string. If you keep only method, route and status, all the user-agent variations collapse into the same data points. The totals stay exactly right, because the measurements are merged rather than discarded, and the number of data points can fall dramatically.

You cannot fix what you cannot see, so make overflow visible and watch the early warning signs.

The beauty of the shared overflow marker is that it turns a hidden problem into a searchable fact. Since every compliant SDK uses the same attribute, you can ask your backend a simple question: which metrics, from which services, have emitted an overflow data point recently? The answer is a ready-made list of metrics that need attention.

Early warning signs

If metrics cannot carry every detail, something else must. OpenTelemetry has three signals, and each has its own strength.

A common worry is: “But I really do need to know which user had the slow request.” That is a perfectly good need. The answer is not to push the detail into metrics, but to put it in the signal that was built to carry it. OpenTelemetry offers three main signals, and they work best as a team.

The two-step investigation

The limit protects one process. Your monitoring backend sees the whole fleet.

The SDK limit is enforced inside each running process, per metric stream. It is a guardrail for application memory, and it does its job well. But it does not cap the number of series that arrive in your backend, because many processes each send their own set of data points.

A fleet of one thousand pods, each allowed two thousand combinations, can in principle deliver up to two million series for a single metric. And with delta temporality, a leak of changing values can grow even larger over time in the backend, because new combinations keep appearing in different intervals while each individual process stays under its own limit.

Helpful habits at fleet scale

Teams keep making the same handful of mistakes, and the same handful of fixes keep working.

Healthy design patterns

Anti-patterns to avoid

Avoiding high cardinality is the default advice, but it is not a law of nature.

Sometimes an operational need is real. A platform that bills each of a few hundred business customers may genuinely need per-customer metrics. A service that supports a bounded number of devices may want one series per device. The guidance is not “never”, but “only on purpose”.

Four everyday situations show how these ideas play out.

flowchart TD
  A["Metric looks too expensive or overflows"] --> B["Find the attribute with the most values"]
  B --> C{"Is it really needed for decisions?"}
  C -- No --> D["Remove it with a View"]
  C -- Yes --> E{"Can it be grouped or bounded?"}
  E -- Yes --> F["Use template, class, tier or allow-list"]
  E -- No --> G["Move detail to traces or logs"]
        

A short checklist you can keep next to your editor.

Quick answers to the questions beginners ask most often.

No. Cardinality counts unique attribute combinations within one metric. You can have many metrics that are all tiny, or one metric that is huge.

Not by itself. A million measurements with identical attributes still produce a single data point. Cardinality grows only when new, different attribute combinations appear.

The default is 2000 unique attribute combinations per metric stream. It can be changed for a specific metric through a View.

You lose detail, not totals. Extra combinations are folded into a single overflow data point, so overall sums remain correct, but you can no longer tell which attributes those measurements had.

Look for data points carrying the attribute otel.metric.overflow set to true. All compliant SDKs use the same marker, so one query can find it across services.

No. The limit covers the attributes supplied with measurements through the metrics API. Resource attributes still multiply series in the backend across instances, so they matter for cost.

Delta is usually gentler, because inactive combinations can be released. Cumulative must keep reporting every combination seen since start. The right choice also depends on what your backend supports.

You can, but it usually hides the real problem and increases memory and cost. It is better to remove or bound the offending attribute and raise the limit only for a deliberate reason.

On traces and logs. Those signals are designed to carry detail for individual requests, while metrics are designed for summaries.

Only partly. It limits what each process tracks, but many processes together can still send far more series than any single limit suggests. Use Views, pipeline filtering and backend monitoring as well.

Support can vary by language and version. Check the documentation for your SDK, and watch process memory if you are unsure that a limit is applied.

Cardinality is the number of unique attribute combinations a metric carries, and it is the quiet force behind the memory, network, storage and query cost of your metrics. Attributes multiply rather than add, so one careless identifier can turn a small, healthy metric into an enormous one. OpenTelemetry protects applications with a default limit of 2000 combinations per metric stream, folding any extras into a clearly marked overflow data point so totals stay correct while detail is lost. That safety net is helpful, but it is not a full cost strategy, so good attribute design, Views, temporality awareness, fleet-level budgeting and overflow alerts all deserve a place in your toolkit. Keep metrics for trends and put the rich, per-request detail where it belongs: in traces and logs.