Skip to content

Set Prometheus<->OTLP specification to Mixed stability #4860

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

Merged
dashpole merged 1 commit into from
Feb 2, 2026
Merged

Set Prometheus<->OTLP specification to Mixed stability #4860

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
54 changes: 53 additions & 1 deletion specification/compatibility/prometheus_and_openmetrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ aliases:

# Prometheus and OpenMetrics Compatibility

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

<details>
<summary>Table of Contents</summary>
Expand Down Expand Up @@ -78,8 +78,12 @@ at the time of writing:

## Prometheus Metric points to OTLP

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

### Metric Metadata

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

The [Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information)
MUST be added as the Name of the OTLP metric. By default, the name SHOULD NOT be altered, but translation SHOULD provide configuration which, when enabled, removes type (e.g. `_total`) and unit (e.g. `_seconds`) suffixes.

Expand All @@ -103,26 +107,38 @@ under the `prometheus.type` key (e.g. `prometheus.type="unknown"`).

### Counters

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

A [Prometheus Counter](https://prometheus.io/docs/instrumenting/exposition_formats/#basic-info) MUST be converted to an OTLP Sum with `is_monotonic` equal to `true`.

### Gauges

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

A [Prometheus Gauge](https://prometheus.io/docs/instrumenting/exposition_formats/#basic-info) MUST be converted to an OTLP Gauge.

### Info

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

A [Prometheus Info](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#info) metric MUST be converted to an OTLP Non-Monotonic Sum unless it is the `target` info metric, which is used to populate [resource attributes](#resource-attributes). A Prometheus Info metric can be thought of as a special-case of the Prometheus Gauge metric which has a value of 1, and whose labels generally stays constant over the life of the process. It is converted to a OTLP Non-Monotonic Sum, rather than an OTLP Gauge, because the value of 1 is intended to be viewed as a count, which should be summed together when aggregating away labels.

### StateSet

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

A [Prometheus StateSet](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset) metric MUST be converted to an OTLP Non-Monotonic Sum. A Prometheus StateSet metric can be thought of as a special-case of the Prometheus Gauge which has a 0 or 1 value, and has one metric point for every possible state. It is converted to an OTLP Non-Monotonic Sum, rather than an OTLP Gauge, because the value of 1 is intended to be viewed as a count, which should be summed together when aggregating away labels.

### Unknown-typed

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

A [Prometheus Unknown](https://prometheus.io/docs/instrumenting/exposition_formats/#basic-info) MUST be converted to an OTLP Gauge.

### Histograms

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

A [Prometheus Histogram](https://prometheus.io/docs/instrumenting/exposition_formats/#basic-info) MUST be converted to an OTLP Histogram.

Multiple Prometheus histogram metrics MUST be merged together into a single OTLP Histogram:
Expand All @@ -134,6 +150,8 @@ Multiple Prometheus histogram metrics MUST be merged together into a single OTLP

### Native Histograms

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

A [Prometheus Native Histogram](https://prometheus.io/docs/specs/native_histograms/)
with standard (exponential) schema (i.e. schemas -4 to 8) and which are
of the integer and counter [flavor](https://prometheus.io/docs/specs/native_histograms/#flavors)
Expand Down Expand Up @@ -164,6 +182,8 @@ Native Histograms with `Schema` outside of the range [-4, 8] MUST be dropped.

### Summaries

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

[Prometheus Summary](https://prometheus.io/docs/instrumenting/exposition_formats/#basic-info) MUST be converted to an OTLP Summary.

Multiple Prometheus metrics are merged together into a single OTLP Summary:
Expand All @@ -175,17 +195,23 @@ Multiple Prometheus metrics are merged together into a single OTLP Summary:

### Dropped Types

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

The following Prometheus types MUST be dropped:

* [Prometheus GaugeHistogram](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#gaugehistogram)
* [Prometheus Native GaugeHistogram](https://prometheus.io/docs/specs/native_histograms/#gauge-histograms-vs-counter-histograms)

### Start Time

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

Prometheus Cumulative metrics can include the start time using the [`_created` sample series](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#counter-1). When converting Prometheus Counters to OTLP, conversion SHOULD use `_created` where available. When no `_created` metric is available, conversion MUST follow [Cumulative streams: handling unknown start time](../metrics/data-model.md#cumulative-streams-handling-unknown-start-time) by default. Conversion MAY offer configuration, disabled by default, which allows using the `process_start_time_seconds` metric to provide the start time. Using `process_start_time_seconds` is only correct when all counters on the target start after the process and are not reset while the process is running.

### Exemplars

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

[Prometheus Exemplars](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#exemplars)
can be attached to Prometheus Histogram bucket metric points and counter metric
points. Exemplars on histogram buckets SHOULD be converted to exemplars on
Expand All @@ -198,6 +224,8 @@ exemplar as attributes.

### Instrumentation Scope

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

Labels with `otel_scope_` prefix MUST be dropped from all metric points
and used as the Instrumentation Scope name (`otel_scope_name`),
version (`otel_scope_version`), schema URL (`otel_scope_schema_url`),
Expand Down Expand Up @@ -234,6 +262,8 @@ prometheus receiver).

### Resource Attributes

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

When scraping a Prometheus endpoint, resource attributes MUST be added to the
scraped metrics to distinguish them from metrics from other Prometheus
endpoints. In particular, `service.name` and `service.instance.id`, are needed
Expand Down Expand Up @@ -269,8 +299,12 @@ in keys).

## OTLP Metric points to Prometheus

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

### Metric Metadata

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

Prometheus Pull exporters MUST NOT allow duplicate UNIT, HELP, or TYPE
comments for the same metric name to be returned in a single scrape of the
Prometheus endpoint. Exporters MUST drop entire metrics to prevent conflicting
Expand Down Expand Up @@ -307,6 +341,8 @@ It also dictates type-specific conversion rules listed below.

### Instrumentation Scope

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

Prometheus exporters MUST by default add
the scope name as the `otel_scope_name` label,
the scope version as the `otel_scope_version` label,
Expand All @@ -320,13 +356,17 @@ to avoid conflicts with the already existing `otel_scope_name`, `otel_scope_vers

### Gauges

**Status**: [Development](../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.

### Sums

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

[OpenTelemetry Sums](../metrics/data-model.md#sums) follows this logic:

- If the aggregation temporality is cumulative and the sum is monotonic, it MUST be converted to a Prometheus Counter.
Expand All @@ -345,6 +385,8 @@ Monotonic Sum metric points with `StartTimeUnixNano` should export the `{name}_c

### Histograms

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

An [OpenTelemetry Histogram](../metrics/data-model.md#histogram) with a cumulative aggregation temporality MUST be converted to a Prometheus metric family with the following metrics:

- A single `{name}_count` metric denoting the count field of the histogram. All attributes of the histogram point are converted to Prometheus labels.
Expand All @@ -356,6 +398,8 @@ OpenTelemetry Histograms with Delta aggregation temporality SHOULD be aggregated

### Exponential Histograms

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

An [OpenTelemetry Exponential Histogram](../metrics/data-model.md#exponentialhistogram) with
a cumulative aggregation temporality MUST be converted to a Prometheus Native
Histogram as follows:
Expand Down Expand Up @@ -391,6 +435,8 @@ metrics with the delta aggregation temporality are dropped.

### Summaries

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

An [OpenTelemetry Summary](../metrics/data-model.md#summary-legacy) MUST be converted to a Prometheus metric family with the following metrics:

- A single `{name}_count` metric denoting the count field of the summary.
Expand All @@ -408,6 +454,8 @@ An [OpenTelemetry Summary](../metrics/data-model.md#summary-legacy) MUST be conv

### Metric Attributes

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

OpenTelemetry Metric Attributes MUST be converted to
[Prometheus labels](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels).
String Attribute values are converted directly to Metric Attributes, and
Expand All @@ -424,6 +472,8 @@ the lexicographical order of the original keys.

### Exemplars

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

[Exemplars](../metrics/data-model.md#exemplars) on OpenTelemetry Histograms and Monotonic Sums SHOULD
be converted to Prometheus exemplars. Exemplars on other OpenTelemetry data
points MUST be dropped. For Prometheus Remote Write exporters, multiple exemplars are
Expand All @@ -440,6 +490,8 @@ Prometheus exemplar unless they would exceed the

### Resource Attributes

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

In Prometheus exporters, an OpenTelemetry Resource SHOULD be converted to
a [`target` info metric](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems)
if the resource is not [empty](../resource/sdk.md#the-empty-resource).
Expand Down
Loading
⚡