[concepts] Document metric cardinality limits and overflow#10630
Conversation
otelbot-docs
Bot
added
the
missing:docs-approval
svrnm
left a comment
svrnm
left a comment
There was a problem hiding this comment.
LGTM, thanks for moving this here, I think it would be great to have one more person who knows metrics well review this but then we are good to go:-)
otelbot-docs
Bot
added
ready-to-be-merged
There was a problem hiding this comment.
Pull request overview
Adds durable documentation for OpenTelemetry Metrics SDK cardinality capping behavior, including overflow semantics and consequences, and links it from the glossary so readers can find it from both conceptual and definitional entry points.
Changes:
- Adds a new “Cardinality limits” section to the Metrics concepts page explaining the cap, overflow datapoint semantics, and query-time undercounting behavior.
- Documents what the cap does not apply to (Resource and instrumentation scope) and how temporality impacts how quickly overflow is reached.
- Updates the glossary to refine the “Cardinality” entry and add a “Cardinality limit” term that links to the new concept section; updates cspell words for “undercount*”.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| content/en/docs/concepts/signals/metrics.md | Adds the new conceptual section explaining cardinality limits, overflow, and temporality implications. |
| content/en/docs/concepts/glossary.md | Refines the “Cardinality” definition and adds a “Cardinality limit” term linking to the new section. |
| .cspell/en-words.txt | Adds “undercount*” spellings used by the new docs. |
|
This PR has review comments. Review suggestions, whether from maintainers or automated reviewers, aren't always correct or required. Please evaluate each comment on its merits, then make sure each thread has a clear outcome. For example, link to the commit if you applied a suggestion, explain why it wasn't applied, or ask a follow-up question. Automation flags a PR for human review once every review thread has a reply or is marked as resolved. Status across open PRs is visible on the pull request dashboard. |
223d648 to
02cf8c8
Compare
@pellared has reviewed, so I think this can be merged now. |
|
thank you @pellared for review and thank you for writing this @cijothomas ! |
Adds a Cardinality limits section to the metrics concept page covering: what the cardinality limit is, the default of 2000, the
otel.metric.overflow=trueoverflow data point, the three key properties (no measurements lost, bounded memory, observable overflow), the query-time undercounting consequence (including how a low-cardinality attribute likesuccess=falsebecomes unreliable once its combination overflows), what the limit does not apply to (Resource and instrumentation scope attributes), and how aggregation temporality affects overflow for synchronous instruments.Also expands the glossary: tightens the Cardinality entry and adds a Cardinality limit term linking to the new section.
This grows out of discussion on #9971 (cardinality blog post), where the suggestion was made to put this durable conceptual material in the core docs. A follow-up will trim that blog post to link here.