Prometheus translation modes #4533

ArthurSens · 2025-06-02T21:44:39Z

Related to #4494

Changes

This change focuses on three things:

Flexibilization of underscore scaping
Flexibilization of unit and type suffix additions

The goal is to mimic Prometheus' existing configuration that controls the translation of metric names when receiving OTLP metrics via its /otlp endpoint. Configuration alignment will help users migrate in both directions (Prometheus/Collector) when switching their metrics collection systems.

Additional Information

Some further reading might be helpful for reviewers:

Our guide for receiving metrics via OTLP, specifically the [UTF-8 section]

Related issues Update Prometheus spec based on new updates to UTF-8 and name translation in upstream Prometheus #4494
Links to the prototypes (when adding or changing features)
CHANGELOG.md file updated for non-trivial changes
spec-compliance-matrix.md updated if necessary

specification/compatibility/prometheus_and_openmetrics.md

ywwg · 2025-06-10T17:40:17Z

specification/metrics/sdk_exporters/prometheus.md

+- `UnderscoreEscapingWithSuffixes`, the default. This fully escapes metric names for classic Prometheus metric name compatibility, and includes appending type and unit suffixes.
+- `NoUTF8EscapingWithSuffixes` will disable changing special characters to `_`. Special suffixes like units and `_total` for counters will be attached.
+- `NoTranslation`. This strategy bypasses all metric and label name translation, passing them through unaltered.


Prometheus already also has UTF8 with suffixes, we should list that here for permutation completeness

Does it really? I can't see it in the code 🤔

ywwg · 2025-06-10T17:41:12Z

specification/metrics/sdk_exporters/prometheus.md

