Define conversion mapping from OTel Exponential Histograms to Prometh…

…eus Native Histograms. (#3079)

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)).
 

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