Specify MeterProvider configurable cardinality limits

CHANGELOG.md

@@ -13,6 +13,11 @@ release.
 
 ### Metrics
 
+- Recommended limits applied by default at the MetricProvider level to protect
+  metrics pipelines against excessive data production from a single
+  instrumentation library or instrument.
+  ([#2960](https://github.com/open-telemetry/opentelemetry-specification/pull/2960))
+
 ### Logs
 
 ### Resource
@@ -134,6 +139,10 @@ release.
   "base2_exponential_bucket_histogram". Mark exponential histogram data model and
   base2 exponential histogram aggregation as stable.
   ([#3041](https://github.com/open-telemetry/opentelemetry-specification/pull/3041))
+- Recommended limits applied by default at the MetricProvider level to protect
+  metrics pipelines against excessive data production from a single
+  instrumentation library or instrument.
+  ([#2960](https://github.com/open-telemetry/opentelemetry-specification/pull/2960))
 
 ### Logs
 

spec-compliance-matrix.md

@@ -100,6 +100,7 @@ formats is required. Implementing more than one format is optional.
 | The API provides a way to set and get a global default `MeterProvider`.                                                                                                | X        | +   | +    | +   | +      |      |        | +   |      | +   | -    |       |
 | It is possible to create any number of `MeterProvider`s.                                                                                                               | X        | +   | +    | +   | +      |      |        | +   |      | +   | +    |       |
 | `MeterProvider` provides a way to get a `Meter`.                                                                                                                       |          | +   | +    | +   | +      |      |        | +   |      | +   | -    |       |
+| `MeterProvider` provides a way to set cardinality limits.                                                                                                              | X        |     |      |     |        |      |        |     |      |     |      |       |
 | `get_meter` accepts name, `version` and `schema_url`.                                                                                                                  |          | +   | +    | +   | +      |      |        | +   |      | +   | -    |       |
 | `get_meter` accepts `attributes`.                                                                                                                                      |          |     |      |     |        |      |        | +   |      |     |      |       |
 | When an invalid `name` is specified a working `Meter` implementation is returned as a fallback.                                                                        |          | +   | +    | +   | +      |      |        |     |      | +   | -    |       |

specification/metrics/sdk.md

@@ -32,6 +32,8 @@ linkTitle: SDK
   * [Observations inside asynchronous callbacks](#observations-inside-asynchronous-callbacks)
   * [Resolving duplicate instrument registration conflicts](#resolving-duplicate-instrument-registration-conflicts)
 - [Attribute limits](#attribute-limits)
+- [Cardinality limits](#cardinality-limits)
+  * [Specific cardinality limits](#specific-cardinality-limits)
 - [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
   * [Built-in ExemplarFilters](#built-in-exemplarfilters)
@@ -75,6 +77,12 @@ metrics produced by any `Meter` from the `MeterProvider`. The [tracing SDK
 specification](../trace/sdk.md#additional-span-interfaces) has provided some
 suggestions regarding how to implement this efficiently.
 
+A `MeterProvider` SHOULD provide a way to specify the configurable
+[cardinality limits](#cardinality-limits) to be applied to `Meter`
+instances.  SDKs that support configurable limits MUST provide an
+option to configure the default limits to be applied to all `Meter`
+instances by default.
+
 ### MeterProvider Creation
 
 The SDK SHOULD allow the creation of multiple independent `MeterProvider`s.
@@ -597,6 +605,65 @@ Attributes which belong to Metrics are exempt from the
 time. Attribute truncation or deletion could affect identity of metric time
 series and the topic requires further analysis.
 
+## Cardinality limits
+
+**Status**: [Experimental](../document-status.md)
+
+MeterProviders SHOULD support being configured with limits to be
+applied to individual metric instruments.  This mechanism supports
+protecting metrics pipelines from excessive data production in cases
+when the number of timeseries produced by application code grows
+large, which can happen due to several factors.
+
+Whether because of single attributes having many distinct values or
+because of combinatorial expansion among many attributes, these limits
+help protect the overall system from individual sources of excessive
+metrics instrumentation.
+
+Implementations may take unique approach to managing concurrency in
+the OTel API, therefore we cannot prescribe how to evaluate when the
+limit is reached.  The requirements for the implementation are:
+
+- An instrument with no configured views SHOULD NOT implement
+  cardinality limits.
+- An instrument with one or more configured views SHOULD detect that
+  the limit was reached before or during the next collection event (by
+  any Reader).
+- An instrument is NOT REQUIRED to be remove stale timeseries (e.g.,
+  exclude zero-valued sums from consideration) before evaluating the
+  cardinality limit.
+
+When the limit is reached by an the individual metric instrument,
+subsequent new timeseries created for that instrument will have their
+complete attribute set replaced by a single-attribute named `overflow`
+with value `true`.
+
+The implementation is permitted to evaluate the cardinality limit at a
+time when it is convenient.  Implementations are NOT REQUIRED to
+exactly meet the cardinality limit when it is reached, because that
+implies an unwanted degree of synchronization.  Implementations MAY
+exceed the limit due to the effects of concurrency.  Implementations
+SHOULD NOT allow unchecked cardinality growth between collection
+events.
+
+Concerning the synchronous instruments, the implementation of
+cardinality limits is NOT REQUIRED to ensure that metric API events
+are mapped uniquely onto a single timeseries when the instrument has
+reached its cardinality limit.  All that is required is that every
+metric event is aggregated in exactly one timeseries.
+
+### Specific cardinality limits
+
+The SDKs that support cardinality limits MUST support the configuration and enforcement of the following limits.
+
+- The number of timeseries per instrument, with a RECOMMENDED default value 2000.
+
+All SDKs MUST NOT support the configuration or enforcement of any limit not listed above.
+
+SDKs SHOULD NOT support the configuration of unlimited limits.  There is no unset
+value for this configurable limit.  Users that wish to configure
+"unlimited" cardinality should instead configure a very large limit.
+
 ## Exemplar
 
 **Status**: [Feature-freeze](../document-status.md)