From ab95f7790f7291a291f6a18b2eca8f193d40226f Mon Sep 17 00:00:00 2001 From: Arthur Silva Sens Date: Wed, 4 Feb 2026 16:44:47 -0300 Subject: [PATCH 1/4] Stabilize Prometheus Classic Histogram -> OTLP Explicit Histogram Signed-off-by: Arthur Silva Sens --- CHANGELOG.md | 3 +++ specification/compatibility/prometheus_and_openmetrics.md | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8205433da11..bcd4f0e32cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,9 @@ release. ### Compatibility +- Stabilize Prometheus Classic Histogram to OTLP Explicit Histogram transformation. + ([#4874](https://github.com/open-telemetry/opentelemetry-specification/pull/4874)) + ### SDK Configuration ### Supplementary Guidelines diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 97189cded43..825d06e18c0 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -137,9 +137,9 @@ A [Prometheus Unknown](https://prometheus.io/docs/instrumenting/exposition_forma ### Histograms -**Status**: [Development](../document-status.md) +**Status**: [Stable](../document-status.md) -A [Prometheus Histogram](https://prometheus.io/docs/instrumenting/exposition_formats/#basic-info) MUST be converted to an OTLP Histogram. +A [Prometheus Histogram](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram) MUST be converted to an OTLP Histogram. Multiple Prometheus histogram metrics MUST be merged together into a single OTLP Histogram: From 98d370a88339d44b258e0044915a60df3c56ae0e Mon Sep 17 00:00:00 2001 From: Arthur Silva Sens Date: Tue, 17 Feb 2026 16:46:15 -0300 Subject: [PATCH 2/4] Address feedback Signed-off-by: Arthur Silva Sens --- specification/compatibility/prometheus_and_openmetrics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 825d06e18c0..49e41f7479f 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -139,12 +139,12 @@ A [Prometheus Unknown](https://prometheus.io/docs/instrumenting/exposition_forma **Status**: [Stable](../document-status.md) -A [Prometheus Histogram](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram) MUST be converted to an OTLP Histogram. +A [Prometheus Histogram](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram) MUST be converted to an [OTLP Histogram](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#histogram). -Multiple Prometheus histogram metrics MUST be merged together into a single OTLP Histogram: +Prometheus buckets except the +Inf bucket become OpenTelemetry buckets. The Prometheus Histogram Count becomes the OTLP Histogram Count and Prometheus Histogram Sum becomes OTLP Histogram Sum. + +In the text format, Prometheus histograms buckets, count and sum are sent as separate samples and they MUST be merged together when forming an OTLP Histogram. Samples with a `_bucket` suffix will have an `le` label denoting the bucket boundary, whose value is the total count of observations less than the bucket boundary. The count of the OpenTelemetry bucket is computed as the difference between the bucket and the next-lowest bucket, if it exists. Lines with `_count` and `_sum` suffixes are used to determine the histogram's count and sum. -* The `le` label on the `_bucket`-suffixed metric is used to identify and order histogram bucket boundaries. Each Prometheus line produces one bucket count on the resulting histogram. Each value for the `le` label except `+Inf` produces one bucket boundary. -* Lines with `_count` and `_sum` suffixes are used to determine the histogram's count and sum. * If `_count` is not present, the metric MUST be dropped. * If `_sum` is not present, the histogram's sum MUST be unset. From 864ca0c6cde9d417a81ea8b301babdbab5cfb739 Mon Sep 17 00:00:00 2001 From: Arthur Silva Sens Date: Tue, 17 Feb 2026 16:59:52 -0300 Subject: [PATCH 3/4] Fix trailing space in prometheus_and_openmetrics.md Removes trailing space to fix markdownlint MD009 violation. Signed-off-by: Arthur Silva Sens --- specification/compatibility/prometheus_and_openmetrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 49e41f7479f..442897c2a14 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -141,7 +141,7 @@ A [Prometheus Unknown](https://prometheus.io/docs/instrumenting/exposition_forma A [Prometheus Histogram](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram) MUST be converted to an [OTLP Histogram](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#histogram). -Prometheus buckets except the +Inf bucket become OpenTelemetry buckets. The Prometheus Histogram Count becomes the OTLP Histogram Count and Prometheus Histogram Sum becomes OTLP Histogram Sum. +Prometheus buckets except the +Inf bucket become OpenTelemetry buckets. The Prometheus Histogram Count becomes the OTLP Histogram Count and Prometheus Histogram Sum becomes OTLP Histogram Sum. In the text format, Prometheus histograms buckets, count and sum are sent as separate samples and they MUST be merged together when forming an OTLP Histogram. Samples with a `_bucket` suffix will have an `le` label denoting the bucket boundary, whose value is the total count of observations less than the bucket boundary. The count of the OpenTelemetry bucket is computed as the difference between the bucket and the next-lowest bucket, if it exists. Lines with `_count` and `_sum` suffixes are used to determine the histogram's count and sum. From 4b7e98b5e1cf9b7ff78f906484416686e12fe949 Mon Sep 17 00:00:00 2001 From: Arthur Silva Sens Date: Mon, 23 Feb 2026 11:23:16 -0300 Subject: [PATCH 4/4] Clarify behavior of +Inf buckets Signed-off-by: Arthur Silva Sens --- specification/compatibility/prometheus_and_openmetrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 442897c2a14..779f028bc88 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -141,7 +141,7 @@ A [Prometheus Unknown](https://prometheus.io/docs/instrumenting/exposition_forma A [Prometheus Histogram](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram) MUST be converted to an [OTLP Histogram](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#histogram). -Prometheus buckets except the +Inf bucket become OpenTelemetry buckets. The Prometheus Histogram Count becomes the OTLP Histogram Count and Prometheus Histogram Sum becomes OTLP Histogram Sum. +Prometheus bucket boundaries become OTLP explicit bounds, except the +Inf boundary which is dropped. The sample values associated with the Prometheus bucket boundaries become OTLP bucket counts, including the value associated with the +Inf boundary. The Prometheus Histogram Count becomes the OTLP Histogram Count and Prometheus Histogram Sum becomes OTLP Histogram Sum. In the text format, Prometheus histograms buckets, count and sum are sent as separate samples and they MUST be merged together when forming an OTLP Histogram. Samples with a `_bucket` suffix will have an `le` label denoting the bucket boundary, whose value is the total count of observations less than the bucket boundary. The count of the OpenTelemetry bucket is computed as the difference between the bucket and the next-lowest bucket, if it exists. Lines with `_count` and `_sum` suffixes are used to determine the histogram's count and sum.