From 44c975f5356db42676f1289ab13f0650daaf395e Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 18 Oct 2021 11:13:41 -0700 Subject: [PATCH] Spec out the metrics exporter and temporality handling (#2013) * spec out the metrics exporter and temporality handling * OTLP defaults to cumulative * add envvar --- specification/metrics/sdk.md | 43 +++++++++++++++++++ .../metrics/sdk_exporters/in-memory.md | 13 ++++-- specification/metrics/sdk_exporters/otlp.md | 28 ++++++++++-- .../metrics/sdk_exporters/prometheus.md | 6 +-- specification/metrics/sdk_exporters/stdout.md | 17 ++++++-- 5 files changed, 95 insertions(+), 12 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 5a79b62d092..13f3e622752 100644 --- a/specification/metrics/sdk.md +++ b/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: diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md index 62541ea232e..64775a85b35 100644 --- a/specification/metrics/sdk_exporters/in-memory.md +++ b/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). diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 507538aead0..2abd586e189 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/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` diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index bb78e8f526a..4edcf3625b2 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/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/). diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md index 1a91d26aa0e..4e11cb47ed4 100644 --- a/specification/metrics/sdk_exporters/stdout.md +++ b/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).