From 2903e6460fbc7c4578f7634b85e1460d0daf1629 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Wed, 24 Jul 2024 09:16:32 -0500 Subject: [PATCH] Clarify reader / exporter relationship for temporality preference and default aggregation (#4142) Reviewing @dashpole's [comments](https://github.com/open-telemetry/opentelemetry-specification/pull/4124#pullrequestreview-2163699299) 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 | 5 + spec-compliance-matrix.md | 122 +++++++++--------- specification/metrics/sdk.md | 8 +- .../metrics/sdk_exporters/in-memory.md | 11 +- specification/metrics/sdk_exporters/otlp.md | 21 ++- .../metrics/sdk_exporters/prometheus.md | 9 ++ specification/metrics/sdk_exporters/stdout.md | 11 +- 7 files changed, 112 insertions(+), 75 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b6f36a8bae..ea401b9dbc4 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 8d505c4a7e3..b0d9f5c07ef 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -316,66 +316,68 @@ for details. ## Exporters -| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -|--------------------------------------------------------------------------------|----------|----|------|----|-------------|------|--------|-----|------|-----|------|-------| -| [Exporter interface](specification/trace/sdk.md#span-exporter) | | | + | | + | + | + | + | + | + | + | | -| [Exporter interface has `ForceFlush`](specification/trace/sdk.md#forceflush-2) | | | + | | [-][py1779] | + | + | + | - | | + | | -| Standard output (logging) | | + | + | + | + | + | + | + | + | + | + | + | -| In-memory (mock exporter) | | + | + | + | + | + | + | + | - | + | + | + | -| **[OTLP](specification/protocol/otlp.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| OTLP/gRPC Exporter | * | + | + | + | + | | + | + | + | + | + | + | -| OTLP/HTTP binary Protobuf Exporter | * | + | + | + | + | + | + | + | + | + | + | - | -| OTLP/HTTP JSON Protobuf Exporter | | + | - | + | [-][py1003] | | - | + | | + | - | - | -| OTLP/HTTP gzip Content-Encoding support | X | + | + | + | + | + | - | + | | - | - | - | -| Concurrent sending | | - | + | + | [-][py1108] | | - | | + | - | - | - | -| Honors retryable responses with backoff | X | + | - | + | + | + | - | | | - | - | - | -| Honors non-retryable responses | X | + | - | - | + | + | - | | | - | - | - | -| Honors throttling response | X | + | - | - | + | + | - | | | - | - | - | -| Multi-destination spec compliance | X | + | - | | [-][py1109] | | - | | | - | - | - | -| SchemaURL in ResourceSpans and ScopeSpans | | + | + | | + | | + | + | | | - | | -| SchemaURL in ResourceMetrics and ScopeMetrics | | | + | | + | | - | + | | | - | | -| SchemaURL in ResourceLogs and ScopeLogs | | | + | | + | | - | + | | | - | | -| Honors the [user agent spec](specification/protocol/exporter.md#user-agent) | | | | | | | | + | | | + | | -| [Partial Success](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#partial-success) messages are handled and logged for OTLP/gRPC | X | + | | | | | | + | | | | | -| [Partial Success](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#partial-success-1) messages are handled and logged for OTLP/HTTP | X | + | | | | | | + | | | | | -| **[Zipkin](specification/trace/sdk_exporters/zipkin.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| Zipkin V1 JSON | X | - | + | | + | - | - | - | - | - | - | - | -| Zipkin V1 Thrift | X | - | + | | [-][py1174] | - | - | - | - | - | - | - | -| Zipkin V2 JSON | * | + | + | | + | + | - | + | + | + | + | + | -| Zipkin V2 Protobuf | * | - | + | | + | - | + | - | - | - | - | - | -| Service name mapping | | + | + | + | + | + | + | + | + | + | + | + | -| SpanKind mapping | | + | + | + | + | + | + | + | + | + | + | + | -| InstrumentationLibrary mapping | | + | + | - | + | + | - | + | + | + | + | + | -| InstrumentationScope mapping | | | + | | | | | | | | | | -| Boolean attributes | | + | + | + | + | + | + | + | + | + | + | + | -| Array attributes | | + | + | + | + | + | + | + | + | + | + | + | -| Status mapping | | + | + | + | + | + | + | + | + | + | + | + | -| Error Status mapping | | + | + | | + | + | - | + | + | + | + | - | -| Event attributes mapping to Annotations | | + | + | + | + | + | + | + | + | + | + | + | -| Integer microseconds in timestamps | | N/A| + | | + | + | - | + | + | + | + | + | -| **Prometheus** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| [Metadata Deduplication](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | - | - | - | - | - | + | - | - | - | -| [Name Sanitization](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | + | + | - | - | - | + | + | + | + | -| [UNIT Metadata](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | X | - | - | + | + | - | - | - | - | - | + | - | -| [Unit Suffixes](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | X | + | + | - | + | - | - | - | + | + | + | - | -| [Unit Full Words](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | X | + | + | - | - | - | - | - | + | - | - | - | -| [HELP Metadata](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | + | + | - | - | - | + | + | + | + | -| [TYPE Metadata](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | + | + | - | - | - | + | + | + | + | -| [otel_scope_name and otel_scope_version labels on all Metrics](specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1) | | + | + | - | - | - | - | - | + | - | - | - | -| [otel_scope_info metric](specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1) | X | + | + | - | - | - | - | - | + | - | - | - | -| [otel_scope_info and labels can be disabled](specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1) | X | + | - | - | - | - | - | - | + | - | - | - | -| [Gauges become Prometheus Gauges](specification/compatibility/prometheus_and_openmetrics.md#gauges-1) | | + | + | + | + | - | - | - | + | + | + | - | -| [Cumulative Monotonic Sums become Prometheus Counters](specification/compatibility/prometheus_and_openmetrics.md#sums) | | + | + | + | + | - | - | - | + | + | + | + | -| [Prometheus Counters have _total suffix by default](specification/compatibility/prometheus_and_openmetrics.md#sums) | | + | + | + | + | - | - | - | + | - | - | - | -| [Prometheus Counters _total suffixing can be disabled](specification/compatibility/prometheus_and_openmetrics.md#sums) | X | + | - | - | - | - | - | - | - | - | - | - | -| [Cumulative Non-Monotonic Sums become Prometheus Gauges](specification/compatibility/prometheus_and_openmetrics.md#sums) | | + | + | + | + | - | - | - | + | + | + | - | -| [Delta Non-Monotonic Sums become Cumulative Prometheus Counters](specification/compatibility/prometheus_and_openmetrics.md#sums) | X | - | - | - | - | - | - | - | - | - | - | - | -| [Cumulative Histograms become Prometheus Histograms](specification/compatibility/prometheus_and_openmetrics.md#histograms-1) | | + | + | + | + | - | - | - | + | + | + | + | -| [Delta Histograms become Cumulative Prometheus Histograms](specification/compatibility/prometheus_and_openmetrics.md#histograms-1) | X | - | - | - | - | - | - | - | - | - | - | - | -| [Attributes Keys are Sanitized](specification/compatibility/prometheus_and_openmetrics.md#metric-attributes) | | + | + | + | + | - | - | - | + | + | + | + | -| [Colliding sanitized attribute keys are merged](specification/compatibility/prometheus_and_openmetrics.md#metric-attributes) | | + | + | - | - | - | - | - | + | - | - | - | -| [Exemplars for Histograms and Monotonic sums](specification/compatibility/prometheus_and_openmetrics.md#exemplars-1) | X | - | - | - | - | - | - | - | - | - | - | - | -| [`target_info` metric from Resource](specification/compatibility/prometheus_and_openmetrics.md#resource-attributes-1) | X | + | + | + | + | - | - | - | + | - | - | - | +| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-----|------|----|-------------|------|--------|-----|------|-----|------|-------| +| [Exporter interface](specification/trace/sdk.md#span-exporter) | | | + | | + | + | + | + | + | + | + | | +| [Exporter interface has `ForceFlush`](specification/trace/sdk.md#forceflush-2) | | | + | | [-][py1779] | + | + | + | - | | + | | +| Standard output (logging) | | + | + | + | + | + | + | + | + | + | + | + | +| In-memory (mock exporter) | | + | + | + | + | + | + | + | - | + | + | + | +| **[OTLP](specification/protocol/otlp.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +| OTLP/gRPC Exporter | * | + | + | + | + | | + | + | + | + | + | + | +| OTLP/HTTP binary Protobuf Exporter | * | + | + | + | + | + | + | + | + | + | + | - | +| OTLP/HTTP JSON Protobuf Exporter | | + | - | + | [-][py1003] | | - | + | | + | - | - | +| OTLP/HTTP gzip Content-Encoding support | X | + | + | + | + | + | - | + | | - | - | - | +| Concurrent sending | | - | + | + | [-][py1108] | | - | | + | - | - | - | +| Honors retryable responses with backoff | X | + | - | + | + | + | - | | | - | - | - | +| Honors non-retryable responses | X | + | - | - | + | + | - | | | - | - | - | +| Honors throttling response | X | + | - | - | + | + | - | | | - | - | - | +| Multi-destination spec compliance | X | + | - | | [-][py1109] | | - | | | - | - | - | +| SchemaURL in ResourceSpans and ScopeSpans | | + | + | | + | | + | + | | | - | | +| SchemaURL in ResourceMetrics and ScopeMetrics | | | + | | + | | - | + | | | - | | +| SchemaURL in ResourceLogs and ScopeLogs | | | + | | + | | - | + | | | - | | +| Honors the [user agent spec](specification/protocol/exporter.md#user-agent) | | | | | | | | + | | | + | | +| [Partial Success](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#partial-success) messages are handled and logged for OTLP/gRPC | X | + | | | | | | + | | | | | +| [Partial Success](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#partial-success-1) messages are handled and logged for OTLP/HTTP | X | + | | | | | | + | | | | | +| Metric Exporter configurable temporality preference | | | + | | | | | | | | | | +| Metric Exporter configurable default aggregation | | | + | | | | | | | | | | +| **[Zipkin](specification/trace/sdk_exporters/zipkin.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +| Zipkin V1 JSON | X | - | + | | + | - | - | - | - | - | - | - | +| Zipkin V1 Thrift | X | - | + | | [-][py1174] | - | - | - | - | - | - | - | +| Zipkin V2 JSON | * | + | + | | + | + | - | + | + | + | + | + | +| Zipkin V2 Protobuf | * | - | + | | + | - | + | - | - | - | - | - | +| Service name mapping | | + | + | + | + | + | + | + | + | + | + | + | +| SpanKind mapping | | + | + | + | + | + | + | + | + | + | + | + | +| InstrumentationLibrary mapping | | + | + | - | + | + | - | + | + | + | + | + | +| InstrumentationScope mapping | | | + | | | | | | | | | | +| Boolean attributes | | + | + | + | + | + | + | + | + | + | + | + | +| Array attributes | | + | + | + | + | + | + | + | + | + | + | + | +| Status mapping | | + | + | + | + | + | + | + | + | + | + | + | +| Error Status mapping | | + | + | | + | + | - | + | + | + | + | - | +| Event attributes mapping to Annotations | | + | + | + | + | + | + | + | + | + | + | + | +| Integer microseconds in timestamps | | N/A | + | | + | + | - | + | + | + | + | + | +| **Prometheus** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +| [Metadata Deduplication](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | - | - | - | - | - | + | - | - | - | +| [Name Sanitization](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | + | + | - | - | - | + | + | + | + | +| [UNIT Metadata](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | X | - | - | + | + | - | - | - | - | - | + | - | +| [Unit Suffixes](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | X | + | + | - | + | - | - | - | + | + | + | - | +| [Unit Full Words](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | X | + | + | - | - | - | - | - | + | - | - | - | +| [HELP Metadata](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | + | + | - | - | - | + | + | + | + | +| [TYPE Metadata](specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1) | | + | + | + | + | - | - | - | + | + | + | + | +| [otel_scope_name and otel_scope_version labels on all Metrics](specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1) | | + | + | - | - | - | - | - | + | - | - | - | +| [otel_scope_info metric](specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1) | X | + | + | - | - | - | - | - | + | - | - | - | +| [otel_scope_info and labels can be disabled](specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1) | X | + | - | - | - | - | - | - | + | - | - | - | +| [Gauges become Prometheus Gauges](specification/compatibility/prometheus_and_openmetrics.md#gauges-1) | | + | + | + | + | - | - | - | + | + | + | - | +| [Cumulative Monotonic Sums become Prometheus Counters](specification/compatibility/prometheus_and_openmetrics.md#sums) | | + | + | + | + | - | - | - | + | + | + | + | +| [Prometheus Counters have _total suffix by default](specification/compatibility/prometheus_and_openmetrics.md#sums) | | + | + | + | + | - | - | - | + | - | - | - | +| [Prometheus Counters _total suffixing can be disabled](specification/compatibility/prometheus_and_openmetrics.md#sums) | X | + | - | - | - | - | - | - | - | - | - | - | +| [Cumulative Non-Monotonic Sums become Prometheus Gauges](specification/compatibility/prometheus_and_openmetrics.md#sums) | | + | + | + | + | - | - | - | + | + | + | - | +| [Delta Non-Monotonic Sums become Cumulative Prometheus Counters](specification/compatibility/prometheus_and_openmetrics.md#sums) | X | - | - | - | - | - | - | - | - | - | - | - | +| [Cumulative Histograms become Prometheus Histograms](specification/compatibility/prometheus_and_openmetrics.md#histograms-1) | | + | + | + | + | - | - | - | + | + | + | + | +| [Delta Histograms become Cumulative Prometheus Histograms](specification/compatibility/prometheus_and_openmetrics.md#histograms-1) | X | - | - | - | - | - | - | - | - | - | - | - | +| [Attributes Keys are Sanitized](specification/compatibility/prometheus_and_openmetrics.md#metric-attributes) | | + | + | + | + | - | - | - | + | + | + | + | +| [Colliding sanitized attribute keys are merged](specification/compatibility/prometheus_and_openmetrics.md#metric-attributes) | | + | + | - | - | - | - | - | + | - | - | - | +| [Exemplars for Histograms and Monotonic sums](specification/compatibility/prometheus_and_openmetrics.md#exemplars-1) | X | - | - | - | - | - | - | - | - | - | - | - | +| [`target_info` metric from Resource](specification/compatibility/prometheus_and_openmetrics.md#resource-attributes-1) | X | + | + | + | + | - | - | - | + | - | - | - | ## OpenCensus Compatibility diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 8823b4b69f1..3dd0c6ecf10 100644 --- a/specification/metrics/sdk.md +++ b/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. diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md index 3a37039a064..6a17ea7a1cf 100644 --- a/specification/metrics/sdk_exporters/in-memory.md +++ b/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 diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 86719ea22f7..5b22516e883 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/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: diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 844e88ef40f..9c119718838 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/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. diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md index fa336eced62..fee5158e77f 100644 --- a/specification/metrics/sdk_exporters/stdout.md +++ b/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