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

@@ -99,6 +99,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

@@ -31,6 +31,7 @@ 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)
 - [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
   * [ExemplarReservoir](#exemplarreservoir)
@@ -70,6 +71,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.
+
 ### Meter Creation
 
 New `Meter` instances are always created through a `MeterProvider`
@@ -586,6 +593,48 @@ 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 metrics produced from a single metric instrument.  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.
+
+When the limit is reached by an the individual metric instrument, the
+entire batch of metrics for the instrument MUST be dropped and an
+error reported to the user indicating:
+
+- Detail about the limit that was exceeded (e.g., the library name and
+  version, the instrument, and the configured limit).
+- Recommend the user to configure a [View](#view) that filters the
+  offending instrument to limit cardinality or otherwise correct the problem.
+
+Note that limit expressed here refers to exported data for a single
+instrument and collection interval.  The number of timeseries referred
+to here corresponds with the number of distinct data points produced
+by the instrument over one collection interval.
+
+Under some circumstances, depending on the configured aggregation
+temporality, the MeterProvider may be able to recover after these
+limits are reached.
+
+### Specific cardinality limits
+
+There is only one configurable limit: the number of timeseries per
+instrument, with recommended default value 2000.
+
+SDKs SHOULD NOT support unlimited cardinality.  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)