oss_11_m1_metric_cardinality_limit

[ocelotl]

Implements M1 (base layer) of metric cardinality limits — Linear OSS-11, finding M1–M3.

Problem: Cardinality limits are entirely unimplemented — _ViewInstrumentMatch inserts every distinct attribute set unbounded, with no otel.metric.overflow overflow series, so an attribute explosion grows memory without limit.

Scope of this issue (M1 only): base aggregation_cardinality_limit (default 2000) enforced in _ViewInstrumentMatch.consume_measurement, routing overflow into a single {"otel.metric.overflow":"true"} series. M2 (per-MetricReader default) and M3 (per-View override) remain and will be tracked as their own stacked issues per the Linear note.

Branch / worktree: oss_11_m1_metric_cardinality_limit

Linear issue: https://linear.app/dash0/issue/OSS-11/m1-m3-metric-cardinality-limits-base-per-reader-per-view

[ocelotl]

🔒 Internal (dash0) — not for upstream.

Tracking for metric cardinality limit — M1 (base layer).

• Linear: https://linear.app/dash0/issue/OSS-11/m1-m3-metric-cardinality-limits-base-per-reader-per-view (findings M1–M3; this issue = M1 only)
• Slug / branch / worktree: oss_11_m1_metric_cardinality_limit
• Fix commit: 256db0546 (adopted from the former m1_fix worktree, re-homed to convention)
• PR: oss_11_m1_metric_cardinality_limit #17
• Validation: scope contained to metrics SDK + tests + changelog; cardinality test 3 passed; full metrics suite 306 passed.
• Remaining: M2 (per-MetricReader default) and M3 (per-View override) to follow as stacked issues/PRs.

[ocelotl]

📣 Public-facing draft — to be opened upstream in open-telemetry/opentelemetry-python. No internal references; copy verbatim.

Title: Metrics SDK: enforce an aggregation cardinality limit with an overflow series

Summary

The metrics SDK does not implement cardinality limits. _ViewInstrumentMatch allocates a new aggregation for every distinct attribute set with no upper bound and no otel.metric.overflow overflow series, so an attribute-value explosion (e.g. an unbounded label like a user id or URL) grows memory without limit. This is a long-standing gap (feature request open for ~4 years).

Evidence

opentelemetry-sdk/.../metrics/_internal/_view_instrument_match.py inserts each new attribute set into self._attributes_aggregation unconditionally in consume_measurement. A grep for cardinality / overflow across the metrics SDK returns zero hits.

Spec

specification/metrics/sdk.md ("Cardinality limits") defines a default aggregation cardinality limit of 2000 per metric, and requires that once the limit is reached, further attribute sets are folded into a single overflow series identified by the attribute {"otel.metric.overflow": true}. The total number of exported points for the metric must not exceed the limit (one slot is reserved for the overflow series).

Reference implementations

Go: sdk/metric/pipeline.go, config.go. Java: SynchronousMetricStorage / AsynchronousMetricStorage, CardinalityLimitSelector.

Proposed fix (this change — base layer)

Enforce the default limit (2000) in _ViewInstrumentMatch.consume_measurement: once the number of tracked attribute sets would exceed limit - 1, route any previously-unseen attribute set into a single {"otel.metric.overflow": true} series instead of allocating a new one, and log a warning once when overflow first occurs.

Follow-ups (separate changes)

• Per-MetricReader default cardinality limit.
• Per-metric override via View.