Skip to content

Stabilize OTLP->Prometheus: Gauges and Sums #5034

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

Open
ArthurSens wants to merge 2 commits into
base: main
Choose a base branch
from
+15 −19
Open

Stabilize OTLP->Prometheus: Gauges and Sums #5034

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7fdcfdb
Stabilize OTLP->Prometheus: Gauges and Sums
ArthurSens Apr 17, 2026
c83bd8c
Address comments
ArthurSens Apr 17, 2026
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
27 changes: 13 additions & 14 deletions specification/compatibility/prometheus_and_openmetrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,32 +466,31 @@

### Gauges

**Status**: [Development](../document-status.md)
**Status**: [Stable](../document-status.md)

An [OpenTelemetry Gauge](../metrics/data-model.md#gauge) MUST be converted to
a Prometheus Unknown-typed metric if the `prometheus.type` key of
[metric.metadata][metricMetadata] is `unknown`. Otherwise, it MUST be converted
to a Prometheus Gauge.
An [OpenTelemetry Gauge](../metrics/data-model#gauge) MUST be converted following
a hint present in [metric.metadata][metricMetadata]:
- If the `prometheus.type` key is absent, or its value is equal to `gauge`, the datapoint MUST be transformed to a Prometheus Gauge.
- If the `prometheus.type` key has value equal to `info`, the datapoint MUST be transformed to a Prometheus Info.
- If the `prometheus.type` key has value equal to `stateset`, the datapoint MUST be transformed to a Prometheus Stateset.
Comment thread
ArthurSens marked this conversation as resolved.
Outdated
- If the `prometheus.type` key has value equal to `unkown`, the datapoint MUST be transformed to a Prometheus Unkown.

Check failure on line 476 in specification/compatibility/prometheus_and_openmetrics.md

View workflow job for this annotation

GitHub Actions / textlint

TextLint->common-misspellings 

This is a commonly misspelled word. Correct it to unknown

### Sums

**Status**: [Development](../document-status.md)
**Status**: [Stable](../document-status.md)

[OpenTelemetry Sums](../metrics/data-model.md#sums) follows this logic:
An [OpenTelemetry Sums](../metrics/data-model.md#sums) MUST be converted following the rules below:

- If the aggregation temporality is cumulative and the sum is monotonic, it MUST be converted to a Prometheus Counter.
- If the aggregation temporality is cumulative and the sum is non-monotonic and the `prometheus.type` key of
[metric.metadata][metricMetadata] is `info`, it MUST be converted to an OpenMetrics Info metric.
- If the aggregation temporality is cumulative and the sum is non-monotonic and the `prometheus.type` key of
[metric.metadata][metricMetadata] is `stateset`, it MUST be converted to an OpenMetrics StateSet metric.
- If the aggregation temporality is cumulative and the sum is non-monotonic, it MUST be converted to a Prometheus Gauge.
- If the aggregation temporality is cumulative and the sum is non-monotonic, it should follow the same rules as described for [OpenTelemetry Gauge](#gauges-1)
- If the aggregation temporality is delta and the sum is monotonic, it SHOULD be converted to a cumulative temporality and become a Prometheus Counter. The following behaviors are expected:
- The new data point type must be the same as the accumulated data point type.
- The new data point's start time must match the time of the accumulated data point. If not, see [detecting alignment issues](../metrics/data-model.md#sums-detecting-alignment-issues).
- Otherwise, it MUST be dropped.
Copy link
Copy Markdown
Member Author

@ArthurSens ArthurSens Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@open-telemetry/prometheus-interoperability, I'm a bit unsure about this one.

In the collector, there's a component that transforms deltas into cumulative, and as far as I know, using this is the recommended way for folks trying to consume Delta and expose Prometheus.

I'm a bit inclined to adjust the wording to say that Deltas MUST be dropped, and recommend that this transformation should happen outside of the Prometheus domain

Copy link
Copy Markdown
Contributor

@dashpole dashpole Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree. Lets drop this language

Copy link
Copy Markdown
Contributor

@dashpole dashpole Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Turns out we do support delta -> Cumulative in the prometheusexporter: open-telemetry/opentelemetry-collector-contrib#47721. We should discuss whether we want to remove that support.

Copy link
Copy Markdown
Member Author

@ArthurSens ArthurSens Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are the downsides of using deltatocumulativeprocessor instead? If there isn't any, or if they are very minimal, I'd prefer that we drop this 😬

Copy link
Copy Markdown
Contributor

@dashpole dashpole Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably mostly memory usage. Both deltatocumulativeprocessor and prometheusexporter have an internal state of all metrics that they accumulate. It would be twice as expensive.

WDYT about just changing this to MAY convert delta to cumulative instead of SHOULD?

Copy link
Copy Markdown
Member Author

@ArthurSens ArthurSens Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I'm following. If folks use deltatocumulative, then deltatocumulative will retain state, and everything will be cumulative when it reaches the Prometheus exporter. We're just moving the same operation from one place to another.


If the metric name for monotonic Sum metric points does not end in a suffix of `_total` a suffix of `_total` SHOULD be added by default, otherwise the name MUST remain unchanged. Exporters SHOULD provide a configuration option to disable the addition of `_total` suffixes.
Monotonic Sum metric points with `StartTimeUnixNano` should export the `{name}_created` metric as well.
If the metric name for monotonic Sum metric points does not end in a suffix of `_total` a suffix of `_total` SHOULD be added by default, otherwise the name MUST remain unchanged.

Monotonic Sum metric points with `StartTimeUnixNano` SHOULD transform `StartTimeUnixNano` into Prometheus `StartTime`, following the appropriate format used by each Prometheus protocol.

### Histograms

Expand Down
Loading