diff --git a/CHANGELOG.md b/CHANGELOG.md index 3efb823850b..b5b9a2b9697 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,10 @@ release. ### Compatibility +- Define conversion mapping from OTel Exponential Histograms to Prometheus Native + Histograms. + ([#3078](https://github.com/open-telemetry/opentelemetry-specification/issues/3078)) + - Fix Prometheus histogram metric suffixes. Bucket series end in `_bucket` ([#3018](https://github.com/open-telemetry/opentelemetry-specification/pull/3018)). diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 5314b1bb2f5..6db6993b0f8 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -27,8 +27,8 @@ * [Gauges](#gauges-1) * [Sums](#sums) * [Histograms](#histograms-1) + * [Exponential Histograms](#exponential-histograms) * [Summaries](#summaries-1) - * [Dropped Data Points](#dropped-data-points) * [Metric Attributes](#metric-attributes) * [Exemplars](#exemplars-1) * [Resource Attributes](#resource-attributes-1) @@ -293,6 +293,41 @@ An [OpenTelemetry Histogram](../metrics/data-model.md#histogram) with a cumulati OpenTelemetry Histograms with Delta aggregation temporality SHOULD be aggregated into a Cumulative aggregation temporality and follow the logic above, or MUST be dropped. +### Exponential Histograms + +An [OpenTelemetry Exponential Histogram](../metrics/data-model.md#exponentialhistogram) with +a cumulative aggregation temporality MUST be converted to a Prometheus Native +Histogram as follows: + +- `Scale` is converted to the Native Histogram `Schema`. Currently, + [valid values](https://github.com/prometheus/prometheus/commit/d9d51c565c622cdc7d626d3e7569652bc28abe15#diff-bdaf80ebc5fa26365f45db53435b960ce623ea6f86747fb8870ad1abc355f64fR76-R83) + for `schema` are -4 <= n <= 8. + If `Scale` is > 8 then Exponential Histogram data points SHOULD be downscaled + to a scale accepted by Prometheus (in range [-4,8]). Any data point unable to + be rescaled to an acceptable range MUST be dropped. +- `Count` is converted to Native Histogram `Count` if the `NoRecordedValue` + flag is set to `false`, otherwise, Native Histogram `Count` is set to the + Stale NaN value. +- `Sum` is converted to the Native Histogram `Sum` if `Sum` is set and the + `NoRecordedValue` flag is set to `false`, otherwise, Native Histogram `Sum` is + set to the Stale NaN value. +- `TimeUnixNano` is converted to the Native Histogram `Timestamp` after + converting nanoseconds to milliseconds. +- `ZeroCount` is converted directly to the Native Histogram `ZeroCount`. +- `ZeroThreshold`, if set, is converted to the Native Histogram `ZeroThreshold`. + Otherwise, it is set to the default value `1e-128`. +- The dense bucket layout represented by `Positive` bucket counts and `Offset` is + converted to the Native Histogram sparse layout represented by `PositiveSpans` + and `PositiveDeltas`. The same holds for the `Negative` bucket counts + and `Offset`. Note that Prometheus Native Histograms buckets are indexed by + upper boundary while Exponential Histograms are indexed by lower boundary, the + result being that the Offset fields are different-by-one. +- `Min` and `Max` are not used. +- `StartTimeUnixNano` is not used. + +[OpenTelemetry Exponential Histogram](../metrics/data-model.md#exponentialhistogram) +metrics with the delta aggregation temporality are dropped. + ### Summaries An [OpenTelemetry Summary](../metrics/data-model.md#summary-legacy) MUST be converted to a Prometheus metric family with the following metrics: @@ -310,12 +345,6 @@ An [OpenTelemetry Summary](../metrics/data-model.md#summary-legacy) MUST be conv each point is the computed value of the quantile point. - Summaries with `StartTimeUnixNano` set should export the `{name}_created` metric as well. -### Dropped Data Points - -The following OTLP data points MUST be dropped: - -* [ExponentialHistogram](../metrics/data-model.md#exponentialhistogram) - ### Metric Attributes OpenTelemetry Metric Attributes MUST be converted to