-A Prometheus Exporter MAY support a configuration option to produce metrics without a [unit suffix](../../compatibility/prometheus_and_openmetrics.md#metric-metadata)
-or UNIT metadata. The option MAY be named `without_units`, and MUST be `false` by default.
+A Prometheus Exporter MAY support a configuration option that controls the translation of metric names from OpenTelemetry Naming Conventions to [Prometheus Naming conventions](https://prometheus.io/docs/practices/naming/).
+If the Prometheus exporter supports such configuration it MUST be named `translation_strategy`, and the translation options MUST be:


I don't think we should enforce the configuration name with MUST, esp because the without_units configuration option MAY be named that as indicated below.

I'm not sure if we're understanding each other here 🤔

I'm adding a MUST for the configuration name to ensure consistency between Prometheus and OTel SDKs and Collector components. That was our goal here, right?

The without_unit existed before this change and was used to control both suffix addition and the inclusion of UNIT metadata. The change I'm proposing is that without_unit doesn't control suffix addition anymore, just the metadata inclusion

specification/metrics/sdk_exporters/prometheus.md

ywwg · 2025-06-10T17:45:53Z

specification/metrics/sdk_exporters/prometheus.md

+For example:
+
+- If configured with `NoTranslation` but the client requests `escaping=underscores`, the exporter MUST apply underscore escaping
+- If configured with `UnderscoreEscapingWithSuffixes` but the client `escaping=allow-utf8`, there's no need to revert what has been translated since the SDK will continue to be compliant.


love this clarification!

ArthurSens · 2025-06-11T13:04:15Z

Folks, I'm out until June 25th. @ywwg is picking this up while I'm gone :)

I've removed the draft mode to help Owen with his notification settings

github-actions · 2025-06-19T03:33:18Z

This PR was marked stale due to lack of activity. It will be closed in 7 days.

ywwg · 2025-06-20T14:03:21Z

not stale

ywwg · 2025-06-20T14:03:38Z

(it won't let me remove the stale label)

## Changes Addressing feedback received during the last Spec SIG meeting, I'm splitting my previous PR(#4533) into two to ensure we keep the scope of the original one for the configuration changes. If I understand correctly, almost all SDKs (if not all) are already compliant since they are wrappers around Prometheus SDKs, and Prometheus SDKs already do content negotiation properly. Then the PoCs are already done :) * [X] Related issues #4494 * [ ] Links to the prototypes (when adding or changing features) * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes * [ ] [`spec-compliance-matrix.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) updated if necessary --------- Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com> Co-authored-by: Reiley Yang <reyang@microsoft.com> Co-authored-by: David Ashpole <dashpole@google.com>

…tion Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

…ddition Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

Co-authored-by: David Ashpole <dashpole@google.com>

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

specification/compatibility/prometheus_and_openmetrics.md

specification/metrics/sdk_exporters/prometheus.md

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

ArthurSens · 2025-07-02T17:45:58Z

The CI failure seems unrelated. Could someone re-trigger it? 😇

ArthurSens mentioned this pull request Jun 4, 2025

sdk_exporters/prometheus: Clarify Content Negotiation #4543

Merged

4 tasks

dashpole reviewed Jun 5, 2025

View reviewed changes

ywwg reviewed Jun 10, 2025

View reviewed changes

specification/metrics/sdk_exporters/prometheus.md Outdated Show resolved Hide resolved

ywwg reviewed Jun 10, 2025

View reviewed changes

ArthurSens marked this pull request as ready for review June 11, 2025 13:03

ArthurSens requested review from a team as code owners June 11, 2025 13:03

github-actions bot added the Stale label Jun 19, 2025

github-actions bot removed the Stale label Jun 21, 2025

This was referenced Jun 23, 2025

Update Prometheus spec based on new updates to UTF-8 and name translation in upstream Prometheus #4494

Open

feat(exporters/prometheus): add explicit option to set naming scheme open-telemetry/opentelemetry-go#6927

Draft

ArthurSens and others added 6 commits June 27, 2025 10:38

sdk_exporters/prometheus: Add 'translation_strategy' configuration op…

a0c9c71

…tion Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

compatibility/prometheus: Flexibilize underscore scaping and suffix a…

ed19ed2

…ddition Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

sdk_exporters/prometheus: Add content negotiation

d86ded8

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

Lint

4272701

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

Update specification/compatibility/prometheus_and_openmetrics.md

f0c63a9

Co-authored-by: David Ashpole <dashpole@google.com>

Update specification/compatibility/prometheus_and_openmetrics.md

e8ee790

Co-authored-by: David Ashpole <dashpole@google.com>

ArthurSens force-pushed the prometheus-translation-modes branch from 591044a to e8ee790 Compare June 27, 2025 13:41

ArthurSens changed the title ~~Prometheus translation modes and content negotiation~~ Prometheus translation modes Jun 27, 2025

Address comments

1067b15

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

dashpole reviewed Jun 27, 2025

View reviewed changes

specification/compatibility/prometheus_and_openmetrics.md Outdated Show resolved Hide resolved

specification/metrics/sdk_exporters/prometheus.md Outdated Show resolved Hide resolved

ArthurSens added 2 commits June 30, 2025 14:05

Improve wording around encoraged/discouraged characters

208dda7

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

Remove 'without_unit' configuration option

a42f10d

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

dashpole approved these changes Jul 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Prometheus translation modes #4533

Prometheus translation modes #4533

Uh oh!

ArthurSens commented Jun 2, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ywwg Jun 10, 2025

Uh oh!

ArthurSens Jun 27, 2025

Uh oh!

ywwg Jun 10, 2025

Uh oh!

ArthurSens Jun 27, 2025

Uh oh!

Uh oh!

ywwg Jun 10, 2025

Uh oh!

ArthurSens commented Jun 11, 2025

Uh oh!

github-actions bot commented Jun 19, 2025

Uh oh!

ywwg commented Jun 20, 2025

Uh oh!

ywwg commented Jun 20, 2025

Uh oh!

Uh oh!

Uh oh!

ArthurSens commented Jul 2, 2025

Uh oh!

Uh oh!

Prometheus translation modes #4533

Are you sure you want to change the base?

Prometheus translation modes #4533

Uh oh!

Conversation

ArthurSens commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Additional Information

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ywwg Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

ArthurSens Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

ywwg Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

ArthurSens Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ywwg Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

ArthurSens commented Jun 11, 2025

Uh oh!

github-actions bot commented Jun 19, 2025

Uh oh!

ywwg commented Jun 20, 2025

Uh oh!

ywwg commented Jun 20, 2025

Uh oh!

Uh oh!

Uh oh!

ArthurSens commented Jul 2, 2025

Uh oh!

Uh oh!

ArthurSens commented Jun 2, 2025 •

edited

Loading