Cardinality

David Granzin By David Granzin

In observability, cardinality is the number of distinct values an attribute takes, and for a metric the number of distinct time series its attribute combinations produce.

Low and high cardinality

An attribute's cardinality is how many different values it takes. http.request.method has a handful: GET, POST, PUT, DELETE and a few more. http.response.status_code has a few dozen in practice. user.id has one value per user, so its cardinality grows with your business. http.request.id has a new value on every request and is unbounded.

"High cardinality" has no fixed threshold. It means "enough distinct values to matter for the system storing them", and that depends a great deal on whether the system stores metrics or events.

Why it matters for metrics

A metric stores one time series per distinct combination of attribute values. A request counter with 5 methods, 40 routes and 10 status codes can produce up to 2,000 series. Add user.id with 10,000 active users and the ceiling becomes 20 million. Each series is indexed and kept, gets a data point at every export, and in many products is billed. This is why a single attribute added to a metric can multiply its cost overnight.

The OpenTelemetry metrics SDK guards against runaway growth with a cardinality limit, 2,000 attribute combinations per metric by default. Past it, new combinations are folded into one series marked otel.metric.overflow=true. The metric cardinality guide covers how to find the attribute responsible and how to drop it with SDK views or the Collector.

Why it is fine for traces and logs

Spans and log records are stored one event at a time. A user.id attribute on a span adds a few bytes to that span and creates no new series. High-cardinality attributes are what make traces useful: "show me the slow checkout requests for customer acme" needs the customer ID on the span.

The practical rule: put bounded dimensions (route, method, status, region, version) on metrics, and put identifiers (user, tenant, order, request) on spans and logs. When a metric shows a problem, the spans carry the detail that explains it.

Common high-cardinality attributes

  • User, session, request and order IDs
  • Full URLs and paths with IDs in them, such as /orders/8812; use the route template /orders/{id}
  • Client IP addresses
  • Error messages that embed values; use an error type
  • Raw SQL statements
  • Pod names and container IDs, which change on every deploy

The semantic conventions already mark which attributes are safe on metrics, which is one reason to follow them.

Sources

今日、最初のトレースを。

SDKを追加し、OTLPエクスポーターをMapleに向ければトレースが届きます。

maple.dev:OpenTelemetryの上のオブザーバビリティ