Clarify reader / exporter relationship for temporality preference and…

… default aggregation (#4142)

Reviewing @dashpole's
[comments](#4124 (review))
on #4124, I realize that a key clarification is missing for the contract
between readers and exporters, and for the configuration of built-in
exporters.

We [state
that](/~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#metricreader)
MetricReaders should be constructed with:
- "The default output aggregation (optional), a function of instrument
kind. If not configured, the [default
aggregation](/~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#default-aggregation)
SHOULD be used."
- "The default output temporality (optional), a function of instrument
kind. If not configured, the Cumulative temporality SHOULD be used."

And for MetricExporters, we [state
that](/~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#metricexporter)
"The aggregation and temporality properties used by the OpenTelemetry
Metric SDK are determined when registering Metric Exporters through
their associated MetricReader."

But we don't connect the dots that the `aggregation` and `temporality`
options for the MetricReader should be obtained from a MetricExporter. I
think this is understood, since the whole reason these are configurable
at the MetricReader level is that MetricExporters and their associated
backends have different requirements around temporality and default
aggregation (especially in the case of base2 exponential histogram).

This PR clarifies that the MetricReader `aggregation` and `temporality`
options SHOULD come from the associated MetricExporter, NOT from the
caller.

Furthermore, because these are now clearly spelled out as preferences of
MetricExporter, I've updated all the built-in metric exporter
definitions to make expectations clear around what defaults and
configuration of `aggregation` and `temporality` should be supported.
This achieves the goals of #4124 in a more generic way.

| Exporter | default `aggregation` | `temporality` |
|---|---|---|
| Prometheus | configurable | always cumulative |
| OTLP | configurable | configurable |
| Standard Output | configurable | configurable |
| InMemory | configurable | configurable |

CHANGELOG.md

@@ -18,6 +18,11 @@ release.
 
 - Clarify prometheus exporter should have `host` and `port` configuration options.
   ([#4147](/~https://github.com/open-telemetry/opentelemetry-specification/pull/4147))
+- Clarify metric reader / metric exporter relationship for temporality
+  preference and default aggregation. Explicitly define configuration options
+  for temporality preference and default aggregation of built-in exporters, and
+  make default values explicit.
+  ([#4142](/~https://github.com/open-telemetry/opentelemetry-specification/pull/4142))
 
 ### Logs
 

specification/metrics/sdk.md

@@ -1221,12 +1221,12 @@ determines the following capabilities:
 * 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:
+To construct a `MetricReader` when setting up an SDK, at least the following
+SHOULD be provided:
 
 * The `exporter` to use, which is a `MetricExporter` instance.
-* The default output `aggregation` (optional), a function of instrument kind.  If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
-* The default output `temporality` (optional), a function of instrument kind.  If not configured, the Cumulative temporality SHOULD be used.
+* The default output `aggregation` (optional), a function of instrument kind. This function SHOULD be obtained from the `exporter`. If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
+* The output `temporality` (optional), a function of instrument kind. This function SHOULD be obtained from the `exporter`. If not configured, the Cumulative temporality SHOULD be used.
 * **Status**: [Development](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind.  If not configured, a default value of 2000 SHOULD be used.
 * **Status**: [Development](../document-status.md) - The [MetricFilter](#metricfilter) to apply to metrics and attributes during `MetricReader#Collect`.
 * Zero of more [MetricProducer](#metricproducer)s (optional) to collect metrics from in addition to metrics from the SDK.

specification/metrics/sdk_exporters/in-memory.md

@@ -10,8 +10,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).
 
-In-memory Metrics Exporter MUST support both Cumulative and Delta
-[Temporality](../data-model.md#temporality).
+In-memory Metrics Exporter MUST provide configuration to set
+the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
+instrument kind. This option MAY be named `temporality`, and MUST set
+temporality to Cumulative for all instrument kinds by default.
+
+In-memory Metrics Exporter MAY provide configuration to set
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST use
+the [default aggregation](../sdk.md#default-aggregation) by default.
 
 If a language provides a mechanism to automatically configure a
 [MetricReader](../sdk.md#metricreader) to pair with the associated

specification/metrics/sdk_exporters/otlp.md

@@ -12,8 +12,15 @@ OTLP Metrics Exporter is a [Push Metric
 Exporter](../sdk.md#push-metric-exporter) which sends metrics via the
 [OpenTelemetry Protocol](../../protocol/README.md).
 
-OTLP Metrics Exporter MUST support both Cumulative and Delta
-[Aggregation Temporality](../data-model.md#temporality).
+OTLP Metrics Exporter MUST provide configuration to influence
+the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
+instrument kind. This option MAY be named `temporality`, and MUST set
+temporality preference to Cumulative for all instrument kinds by default.
+
+OTLP Metrics Exporter MUST provide configuration to influence
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST set
+the [default aggregation](../sdk.md#default-aggregation) for all instrument kinds by default.
 
 The exporter MUST provide configuration according to the [OpenTelemetry Protocol
 Exporter](../../protocol/exporter.md) specification.
@@ -33,12 +40,12 @@ then by default:
 * The exporter MUST configure the default aggregation on the basis of instrument kind using
   the `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` variable as described below if it is implemented.
 
-## Additional Configuration
+## Additional Environment Variable Configuration
 
-| Name                                                       | Description                                                         | Default                     |
-|------------------------------------------------------------|---------------------------------------------------------------------|-----------------------------|
-| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`        | The aggregation temporality to use on the basis of instrument kind. | `cumulative`                |
-| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | The default aggregation to use for histogram instruments.           | `explicit_bucket_histogram` |
+| Name                                                       | Description                                                                                            | Default                     |
+|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|-----------------------------|
+| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`        | Configure the exporter's aggregation `temporality` option (see above) on the basis of instrument kind. | `cumulative`                |
+| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | Configure the exporter's `default_aggregation` option (see above) for Histogram instrument kind.   | `explicit_bucket_histogram` |
 
 The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` are:
 

specification/metrics/sdk_exporters/prometheus.md

@@ -38,6 +38,10 @@ A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT add
 There MUST be at most one `target` info metric exposed by an SDK
 Prometheus exporter.
 
+A Prometheus Exporter MUST set
+the [MetricReader](../sdk.md#metricreader) `temporality` as a function of
+instrument kind to be `cumulative` for all instrument kinds.
+
 ## Configuration
 
 A Prometheus Exporter SHOULD support a configuration option to set the host
@@ -48,6 +52,11 @@ A Prometheus Exporter SHOULD support a configuration option to set the port
 that metrics are served on. The option MAY be named `port`, and MUST be `9464` by
 default.
 
+A Prometheus Exporter SHOULD support a configuration option to set
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST use
+the [default aggregation](../sdk.md#default-aggregation) by default.
+
 A Prometheus Exporter MAY offer configuration to add resource attributes as metric attributes.
 By default, it MUST NOT add any resource attributes as metric attributes.
 The configuration SHOULD allow the user to select which resource attributes to copy (e.g.

specification/metrics/sdk_exporters/stdout.md

@@ -14,8 +14,15 @@ stdout/console.
 name for their language. For example, ConsoleExporter, StdoutExporter,
 StreamExporter, etc.
 
-"Standard output" Metrics Exporter MUST support both Cumulative and Delta
-[Temporality](../data-model.md#temporality).
+"Standard output" Metrics Exporter MUST provide configuration to set
+the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
+instrument kind. This option MAY be named `temporality`, and MUST set
+temporality to Cumulative for all instrument kinds by default.
+
+"Standard output" Metrics Exporter MAY provide configuration to set
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST use
+the [default aggregation](../sdk.md#default-aggregation) by default.
 
 If a language provides a mechanism to automatically configure a
 [MetricReader](../sdk.md#metricreader) to pair with the associated