Specify MeterProvider configurable cardinality limits

CHANGELOG.md

@@ -15,6 +15,10 @@ release.
 
 - Define Experimental MetricProducer as a third-party provider of metric data to MetricReaders.
   ([#2951](https://github.com/open-telemetry/opentelemetry-specification/pull/2951))
+- 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

@@ -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,57 @@ 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 Instrumentation Library Scope.  This
+mechanism supports protecting metrics pipelines from excessive da
+ta
+production, which is usually caused by a problem known as ["explosition
+of cardinality"](supplementary-guidelines.md#synchronous-example-cumulative-aggregation-temporality),
+in which the number of timeseries produced by application code exceeds a
+reasonable number.  These limits help protect the overall system from
+individual sources of excessive metrics instrumentation.
+
+When the limits are reached by an the individual instrumentation
+library scope, the entire batch of metrics for the scope 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 configured limit, the instruments of that library
+  ranked by cardinality).
+- Recommend the user to configure a [View](#view) that filters the
+  offending cardinality or drops selected instruments to correct the problem.
+
+Note that limits expressed here refer to exported data for a single
+collection cycle.  The number of timeseries referred to in each of
+these limits equals the number of distinct data points produced over
+one interval.
+
+Under some circumstances, depending on the configured aggregation
+temporality, the MeterProvider may be able to recover after these
+limits are reached.  In particular, for Synchronous instruments
+configured with Delta aggregation temporality, the MeterProvider
+SHOULD remove timeseries from memory when they become stale, making it
+possible to recover from an explosion of cardinality from one
+collection cycle to the next provided the application stops using
+excessive cardinality.  However, for MeterProviders that have
+Synchronous instruments configured with Cumulative aggregation
+temporality, once a limit is reached the MeterProvider SHOULD disable
+it for the remaining lifetime of the MeterProvider.
+
+The configurable limits are:
+
+1. The number of timeseries per instrument, with recommended default value 2000.
+2. The number of timeseries per instrumentation library scope, with recommended default value 2000.
+
+For both of these limits, the limit MAY be unset to indicate an
+unlimited configuration and the zero value is considered invalid.
+MeterProviders SHOULD NOT use an unlimited memory configuration by
+default.
+
 ## Exemplar
 
 **Status**: [Feature-freeze](../document-status.md)