Clarify MetricReader parameters and temporality controls

CHANGELOG.md

@@ -31,6 +31,10 @@ release.
 - Clarify that the periodic metric reader is the default metric reader to be
   paired with push metric exporters (OTLP, stdout, in-memory)
   ([#2379](https://github.com/open-telemetry/opentelemetry-specification/pull/2379)).
+- Allow Sum, Histogram, and ExponentialHistogram View Aggregations to
+  define the temporality to "cumulative", "delta", or "default", where
+  "default" is the default determined by the MetricExporter on a per-instrument basis.
+  ([#2404](https://github.com/open-telemetry/opentelemetry-specification/pull/2404)).
 
 ### Logs
 

specification/metrics/sdk.md

@@ -180,10 +180,15 @@ are the inputs:
     will be used by default (TODO: once the Hint API is available, the default
     behavior should respect the Hint if it is available).
   * The `aggregation` (optional) to be used. If not provided, the SDK MUST
-    apply a [default aggregation](#default-aggregation). If the aggregation
-    outputs metric points that use aggregation temporality (e.g. Histogram,
-    Sum), the SDK SHOULD handle the aggregation temporality based on the
-    temporality of each [MetricReader](#metricreader) instance.
+    apply a [default aggregation](#default-aggregation) configurable on a
+    per-instrument basis according to the [MetricReader](#metricreader) instance.
+  * The aggregation `temporality` (optional) to be used, which may be one of
+    "cumulative", "delta", or "default".  If the configured `aggregation` outputs
+    metric points that define aggregation temporality (e.g. Histogram,
+    Sum), then the SDK MUST export the View using the configured aggregation
+    temporality.  The "default" value means the SDK SHOULD set the default
+    aggregation temporality on a per-instrument basis according to the
+    [MetricReader](#metricreader) instance.
   * The `exemplar_reservoir` (optional) to use for storing exemplars.
     This should be a factory or callback similar to aggregation which allows
     different reservoirs to be chosen by the aggregation.
@@ -199,8 +204,10 @@ The SDK SHOULD use the following logic to determine how to process Measurements
 made with an Instrument:
 
 * Determine the `MeterProvider` which "owns" the Instrument.
-* If the `MeterProvider` has no `View` registered, take the Instrument and apply
-    the default configuration.
+* If the `MeterProvider` has no `View` registered, take the Instrument
+    and apply the default Aggregation and default Aggregation
+    Temporality according to the [MetricReader](#metricreader)
+    instance's `aggregation` and `temporality` properties by default..
 * If the `MeterProvider` has one or more `View`(s) registered:
   * For each View, if the Instrument could match the instrument selection
     criteria:
@@ -209,12 +216,10 @@ made with an Instrument:
       the name is already used by another View), provide a way to let the user
       know (e.g. expose
       [self-diagnostics logs](../error-handling.md#self-diagnostics)).
-  * If the Instrument could not match with any of the registered `View`(s), the
-    SDK SHOULD provide a default behavior. The SDK SHOULD also provide a way for
-    the user to turn off the default behavior via MeterProvider (which means the
-    Instrument will be ignored when there is no match). Individual
-    implementations can decide what the default behavior is, and how to turn the
-    default behavior off.
+  * If the Instrument could not match with any of the registered
+    `View`(s), the SDK SHOULD whether to use the default `aggregation`
+    and `temporality` according to the [MetricReader](#metricreader)
+    instance's `default_enabled` property.
 * END.
 
 Here are some examples:
@@ -637,12 +642,30 @@ measurements using the equivalent of the following naive algorithm:
 
 ## MetricReader
 
-`MetricReader` is an interface which provides the following capabilities:
+`MetricReader` is an SDK implementation object that provides the
+common configurable aspects of the OpenTelemetry Metrics SDK and
+determines the following capabilities:
 
-* Collecting metrics from the SDK.
+* Collecting metrics from the SDK on demand.
 * Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from
   the SDK.
 
+To construct a `MetricReader` when setting up an SDK, the caller
+SHOULD provide at least the following:
+
+* The `exporter` to use, which is a `MetricExporter` instance.
+* The default View `aggregation` (optional), a function of instrument kind.
+* The default View `temporality` (optional), a function of instrument kind.
+* The `default_enabled` option, which determines whether instruments
+  that do not match a configured `View` use Default `aggregation`
+  (i.e., enabled) or Drop `aggrgation` (i.e., disabled).
+
+The [MetricReader.Collect](#collect) method allows general-purpose
+`MetricExporter` instances to explicitly initiate collection, commonly
+used with pull-based metrics collection.  A common sub-class of
+`MetricReader`, the periodic exporting `MetricReader` SHOULD be provided
+to be used typically with push-based metrics collection.
+
 The SDK MUST support multiple `MetricReader` instances to be registered on the
 same `MeterProvider`, and the [MetricReader.Collect](#collect) invocation on one
 `MetricReader` instance SHOULD NOT introduce side-effects to other `MetricReader`
@@ -672,26 +695,6 @@ The SDK SHOULD provide a way to allow `MetricReader` to respond to
 idiomatic approach, for example, as `OnForceFlush` and `OnShutdown` callback
 functions.
 
-The SDK SHOULD provide a way to allow the preferred [Aggregation
-Temporality](./datamodel.md#temporality) to be specified for a `MetricReader`
-instance during the setup (e.g. initialization, registration, etc.) time. If the
-preferred temporality is explicitly specified then the SDK SHOULD respect that,
-otherwise use Cumulative.
-
-[OpenTelemetry SDK](../overview.md#sdk)
-authors MAY choose the best idiomatic design for their language:
-
-* Whether to treat the temporality settings as recommendation or enforcement.
-  For example, if the temporality is set to Delta, would the SDK want to perform
-  Cumulative->Delta conversion for an [Asynchronous
-  Counter](./api.md#asynchronous-counter), or downgrade it to a
-  [Gauge](./datamodel.md#gauge), or keep consuming it as Cumulative due to the
-  consideration of [memory
-  efficiency](./supplementary-guidelines.md#memory-management)?
-* Refer to the [supplementary
-  guidelines](./supplementary-guidelines.md#aggregation-temporality), which have
-  more context and suggestions.
-
 ### MetricReader operations
 
 #### Collect
@@ -736,7 +739,6 @@ a user-configurable time interval, and passes the metrics to the configured
 
 Configurable parameters:
 
-* `exporter` - the push exporter where the metrics are sent to.
 * `exportIntervalMillis` - the time interval in milliseconds between two
   consecutive exports. The default value is 60000 (milliseconds).
 * `exportTimeoutMillis` - how long the export can run before it is cancelled.
@@ -763,6 +765,12 @@ from `MetricReader` and start a background task which calls the inherited
 implement so that they can be plugged into OpenTelemetry SDK and support sending
 of telemetry data.
 
+Metric Exporters always have an _associated_ MetricReader.  Default
+behaviors of the OpenTelemetry Metric SDK are determined when
+registering Metric Exporters through their associated MetricReader.
+OpenTelemetry language implementations MAY support automatically
+configuring the [MetricReader](#metricreader) to use for an Exporter.
+
 The goal of the interface is to minimize burden of implementation for
 protocol-dependent telemetry exporters. The protocol exporter is expected to be
 primarily a simple telemetry data encoder and transmitter.
@@ -781,9 +789,6 @@ can run at different schedule, for example:
 * Exporter D is a pull exporter which reacts to another scraper over a named
   pipe.
 
-`MetricExporter` SHOULD provide a way to allow `MetricReader` to retrieve its
-preferred temporality.
-
 ### Push Metric Exporter
 
 Push Metric Exporter sends metric data it receives from a paired

specification/metrics/sdk_exporters/in-memory.md

@@ -6,16 +6,15 @@ In-memory Metrics Exporter is a [Push Metric
 Exporter](../sdk.md#push-metric-exporter) which accumulates metrics data in the
 local memory and allows to inspect it (useful for e.g. unit tests).
 
-If a language provides a mechanism to automatically configure a
-[MetricReader](../sdk.md#metricreader) to pair with the exporter (e.g., using
-the
-[`OTEL_METRICS_EXPORTER` environment variable](../../sdk-environment-variables.md#exporter-selection)),
-by default the exporter MUST be paired with a
-[periodic exporting MetricReader](../sdk.md#periodic-exporting-metricreader).
-
 In-memory Metrics Exporter MUST support both Cumulative and Delta
 [Temporality](../datamodel.md#temporality).
 
-In-memory Metrics Exporter MUST allow [Aggregation
-Temporality](../datamodel.md#temporality) to be specified, as described in
-[MetricExporter](../sdk.md#metricexporter).
+If a language provides a mechanism to automatically configure a
+[MetricReader](../sdk.md#metricreader) to pair with the associated
+exporter (e.g., using the [`OTEL_METRICS_EXPORTER` environment
+variable](../../sdk-environment-variables.md#exporter-selection)), by
+default:
+
+* the exporter MUST be paired with a [periodic exporting
+MetricReader](../sdk.md#periodic-exporting-metricreader).
+* the exporter MUST use Cumulative default aggregation temporality.

specification/metrics/sdk_exporters/otlp.md

@@ -6,31 +6,32 @@ OTLP Metrics Exporter is a [Push Metric
 Exporter](../sdk.md#push-metric-exporter) which sends metrics via the
 [OpenTelemetry Protocol](../../protocol/README.md).
 
-If a language provides a mechanism to automatically configure a
-[MetricReader](../sdk.md#metricreader) to pair with the exporter (e.g., using
-the
-[`OTEL_METRICS_EXPORTER` environment variable](../../sdk-environment-variables.md#exporter-selection)),
-by default the exporter MUST be paired with a
-[periodic exporting MetricReader](../sdk.md#periodic-exporting-metricreader).
-
 OTLP Metrics Exporter MUST support both Cumulative and Delta
-[Temporality](../datamodel.md#temporality).
-
-OTLP Metrics Exporter MUST allow [Aggregation
-Temporality](../datamodel.md#temporality) to be specified, as described in
-[MetricExporter](../sdk.md#metricexporter).
-
-If the temporality is not specified, OTLP Metrics Exporter SHOULD use Cumulative
-as the default temporality.
+[Aggregation Temporality](../datamodel.md#temporality).
 
 The exporter MUST provide configuration according to the [OpenTelemetry Protocol
 Exporter](../../protocol/exporter.md) specification.
 
-In addition, the exporter MUST provide the following configuration (note: this
-section will be merged to the [OpenTelemetry Protocol
-Exporter](../../protocol/exporter.md) specification once it reaches
-[Stable](../../document-status.md)):
+If a language provides a mechanism to automatically configure a
+[MetricReader](../sdk.md#metricreader) to pair with the associated
+Exporter (e.g., using the [`OTEL_METRICS_EXPORTER` environment
+variable](../../sdk-environment-variables.md#exporter-selection)),
+then by default:
+
+- the exporter MUST be paired with a [periodic exporting
+MetricReader](../sdk.md#periodic-exporting-metricreader).
+- the exporter MUST configure the default aggregation temporality on a
+  per-instrument basis using the
+  `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY` variable as described
+  below, otherwise the exporter MUST use Cumulative as the default
+  aggregation temporality for all instrument kinds.
+
+The `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY` environment variable
+(case-insensitive) defines the default aggregation temporality policy
+to use on the basis of instrument kind.  The recognized values are:
+
+| Value      | Definition                                                                                                                                             |
+|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| CUMULATIVE | Choose Cumulative aggregation temporality for all instrument kinds                                                                                     |
+| DELTA      | Choose Delta aggregation temporality for Counter and Histogram instruments (but choose Cumulative aggregation for UpDownCounter instruments) |
 
-| Description | Default | Env variable |
-| ----------- | ------- | ------------ |
-| The preferred output [Aggregation Temporality](../datamodel.md#temporality), either `CUMULATIVE` or `DELTA` (case insensitive) | `CUMULATIVE` | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY`

specification/metrics/sdk_exporters/stdout.md

@@ -6,20 +6,19 @@
 Exporter](../sdk.md#push-metric-exporter) which outputs the metrics to
 stdout/console.
 
-If a language provides a mechanism to automatically configure a
-[MetricReader](../sdk.md#metricreader) to pair with the exporter (e.g., using
-the
-[`OTEL_METRICS_EXPORTER` environment variable](../../sdk-environment-variables.md#exporter-selection)),
-by default the exporter MUST be paired with a
-[periodic exporting MetricReader](../sdk.md#periodic-exporting-metricreader).
-
 [OpenTelemetry SDK](../../overview.md#sdk) authors MAY choose the best idiomatic
 name for their language. For example, ConsoleExporter, StdoutExporter,
 StreamExporter, etc.
 
 "Standard output" Metrics Exporter MUST support both Cumulative and Delta
 [Temporality](../datamodel.md#temporality).
 
-"Standard output" Metrics Exporter MUST allow [Aggregation
-Temporality](../datamodel.md#temporality) to be specified, as described in
-[MetricExporter](../sdk.md#metricexporter).
+If a language provides a mechanism to automatically configure a
+[MetricReader](../sdk.md#metricreader) to pair with the associated
+exporter (e.g., using the [`OTEL_METRICS_EXPORTER` environment
+variable](../../sdk-environment-variables.md#exporter-selection)), by
+default:
+
+- the exporter MUST be paired with a [periodic exporting
+MetricReader](../sdk.md#periodic-exporting-metricreader).
+- the exporter MUST use Cumulative default aggregation temporality.