From 2f3952d33b3f13483c0cdf18c643daf3db6bd322 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 7 Mar 2022 14:13:15 -0800 Subject: [PATCH 1/5] Specify preferred Aggregtion and Aggregation Temporality on a per-instrument basis --- specification/metrics/sdk.md | 36 ++++++++++----------- specification/metrics/sdk_exporters/otlp.md | 9 ------ 2 files changed, 18 insertions(+), 27 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 206f77d4d28..93d1b8a4b81 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -672,26 +672,12 @@ 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 +The SDK SHOULD provide a way to allow the preferred [Aggregation](#aggregation) and [Aggregation +Temporality](./datamodel.md#temporality) to be specified on the basis of instrument kind +for a `MetricReader` instance during 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 @@ -782,7 +768,21 @@ can run at different schedule, for example: pipe. `MetricExporter` SHOULD provide a way to allow `MetricReader` to retrieve its -preferred temporality. +preferred Aggregation and Aggregation Temporality on a per-instrument basis. + +[OpenTelemetry Exporter](#metric-exporter) authors MAY choose the best +idiomatic 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/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 1060b3b0a5a..e60afcb4561 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -18,12 +18,3 @@ 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 preferred output [Aggregation Temporality](../datamodel.md#temporality), either `CUMULATIVE` or `DELTA` (case insensitive) | `CUMULATIVE` | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY` From 5ec347099d9fa21181a0ba259db583660e95fc65 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 7 Mar 2022 14:15:37 -0800 Subject: [PATCH 2/5] changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd6fe6adca0..27921ce5a20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,9 @@ release. ([#2317](https://github.com/open-telemetry/opentelemetry-specification/pull/2317)). - Clarify that expectations for user callback behavior are documentation REQUIREMENTs. ([#2361](https://github.com/open-telemetry/opentelemetry-specification/pull/2361)). +- Specify that preferred Aggregation and Aggregation Temporality are provided on a + per-instrument basis by the Exporter for the Reader's information. + ([#2407](https://github.com/open-telemetry/opentelemetry-specification/pull/2407)) ### Logs From d7a6315aba5c330b6b4b1f40daf8b7b103253788 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 9 Mar 2022 11:59:27 -0800 Subject: [PATCH 3/5] default ... on the basis of instrument kind (instead of preferred) --- CHANGELOG.md | 4 ++-- specification/metrics/sdk.md | 13 ++++++------- specification/metrics/sdk_exporters/in-memory.md | 9 ++++++--- specification/metrics/sdk_exporters/otlp.md | 10 +++++----- specification/metrics/sdk_exporters/stdout.md | 9 ++++++--- 5 files changed, 25 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 51a64ad5f4b..3c08f943c8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,8 +31,8 @@ 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 a - per-instrument basis by the Exporter for the Reader's information. +- 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 93d1b8a4b81..1f55d09940e 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -672,11 +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](#aggregation) and [Aggregation +The SDK SHOULD provide a way to allow the default [Aggregation](#aggregation) and [Aggregation Temporality](./datamodel.md#temporality) to be specified on the basis of instrument kind -for a `MetricReader` instance during setup (e.g. initialization, registration, etc.) time. If the -preferred temporality is explicitly specified then the SDK SHOULD respect that, -otherwise use Cumulative. +for a `MetricReader` instance during setup (e.g. initialization, registration, etc.) time. ### MetricReader operations @@ -768,10 +766,11 @@ can run at different schedule, for example: pipe. `MetricExporter` SHOULD provide a way to allow `MetricReader` to retrieve its -preferred Aggregation and Aggregation Temporality on a per-instrument basis. +default Aggregation and Aggregation Temporality on the basis of instrument kind. -[OpenTelemetry Exporter](#metric-exporter) authors MAY choose the best -idiomatic design for the corresponding protocol: +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 diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md index f430429a48a..7a04e924ba0 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 b4cefc04b11..04f173d5b1f 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -16,12 +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. diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md index 6a41145de4f..b4d91c1612a 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. From b2911fce0d21d8f4e168bd4e0eafe5fde70fe71c Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 9 Mar 2022 12:13:53 -0800 Subject: [PATCH 4/5] edits --- specification/metrics/sdk.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 1f55d09940e..b7324decd18 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -672,8 +672,8 @@ 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 default [Aggregation](#aggregation) and [Aggregation -Temporality](./datamodel.md#temporality) to be specified on the basis of instrument kind +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 @@ -765,7 +765,7 @@ 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 +`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 From e5d8d7d98f68793509078a2cd28056c45a7bdcae Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 9 Mar 2022 12:32:53 -0800 Subject: [PATCH 5/5] lint --- specification/metrics/sdk.md | 2 +- specification/metrics/sdk_exporters/in-memory.md | 2 +- specification/metrics/sdk_exporters/otlp.md | 2 +- specification/metrics/sdk_exporters/stdout.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b7324decd18..2c204f69fac 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -673,7 +673,7 @@ idiomatic approach, for example, as `OnForceFlush` and `OnShutdown` callback functions. 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 +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 diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md index 7a04e924ba0..c3d482f4ae1 100644 --- a/specification/metrics/sdk_exporters/in-memory.md +++ b/specification/metrics/sdk_exporters/in-memory.md @@ -17,7 +17,7 @@ In-memory Metrics Exporter MUST support both Cumulative and Delta [Temporality](../datamodel.md#temporality). In-memory Metrics Exporter MUST allow the default [Aggregation -Temporality](../datamodel.md#temporality) to be specified on the basis of +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 diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 04f173d5b1f..c0d4e711c5e 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -17,7 +17,7 @@ OTLP Metrics Exporter MUST support both Cumulative and Delta [Temporality](../datamodel.md#temporality). OTLP Metrics Exporter MUST allow the default [Aggregation -Temporality](../datamodel.md#temporality) to be specified on the basis of +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, OTLP Metrics diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md index b4d91c1612a..5df1d70bd94 100644 --- a/specification/metrics/sdk_exporters/stdout.md +++ b/specification/metrics/sdk_exporters/stdout.md @@ -21,7 +21,7 @@ StreamExporter, etc. [Temporality](../datamodel.md#temporality). "Standard output" Metrics Exporter MUST allow the default [Aggregation -Temporality](../datamodel.md#temporality) to be specified on the basis of +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