Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify the cardinality limit section #3593

Merged
merged 8 commits into from
Jul 14, 2023
47 changes: 26 additions & 21 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ linkTitle: SDK
* [Maintain the ideal scale](#maintain-the-ideal-scale)
* [Observations inside asynchronous callbacks](#observations-inside-asynchronous-callbacks)
* [Cardinality limits](#cardinality-limits)
+ [Configuration](#configuration-1)
+ [Overflow attribute](#overflow-attribute)
+ [Synchronous instrument cardinality limits](#synchronous-instrument-cardinality-limits)
+ [Asynchronous instrument cardinality limits](#asynchronous-instrument-cardinality-limits)
- [Meter](#meter)
Expand Down Expand Up @@ -704,19 +706,23 @@ given instrument before starting a subsequent round of collection.

**Status**: [Experimental](../document-status.md)

Views SHOULD support being configured with a cardinality limit to be
applied to all aggregators not configured by a specific view, specified
via `MetricReader` configuration.
SDKs SHOULD support being configured with a cardinality limit. A cardinality
limit is the hard limit on the number of metric streams that can be collected.

View configuration SHOULD support applying per-aggregation cardinality limits.
#### Configuration

The cardinality limit is taken as an exact, hard limit on the number
of data points that can be written per collection, per aggregation.
Each aggregation configured view MUST NOT output more than the
configured `aggregation_cardinality_limit` number of data points per
period.
The cardinality limit for an aggregation is defined one of three ways:

The RECOMMENDED default aggregation cardinality limit is 2000.
1. A [view](#view) with criteria matching the instrument an aggregation is
created for has an `aggregation_cardinality_limit` value defined for the
stream, that value SHOULD be used.
2. If there is no matching view, but the `MetricReader` defines a default
cardinality limit value based on the instrument an aggregation is created
for, that value SHOULD be used.
3. If none of the previous values are deinfed, the default value of 2000 SHOULD
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
be used.

#### Overflow attribute

An overflow attribute set is defined, containing a single attribute
`otel.metric.overflow` having (boolean) value `true`, which is used to
Expand All @@ -731,16 +737,15 @@ limit, as a result.

#### Synchronous instrument cardinality limits

Views of synchronous instruments with cumulative aggregation
temporality MUST continue to export the all attribute sets that were
observed prior to the beginning of overflow. Metric events
corresponding with attribute sets that were not observed prior to the
overflow will be reflected in a single data point described by (only)
the overflow attribute.
Aggregators for synchronous instruments with cumulative temporality MUST
continue to export the all attribute sets that were observed prior to the
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
beginning of overflow. Metric events corresponding with attribute sets that
were not observed prior to the overflow will be reflected in a single data
point described by (only) the overflow attribute.

Views of synchronous instruments with delta aggregation temporality
MAY choose an arbitrary subset of attribute sets to output to maintain
the stated cardinality limit.
Aggregators of synchronous instruments with delta aggregation temporality MAY
choose an arbitrary subset of attribute sets to output to maintain the stated
cardinality limit.

Regardless of aggregation temporality, the SDK MUST ensure that every
metric event is reflected in exactly one Aggregator, which is either
Expand All @@ -752,9 +757,9 @@ overflow.

#### Asynchronous instrument cardinality limits

Views of asynchronous instruments SHOULD prefer the first-observed
Aggregators of asynchronous instruments SHOULD prefer the first-observed
attributes in the callback when limiting cardinality, regardless of
aggregation temporality.
temporality.

## Meter

Expand Down
Loading