[Editorial] clarify cardinality limit

[reyang]

The current spec is misleading IMO "A cardinality limit is the hard limit on the number of metric streams that can be collected". It should be the limit of cardinality for a given metric.

[MrAlias]

A metric stream is defined by an attribute set:

The Metric object contains individual streams, identified by the set of Attributes. Within the individual streams, points are identified by one or two timestamps, details vary by data point type.

The cardinality limit seems to apply to these streams, not the points which are defined by timestamps.

[reyang]

A metric stream is defined by an attribute set:

The Metric object contains individual streams, identified by the set of Attributes. Within the individual streams, points are identified by one or two timestamps, details vary by data point type.

The cardinality limit seems to apply to these streams, not the points which are defined by timestamps.

This is the confusing part https://github.com/open-telemetry/opentelemetry-specification/blob/c0491fb02ad3c454d9f1c2b6b8aa51a225cf2626/specification/metrics/sdk.md#configuration-1, it seems the data model and SDK spec use "metric stream" differently:

... has an aggregation_cardinality_limit value defined for the stream ...

The proto doesn't have a concept called stream https://github.com/open-telemetry/opentelemetry-proto/blob/0a743e76ddbb34d7d46a4c3ca8f9d7bdbb81e389/opentelemetry/proto/metrics/v1/metrics.proto#L89-L92, and it has "data points" which fits the cardinality limit scenario.

[MrAlias]

This is the confusing part https://github.com/open-telemetry/opentelemetry-specification/blob/c0491fb02ad3c454d9f1c2b6b8aa51a225cf2626/specification/metrics/sdk.md#configuration-1, it seems the data model and SDK spec use "metric stream" differently:

A 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.

The view link is in reference to:

https://github.com/open-telemetry/opentelemetry-specification/blob/c0491fb02ad3c454d9f1c2b6b8aa51a225cf2626/specification/metrics/sdk.md#view

Which talks about stream configuration. The term "stream" is defined:

Stream configuration are the parameters that define the metric stream a MeterProvider will use to define telemetry pipelines.

From this I infer that the SDK is defined in connection with the data-model definition of the term.

I'm not sure the proto definition has relevance here since it itself is mentioned to be defined in a different repository.

[MrAlias]

I'm on board with changing the term "metric stream" if we do so comprehensively, but without that this change is adding confusion given metric stream data points already have a distinct meaning.

[jmacd]

Thanks @reyang, I agree this is clarifying.

[MrAlias]

@reyang there seems to be precedence that our terms are defined in the data-model, not the proto: #2905 (comment)

[reyang]

I'm on board with changing the term "metric stream" if we do so comprehensively, but without that this change is adding confusion given metric stream data points already have a distinct meaning.

We discussed how to tackle this issue during the TC meeting, I've created a master issue #3866. This PR will be the first step (trying to break it down into smaller PRs).