Prometheus exporter: Clarify interation between content negotiation and translation strategy

[ArthurSens]

Fixes #5062

Changes

• Related issues [prometheus] Content Negotiation spec is inconsistent with Translation Strategy spec #5062
• Related OTEP(s) #
• Links to the prototypes (when adding or changing features)
• CHANGELOG.md file updated for non-trivial changes
  • For trivial changes, include [chore] in the PR title to skip the changelog check
• Spec compliance matrix updated if necessary
• Declarative config data model is updated if SDK config surface is changed

[ArthurSens]

cc @open-telemetry/prometheus-interoperability

[jack-berg]

@zeitlinger does this align with what you've been working on in open-telemetry/opentelemetry-java#8346?

What are the conditions that would allow a client to actually see metrics conforming to the configured translation strategy? Does a client essentially have to set escaping=allow-utf-8 to avoid the prometheus client library undoing the translation strategy?

[zeitlinger]

@zeitlinger does this align with what you've been working on in open-telemetry/opentelemetry-java#8346?

yes it does

What are the conditions that would allow a client to actually see metrics conforming to the configured translation strategy? Does a client essentially have to set escaping=allow-utf-8 to avoid the prometheus client library undoing the translation strategy?

yes

[quentinmit]

I think we should augment the examples list with all the combinations of translation and header. For example, something like

Examples:
For a counter metric named `foo.bar`:
- With `escaping=underscores` or no `Accept` header (Prometheus's default behavior in Prometheus 2.x):
  - If configured with `UnderscoreEscapingWithSuffixes` (default), the metric will be named `foo_bar_total`
  - If configured with `UnderscoreEscapingWithoutSuffixes`, the metric will be named `foo_bar`
  - If configured with `NoUTF8EscapingWithSuffixes`, the metric will be named `foo_bar_total`
  - if configured with `NoTranslation`, the metric will be named `foo_bar`
- With `escaping=allow-utf-8` (Prometheus's default behavior in Prometheus 3.x):
  - If configured with `UnderscoreEscapingWithSuffixes` (default), the metric will be named `foo_bar_total`
  - If configured with `UnderscoreEscapingWithoutSuffixes`, the metric will be named `foo_bar`
  - If configured with `NoUTF8EscapingWithSuffixes`, the metric will be named `foo.bar_total`
  - if configured with `NoTranslation`, the metric will be named `foo.bar`

I think I have all of those combinations correct. There is no value for translation_strategy that will result in Prometheus 2.x seeing foo_bar_total and Prometheus 3.x seeing foo.bar.

[zeitlinger]

I would do it as a table - but yes, would be great to have this explicit

[zeitlinger]

Yes, the combinations are correct IMO

[quentinmit]

I think it should just explicitly say that content negotiation happens after translation. Something like:

First, `translation_strategy` MUST be applied to construct metric names. Then,
the Prometheus exporter MUST apply content negotiation, which can include
a second translation of metric names.

[quentinmit]

I think we should augment the examples list with all the combinations of translation and header. For example, something like

Examples:
For a counter metric named `foo.bar`:
- With `escaping=underscores` or no `Accept` header (Prometheus's default behavior in Prometheus 2.x):
  - If configured with `UnderscoreEscapingWithSuffixes` (default), the metric will be named `foo_bar_total`
  - If configured with `UnderscoreEscapingWithoutSuffixes`, the metric will be named `foo_bar`
  - If configured with `NoUTF8EscapingWithSuffixes`, the metric will be named `foo_bar_total`
  - if configured with `NoTranslation`, the metric will be named `foo_bar`
- With `escaping=allow-utf-8` (Prometheus's default behavior in Prometheus 3.x):
  - If configured with `UnderscoreEscapingWithSuffixes` (default), the metric will be named `foo_bar_total`
  - If configured with `UnderscoreEscapingWithoutSuffixes`, the metric will be named `foo_bar`
  - If configured with `NoUTF8EscapingWithSuffixes`, the metric will be named `foo.bar_total`
  - if configured with `NoTranslation`, the metric will be named `foo.bar`

I think I have all of those combinations correct. There is no value for translation_strategy that will result in Prometheus 2.x seeing foo_bar_total and Prometheus 3.x seeing foo.bar.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Clarifies how a Prometheus Exporter’s translation_strategy interacts with Prometheus content negotiation, especially when the configured strategy is permissive and may need additional escaping based on the client’s Accept header.

Changes:

• Replaces example bullets with a step-by-step description of applying translation_strategy first, then applying content negotiation (including potentially a second escaping step).
• Adds a concrete example table mapping translation_strategy and requested escaping scheme to resulting metric names.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.