From 5e1b794aa8f23fc4349e1f76ccd64d59acbedad4 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 19 Mar 2026 15:11:03 +0000 Subject: [PATCH 1/6] Prometheus: Stabilize OpenTelemetry to Prometheus Metric Metadata --- CHANGELOG.md | 2 ++ .../prometheus_and_openmetrics.md | 26 ++++++++++--------- 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 139f615e035..23a5c445255 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -63,6 +63,8 @@ release. ([#4962](https://github.com/open-telemetry/opentelemetry-specification/pull/4962)) - Stabilize Prometheus Metadata transformation. ([#4954](https://github.com/open-telemetry/opentelemetry-specification/pull/4954)) +- Stabilize OpenTelemetry Metric Metadata to Prometheus metric metadata. + ([#4966](https://github.com/open-telemetry/opentelemetry-specification/pull/4966)) ### SDK Configuration diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 19f62273c2e..9ecf3931248 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -405,27 +405,29 @@ in keys). ### Metric Metadata -**Status**: [Development](../document-status.md) +**Status**: [Stable](../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 -TYPE comments, but SHOULD NOT drop metric points as a result of conflicting -UNIT or HELP comments. Instead, all but one of the conflicting UNIT and HELP -comments (but not metric points) SHOULD be dropped. If dropping a comment or -metric points, the exporter SHOULD warn the user through error logging. +Prometheus Pull exporters for OpenTelemetry metric data 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 TYPE comments, but SHOULD NOT drop metric points as a result of +conflicting UNIT or HELP comments. Instead, all but one of the conflicting UNIT +and HELP comments (but not metric points) SHOULD be dropped. If dropping a +comment or metric points, the exporter SHOULD warn the user through error +logging. The Name of an OTLP metric MUST be added as the [Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information). -Prometheus naming conventions encourage metric names to match the regular expression: `[a-zA-Z_:]([a-zA-Z0-9_:])*`. Discouraged characters -in the metric name SHOULD be replaced with the `_` character by default, aiming for compatibility with Prometheus conventions. Multiple -consecutive `_` characters SHOULD be replaced with a single `_` character. +Prometheus naming conventions encourage metric names to match the regular +expression: `[a-zA-Z_:]([a-zA-Z0-9_:])*`. Discouraged characters in the metric +name SHOULD be replaced with the `_` character by default, aiming for +compatibility with Prometheus conventions. Multipleconsecutive `_` characters +SHOULD be replaced with a single `_` character. The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in Prometheus when possible. This includes: * Converting from abbreviations to full words (e.g. "ms" to "milliseconds"). * Dropping the portions of the Unit within brackets (e.g. {packet}). Brackets MUST NOT be included in the resulting unit. A "count of foo" is considered unitless in Prometheus. -* Special case: Converting "1" to "ratio". * Converting "foo/bar" to "foo_per_bar". The resulting unit SHOULD be added to the metric as From 4fe0fc55d00ed6f1f1cd22125bc1bd0db1c1ed98 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 2 Apr 2026 09:18:51 -0400 Subject: [PATCH 2/6] Update specification/compatibility/prometheus_and_openmetrics.md Co-authored-by: Joshua MacDonald --- specification/compatibility/prometheus_and_openmetrics.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 9ecf3931248..e65446ecb25 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -414,7 +414,8 @@ conflicting TYPE comments, but SHOULD NOT drop metric points as a result of conflicting UNIT or HELP comments. Instead, all but one of the conflicting UNIT and HELP comments (but not metric points) SHOULD be dropped. If dropping a comment or metric points, the exporter SHOULD warn the user through error -logging. +logging. Note that SDKs are required to [warn the user over duplicate instrument +registration, indicative of the same problem](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#duplicate-instrument-registration). The Name of an OTLP metric MUST be added as the [Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information). From b31b1c12401f111bb9c10bde88eedac98417c113 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 6 Apr 2026 13:05:38 -0400 Subject: [PATCH 3/6] Update specification/compatibility/prometheus_and_openmetrics.md Co-authored-by: Arve Knudsen --- .../compatibility/prometheus_and_openmetrics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index e65446ecb25..6128b9e2790 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -419,11 +419,11 @@ registration, indicative of the same problem](https://opentelemetry.io/docs/spec The Name of an OTLP metric MUST be added as the [Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information). -Prometheus naming conventions encourage metric names to match the regular -expression: `[a-zA-Z_:]([a-zA-Z0-9_:])*`. Discouraged characters in the metric -name SHOULD be replaced with the `_` character by default, aiming for -compatibility with Prometheus conventions. Multipleconsecutive `_` characters -SHOULD be replaced with a single `_` character. +Prometheus naming conventions encourage metric names to match the regular expression: +`[a-zA-Z_:]([a-zA-Z0-9_:])*`. Discouraged characters in the metric name SHOULD +be replaced with the `_` character by default, aiming for compatibility with +Prometheus conventions. Multiple consecutive `_` characters SHOULD be replaced +with a single `_` character. The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in Prometheus when possible. This includes: From 26323e32a5cc42d333c59916821d7a7e5c764550 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 6 Apr 2026 18:24:16 +0000 Subject: [PATCH 4/6] add table of unit conversions --- .../prometheus_and_openmetrics.md | 47 +++++++++++++++---- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 6128b9e2790..fdb7f47100a 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -419,17 +419,46 @@ registration, indicative of the same problem](https://opentelemetry.io/docs/spec The Name of an OTLP metric MUST be added as the [Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information). -Prometheus naming conventions encourage metric names to match the regular expression: -`[a-zA-Z_:]([a-zA-Z0-9_:])*`. Discouraged characters in the metric name SHOULD -be replaced with the `_` character by default, aiming for compatibility with -Prometheus conventions. Multiple consecutive `_` characters SHOULD be replaced -with a single `_` character. +Prometheus naming conventions encourage metric names to match the regular +expression: `[a-zA-Z_:]([a-zA-Z0-9_:])*`. Discouraged characters in the metric +name SHOULD be replaced with the `_` character by default, aiming for +compatibility with Prometheus conventions. Multiple consecutive `_` characters +SHOULD be replaced with a single `_` character. -The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in Prometheus when possible. This includes: +The Unit of an OTLP metric point MUST be converted from the UCUM unit to the +equivalent unit word in Prometheus if it is included in the table below: -* Converting from abbreviations to full words (e.g. "ms" to "milliseconds"). -* Dropping the portions of the Unit within brackets (e.g. {packet}). Brackets MUST NOT be included in the resulting unit. A "count of foo" is considered unitless in Prometheus. -* Converting "foo/bar" to "foo_per_bar". +| UCUM Abbreviation | Prometheus Unit | +| :--- | :--- | +| `d` | `days` | +| `h` | `hours` | +| `min` | `minutes` | +| `s` | `seconds` | +| `ms` | `milliseconds` | +| `us` | `microseconds` | +| `ns` | `nanoseconds` | +| `By` | `bytes` | +| `KiBy` | `kibibytes` | +| `MiBy` | `mebibytes` | +| `GiBy` | `gibibytes` | +| `TiBy` | `tibibytes` | +| `KBy` | `kilobytes` | +| `MBy` | `megabytes` | +| `GBy` | `gigabytes` | +| `TBy` | `terabytes` | +| `m` | `meters` | +| `V` | `volts` | +| `A` | `amperes` | +| `J` | `joules` | +| `W` | `watts` | +| `g` | `grams` | +| `Cel` | `celsius` | +| `Hz` | `hertz` | +| `%` | `percent` | + +Portions of the Unit within brackets (e.g. {packet}) MUST be dropped. + +Units defined as rates over time e.g. "m/s" MUST be converted to "meters_per_second". The resulting unit SHOULD be added to the metric as [UNIT metadata](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metricfamily). From 3438938471157656c9042a34c1a923633c8b81d0 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 7 Apr 2026 18:38:14 +0000 Subject: [PATCH 5/6] update ucum table to fix mistakes --- specification/compatibility/prometheus_and_openmetrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index fdb7f47100a..059db8f8324 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -441,8 +441,8 @@ equivalent unit word in Prometheus if it is included in the table below: | `KiBy` | `kibibytes` | | `MiBy` | `mebibytes` | | `GiBy` | `gibibytes` | -| `TiBy` | `tibibytes` | -| `KBy` | `kilobytes` | +| `TiBy` | `tebibytes` | +| `kBy` | `kilobytes` | | `MBy` | `megabytes` | | `GBy` | `gigabytes` | | `TBy` | `terabytes` | From 5f9ee17063612b7b3a1ab2004b898bef316780f4 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 8 Apr 2026 20:05:36 +0000 Subject: [PATCH 6/6] reference existing table --- .../prometheus_and_openmetrics.md | 34 +++---------------- 1 file changed, 4 insertions(+), 30 deletions(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 059db8f8324..c4d92fc5645 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -426,39 +426,13 @@ compatibility with Prometheus conventions. Multiple consecutive `_` characters SHOULD be replaced with a single `_` character. The Unit of an OTLP metric point MUST be converted from the UCUM unit to the -equivalent unit word in Prometheus if it is included in the table below: - -| UCUM Abbreviation | Prometheus Unit | -| :--- | :--- | -| `d` | `days` | -| `h` | `hours` | -| `min` | `minutes` | -| `s` | `seconds` | -| `ms` | `milliseconds` | -| `us` | `microseconds` | -| `ns` | `nanoseconds` | -| `By` | `bytes` | -| `KiBy` | `kibibytes` | -| `MiBy` | `mebibytes` | -| `GiBy` | `gibibytes` | -| `TiBy` | `tebibytes` | -| `kBy` | `kilobytes` | -| `MBy` | `megabytes` | -| `GBy` | `gigabytes` | -| `TBy` | `terabytes` | -| `m` | `meters` | -| `V` | `volts` | -| `A` | `amperes` | -| `J` | `joules` | -| `W` | `watts` | -| `g` | `grams` | -| `Cel` | `celsius` | -| `Hz` | `hertz` | -| `%` | `percent` | +equivalent unit word in Prometheus if it is included in the +table in [Metric Metadata above](#metric-metadata). Portions of the Unit within brackets (e.g. {packet}) MUST be dropped. -Units defined as rates over time e.g. "m/s" MUST be converted to "meters_per_second". +Units defined as rates over time (e.g. "m/s") MUST be converted to words (e.g. +"meters_per_second"). The resulting unit SHOULD be added to the metric as [UNIT metadata](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metricfamily).