Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define conversion mapping from OTel Exponential Histograms to Prometheus Native Histograms. #3079

Merged
merged 6 commits into from
Feb 7, 2023
Merged

Define conversion mapping from OTel Exponential Histograms to Prometheus Native Histograms. #3079

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8b9f570
Exponential to Prometheus Native Histogram conversion.
kovrus Jan 5, 2023
b817de1
fixup! Exponential to Prometheus Native Histogram conversion.
kovrus Jan 5, 2023
bf475a5
fixup! fixup! Exponential to Prometheus Native Histogram conversion.
kovrus Jan 5, 2023
4007d42
fixup! fixup! fixup! Exponential to Prometheus Native Histogram conve…
kovrus Jan 10, 2023
a50d438
fixup! fixup! fixup! fixup! Exponential to Prometheus Native Histogra…
kovrus Jan 11, 2023
0af7030
Merge branch 'main' into exp-to-native-hist
reyang Feb 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)).

Expand Down
43 changes: 36 additions & 7 deletions specification/compatibility/prometheus_and_openmetrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
kovrus marked this conversation as resolved.
Show resolved Hide resolved
kovrus marked this conversation as resolved.
Show resolved Hide resolved
Histogram as follows:

- `Scale` is converted to the Native Histogram `Schema`. Currently,
kovrus marked this conversation as resolved.
Show resolved Hide resolved
[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
kovrus marked this conversation as resolved.
Show resolved Hide resolved
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`
kovrus marked this conversation as resolved.
Show resolved Hide resolved
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:
Expand All @@ -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
Expand Down