From 5803725a73064ad1c66f768778fba5c0175d354f Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Wed, 22 Jun 2022 23:39:37 -0500 Subject: [PATCH] Config option enabling exponential histogram as default histogram aggregation (#2619) --- CHANGELOG.md | 4 +++ specification/metrics/sdk.md | 22 ++++++------ specification/metrics/sdk_exporters/otlp.md | 38 +++++++++++++++------ 3 files changed, 43 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbb04ea9877..df7821286d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,10 @@ release. ### Metrics +- Add experimental `OTEL_EXPORTER_OTLP_DEFAULT_HISTOGRAM_AGGREGATION` variable for + configuring default histogram aggregation of OTLP metric exporter + ([#2619](https://github.com/open-telemetry/opentelemetry-specification/pull/2619)). + ### Logs ### Resource diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f48e4f64ec5..bfbd2378ef0 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -23,11 +23,11 @@ linkTitle: SDK + [Last Value Aggregation](#last-value-aggregation) - [Histogram Aggregation common behavior](#histogram-aggregation-common-behavior) + [Explicit Bucket Histogram Aggregation](#explicit-bucket-histogram-aggregation) - + [Exponential Histogram Aggregation](#exponential-histogram-aggregation) - - [Exponential Histogram Aggregation: Handle all normal values](#exponential-histogram-aggregation-handle-all-normal-values) - - [Exponential Histogram Aggregation: Support a minimum and maximum scale](#exponential-histogram-aggregation-support-a-minimum-and-maximum-scale) - - [Exponential Histogram Aggregation: Use the maximum scale for single measurements](#exponential-histogram-aggregation-use-the-maximum-scale-for-single-measurements) - - [Exponential Histogram Aggregation: Maintain the ideal scale](#exponential-histogram-aggregation-maintain-the-ideal-scale) + + [Exponential Bucket Histogram Aggregation](#exponential-bucket-histogram-aggregation) + - [Exponential Bucket Histogram Aggregation: Handle all normal values](#exponential-bucket-histogram-aggregation-handle-all-normal-values) + - [Exponential Bucket Histogram Aggregation: Support a minimum and maximum scale](#exponential-bucket-histogram-aggregation-support-a-minimum-and-maximum-scale) + - [Exponential Bucket Histogram Aggregation: Use the maximum scale for single measurements](#exponential-bucket-histogram-aggregation-use-the-maximum-scale-for-single-measurements) + - [Exponential Bucket Histogram Aggregation: Maintain the ideal scale](#exponential-bucket-histogram-aggregation-maintain-the-ideal-scale) * [Observations inside asynchronous callbacks](#observations-inside-asynchronous-callbacks) * [Resolving duplicate instrument registration conflicts](#resolving-duplicate-instrument-registration-conflicts) - [Attribute limits](#attribute-limits) @@ -350,7 +350,7 @@ The SDK MUST provide the following `Aggregation` to support the The SDK MAY provide the following `Aggregation`: -- [Exponential Histogram Aggregation](./sdk.md#exponential-histogram-aggregation) +- [Exponential Bucket Histogram Aggregation](./sdk.md#exponential-bucket-histogram-aggregation) #### Drop Aggregation @@ -439,7 +439,7 @@ bound (except at positive infinity). A measurement is defined to fall into the greatest-numbered bucket with boundary that is greater than or equal to the measurement. -#### Exponential Histogram Aggregation +#### Exponential Bucket Histogram Aggregation The Exponential Histogram Aggregation informs the SDK to collect data for the [Exponential Histogram Metric @@ -491,7 +491,7 @@ either: 1. The maximum supported scale, generally used for single-value histogram Aggregations where scale is not otherwise constrained 2. The largest value of scale such that no more than the maximum number of buckets are needed to represent the full range of input data in either of the positive or negative ranges. -##### Exponential Histogram Aggregation: Handle all normal values +##### Exponential Bucket Histogram Aggregation: Handle all normal values Implementations are REQUIRED to accept the entire normal range of IEEE floating point values (i.e., all values except for +Inf, -Inf and NaN @@ -504,18 +504,18 @@ values do not map into a valid bucket. Implementations MAY round subnormal values away from zero to the nearest normal value. -##### Exponential Histogram Aggregation: Support a minimum and maximum scale +##### Exponential Bucket Histogram Aggregation: Support a minimum and maximum scale The implementation MUST maintain reasonable minimum and maximum scale parameters that the automatic scale parameter will not exceed. -##### Exponential Histogram Aggregation: Use the maximum scale for single measurements +##### Exponential Bucket Histogram Aggregation: Use the maximum scale for single measurements When the histogram contains not more than one value in either of the positive or negative ranges, the implementation SHOULD use the maximum scale. -##### Exponential Histogram Aggregation: Maintain the ideal scale +##### Exponential Bucket Histogram Aggregation: Maintain the ideal scale Implementations SHOULD adjust the histogram scale as necessary to maintain the best resolution possible, within the constraint of diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index ab1c42856da..7838c1bb73d 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -4,6 +4,10 @@ linkTitle: OTLP # OpenTelemetry Metrics Exporter - OTLP +**Status**: [Mixed](../../document-status.md) + +## General + **Status**: [Stable](../../document-status.md) OTLP Metrics Exporter is a [Push Metric @@ -23,18 +27,32 @@ variable](../../sdk-environment-variables.md#exporter-selection)), then by default: * The exporter MUST be paired with a [periodic exporting -MetricReader](../sdk.md#periodic-exporting-metricreader). + MetricReader](../sdk.md#periodic-exporting-metricreader). * The exporter MUST configure the default aggregation temporality on the basis of instrument kind using the `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` variable as described - below, otherwise the exporter MUST use Cumulative as the default - aggregation temporality for all instrument kinds. + below. +* The exporter MUST configure the default aggregation on the basis of instrument kind using + the `OTEL_EXPORTER_OTLP_DEFAULT_HISTOGRAM_AGGREGATION` variable as described below if it is implemented. + +## Additional Configuration + +**Status**: [Mixed](../../document-status.md) + +| Name | Status | Description | Default | +|-----------------------------------------------------|--------------|---------------------------------------------------------------------|-----------------------------| +| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Stable | The aggregation temporality to use on the basis of instrument kind. | `cumulative` | +| `OTEL_EXPORTER_OTLP_DEFAULT_HISTOGRAM_AGGREGATION` | Experimental | The default aggregation to use for histogram instruments. | `explicit_bucket_histogram` | + +The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` are: + +* `cumulative`: Choose cumulative aggregation temporality for all instrument kinds. +* `delta`: Choose Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds, choose + Cumulative aggregation for UpDownCounter and Asynchronous UpDownCounter instrument kinds. -The `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` environment variable -defines the default aggregation temporality policy -to use on the basis of instrument kind. The recognized (case-insensitive) values are: +The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_DEFAULT_HISTOGRAM_AGGREGATION` are: -| Value | Definition | -|------------|---------------------------------------------------------------------------------------------------------------| -| CUMULATIVE | Choose Cumulative aggregation temporality for all instrument kinds. | -| DELTA | Choose Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds, choose Cumulative aggregation temporality for UpDownCounter and Asynchronous UpDownCounter instrument kinds. | +* `explicit_bucket_histogram`: + Use [Explicit Bucket Histogram Aggregation](../sdk.md#explicit-bucket-histogram-aggregation). +* `exponential_bucket_histogram`: + Use [Exponential Bucket Histogram Aggregation](../sdk.md#exponential-bucket-histogram-aggregation).