Spec out the metrics exporter and temporality handling (open-telemetry#2013)

* spec out the metrics exporter and temporality handling

* OTLP defaults to cumulative

* add envvar

Author: reyang

specification/metrics/sdk.md

@@ -559,6 +559,26 @@ 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 [Aggregation
+Temporality](./datamodel.md#temporality) to be specified for a `MetricReader`
+instance during the creation time. [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)?
+* If an invalid combination of settings occurred (e.g. if a `MetricReader`
+  instance is set to use Cumulative, and it has an associated [Push Metric
+  Exporter](#push-metric-exporter) instance which has the temporality set to
+  Delta), would the SDK want to fail fast or use some fallback logic?
+* Refer to the [supplementary
+  guidelines](./supplementary-guidelines.md#aggregation-temporality), which have
+  more context and suggestions.
+
 ### MetricReader operations
 
 #### Collect
@@ -629,6 +649,29 @@ example:
 * Exporter D is a pull exporter which reacts to another scraper over a named
   pipe.
 
+The SDK SHOULD provide a way to allow [Aggregation
+Temporality](./datamodel.md#temporality) to be specified for a `MetricExporter`
+instance during the creation time, if the exporter supports both Cumulative and
+Delta [Temporality](./datamodel.md#temporality). [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 an [OTLP Exporter](./sdk_exporters/otlp.md) instance is being
+  used, and 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 exporting it as Cumulative due to the
+  consideration of [memory
+  efficiency](./supplementary-guidelines.md#memory-management)?
+* If an invalid combination of settings occurred (e.g. if a [Prometheus
+  Exporter](./sdk_exporters/prometheus.md) instance is being used, and the
+  temporality is set to Delta), would the SDK want to fail fast or use some
+  fallback logic?
+* Refer to the [supplementary
+  guidelines](./supplementary-guidelines.md#aggregation-temporality), which have
+  more context and suggestions.
+
 ### Push Metric Exporter
 
 Push Metric Exporter sends the data on its own schedule. Here are some examples:

specification/metrics/sdk_exporters/in-memory.md

@@ -2,6 +2,13 @@
 
 **Status**: [Experimental](../../document-status.md)
 
-Note: this specification is subject to major changes. To avoid thrusting
-language client maintainers, we don't recommend OpenTelemetry clients to start
-the implementation unless explicitly communicated.
+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](../datamodel.md#temporality).
+
+In-memory Metrics Exporter MUST allow [Aggregation
+Temporality](../datamodel.md#temporality) to be specified, as described in
+[MetricExporter](../sdk.md#metricexporter).

specification/metrics/sdk_exporters/otlp.md

@@ -2,6 +2,28 @@
 
 **Status**: [Experimental](../../document-status.md)
 
-Note: this specification is subject to major changes. To avoid thrusting
-language client maintainers, we don't recommend OpenTelemetry clients to start
-the implementation unless explicitly communicated.
+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
+[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.
+
+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)):
+
+| Description | Default | Env variable |
+| ----------- | ------- | ------------ |
+| The output [Aggregation Temporality](../datamodel.md#temporality), either `CUMULATIVE` or `DELTA` (case insensitive) | `CUMULATIVE` | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY`

specification/metrics/sdk_exporters/prometheus.md

@@ -2,6 +2,6 @@
 
 **Status**: [Experimental](../../document-status.md)
 
-Note: this specification is subject to major changes. To avoid thrusting
-language client maintainers, we don't recommend OpenTelemetry clients to start
-the implementation unless explicitly communicated.
+Prometheus Exporter is a [Pull Metric Exporter](../sdk.md#pull-metric-exporter)
+which reacts to the Prometheus scraper and report the metrics passively to
+[Prometheus](https://prometheus.io/).

specification/metrics/sdk_exporters/stdout.md

@@ -2,6 +2,17 @@
 
 **Status**: [Experimental](../../document-status.md)
 
-Note: this specification is subject to major changes. To avoid thrusting
-language client maintainers, we don't recommend OpenTelemetry clients to start
-the implementation unless explicitly communicated.
+"Standard output" Metrics Exporter is a [Push Metric
+Exporter](../sdk.md#push-metric-exporter) which outputs the metrics to
+stdout/console.
+
+[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).