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

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,83 @@ 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 a limit applied to
+individual metric instruments to control the maximum number of
+timeseries they can produce.  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.
+
+The specific limit, known as `MaxTimeseries` is configured as an
+option to the SDK during initialization.  In a metrics pipeline, every
+unqiue attribute set maps onto at most one unique
+[timeseries](./data-model.md#timeseries-model).  Although the limit
+controls the number of timeseries produced by a metrics pipeline, the
+SDKs SHOULD apply this limit as early as possible in the metrics
+pipeline to prevent buildup of memory.
+
+In this version of the specification, the SDK's `MaxTimeseries`
+setting limits all instruments and all instrumentation libraries
+equally; future versions of this specification may support finer-grain
+configuration of cardinality limits.
+
+Implementations details determine how concurrent API events will be
+handled.  To enforce the `MaxTimeseries` limit:
+
+- 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.
+- 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
+MAY defer the overflow test until the nexts collection cycle.
+
+When cardinality limits are reached, the implementation is REQUIRED
+eventually to stop creating new timeseries for the instrument.
+
+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.
+
+The SDK SHOULD try to maintain correctness for timeseries that existed
+before the overflow event.  However, if this feature requires
+substantial additional memory the SDK SHOULD prefer to export an
+arbitrary subset of timeseries when the limit is reached.
+
+### 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)