diff --git a/CHANGELOG.md b/CHANGELOG.md index 02775145def..3c08f943c8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,9 @@ 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)). +- Specify that preferred Aggregation and Aggregation Temporality are provided on the + basis of instrument kind by the Exporter for the Reader's information. + ([#2407](https://github.com/open-telemetry/opentelemetry-specification/pull/2407)) ### Logs diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 206f77d4d28..2c204f69fac 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -672,25 +672,9 @@ 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. +The SDK MUST provide a way to allow the default [Aggregation](#aggregation) and [Aggregation +Temporality](./datamodel.md#temporality) to be determined on the basis of instrument kind +for a `MetricReader` instance during setup (e.g. initialization, registration, etc.) time. ### MetricReader operations @@ -781,8 +765,23 @@ 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. +`MetricExporter` MUST provide a way to allow `MetricReader` to retrieve its +default Aggregation and Aggregation Temporality on the basis of instrument kind. + +For Exporters not specified in the [supported SDK exporters for +metrics](./sdk_exporters), [OpenTelemetry Exporter](#metric-exporter) +authors MAY choose the best design for the corresponding protocol: + +* Whether to treat the temporality settings as recommendation or enforcement. + For example, if the temporality is set to Delta, would the MetricExporter 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. ### Push Metric Exporter diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md index f430429a48a..c3d482f4ae1 100644 --- a/specification/metrics/sdk_exporters/in-memory.md +++ b/specification/metrics/sdk_exporters/in-memory.md @@ -16,6 +16,9 @@ by default the exporter MUST be paired with a 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). +In-memory Metrics Exporter MUST allow the default [Aggregation +Temporality](../datamodel.md#temporality) to be specified on the basis of +instrument kind, as described in [MetricExporter](../sdk.md#metricexporter). + +If the default Aggregation Temporality is not specified, In-memory Metrics +Exporter SHOULD use Cumulative as the default. diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 68dab51e3a1..c0d4e711c5e 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -16,21 +16,12 @@ by default the exporter MUST be paired with a 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). +OTLP Metrics Exporter MUST allow the default [Aggregation +Temporality](../datamodel.md#temporality) to be specified on the basis of +instrument kind, as described in [MetricExporter](../sdk.md#metricexporter). -If the temporality is not specified, OTLP Metrics Exporter SHOULD use Cumulative -as the default temporality. +If the default Aggregation Temporality is not specified, OTLP Metrics +Exporter SHOULD use Cumulative as the default. 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 preferred output [Aggregation Temporality](../datamodel.md#temporality), either `CUMULATIVE` or `DELTA` (case insensitive) | `CUMULATIVE` | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY` diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md index 6a41145de4f..5df1d70bd94 100644 --- a/specification/metrics/sdk_exporters/stdout.md +++ b/specification/metrics/sdk_exporters/stdout.md @@ -20,6 +20,9 @@ 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). +"Standard output" Metrics Exporter MUST allow the default [Aggregation +Temporality](../datamodel.md#temporality) to be specified on the basis of +instrument kind, as described in [MetricExporter](../sdk.md#metricexporter). + +If the default Aggregation Temporality is not specified, "Standard output" Metrics +Exporter SHOULD use Cumulative as the default.