Add Prometheus translation strategy support by zeitlinger · Pull Request #8346 · open-telemetry/opentelemetry-java

zeitlinger · 2026-04-29T08:14:27Z

Summary

add TranslationStrategy support to the Prometheus exporter builder and declarative config
upgrade Prometheus client_java to 1.6.1, which provides the released naming support this needs
preserve existing content negotiation behavior, while enabling non-default strategies to use OM2 name-preservation semantics
align underscore-escaping label-name normalization with the OTel Prometheus compatibility rules / prometheus/otlptranslator behavior for invalid characters, repeated underscores, and digit-leading labels
keep OTLP-to-Prometheus naming translation owned by the OTel exporter instead of relying on Prometheus Java naming helpers

Notes

For non-default translation strategies, this intentionally uses only OM2 name-preservation semantics.
No other OM2 features are enabled.
Content negotiation remains unchanged, so OpenMetrics responses still use the legacy OM1 content type by design.
The behavior change from the new Prometheus release is that metric names can now be passed through as-is for the relevant strategies.
prometheus/otlptranslator preserves labels normalized to __...__; Prometheus Java rejects user labels starting with __, so those labels are collapsed to a valid single-underscore form instead.
Prometheus Java is still used for the metrics model and exposition, but it only validates and serializes names here; it does not own the OTLP naming mangling.

References

OTel Prometheus exporter translation strategy spec: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md#translation-strategy
OTel Prometheus/OpenMetrics compatibility normalization rules: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md#metric-attributes
Prometheus Go otlptranslator: https://github.com/prometheus/otlptranslator
Prometheus Go label normalizer used for comparison: https://github.com/prometheus/otlptranslator/blob/main/label_namer.go

Test plan

./gradlew :exporters:prometheus:test --tests io.opentelemetry.exporter.prometheus.PrometheusHttpServerTest.fetchOpenMetrics --tests io.opentelemetry.exporter.prometheus.PrometheusHttpServerTest.fetchOpenMetrics_translationStrategyEnablesOm2 --tests io.opentelemetry.exporter.prometheus.PrometheusMetricReaderTest --tests io.opentelemetry.exporter.prometheus.Otel2PrometheusConverterTest --tests io.opentelemetry.exporter.prometheus.internal.PrometheusMetricReaderProviderTest :sdk-extensions:declarative-config:test --tests io.opentelemetry.sdk.autoconfigure.declarativeconfig.MetricReaderFactoryTest.create_PullPrometheusConfigured

Resolves #8195

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

codecov · 2026-04-29T08:17:39Z

Codecov Report

❌ Patch coverage is 90.85714% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.65%. Comparing base (327f564) to head (9e61219).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
.../exporter/prometheus/Otel2PrometheusConverter.java	90.56%	4 Missing and 6 partials ⚠️
...try/exporter/prometheus/PrometheusUnitsHelper.java	84.61%	3 Missing and 3 partials ⚠️

❌ Your project check has failed because the head coverage (78.36%) is below the target coverage (89.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@              Coverage Diff              @@
##               main    #8346       +/-   ##
=============================================
- Coverage     91.04%   78.65%   -12.39%     
- Complexity     7822     8567      +745     
=============================================
  Files           893     1009      +116     
  Lines         23721    28993     +5272     
  Branches       2364     3599     +1235     
=============================================
+ Hits          21596    22805     +1209     
- Misses         1407     5342     +3935     
- Partials        718      846      +128

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

psx95

Also might wanna look at this relevant spec issue: open-telemetry/opentelemetry-specification#5062

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

jack-berg

Some small comments and ideas. Thanks!

- Replace IllegalArgumentException control flow in PrometheusUnitsHelper.sanitizeUnitName with @nullable return; drop the try/catch in unitOrNull. - Extract doConvert helper so convert is just the IAE try/catch boundary. - Inline the getMergeKey ternary at the putOrMerge call site. - Reorder convertMetadataEscapedWithSuffixes for readability and use the explicit 5-arg MetricMetadata constructor. Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Also bumps protobuf-bom 4.34.1 -> 4.35.0 to match the gencode shipped inside prometheus-metrics-exposition-formats 1.7.0 (runtime must be >= gencode version). Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

## Summary - Adds `MetricMetadata.builder()` with `name`, `help`, `unit`, `counterSuffix` fields - Builder appends unit to the base name when absent, and appends `_total` to `expositionBaseName` when `counterSuffix=true` - Deprecates the 4-arg and 5-arg constructors; internal callers (`MetricMetadataSupport`, `MetricMetadata.escape`) suppress the warning - Updates `docs/apidiffs/current_vs_latest/prometheus-metrics-model.txt` ## Motivation The OTel exporter ([opentelemetry/opentelemetry-java#8346](open-telemetry/opentelemetry-java#8346)) needs to express per-strategy counter intent without pre-computing `expositionBaseName` manually. The builder encapsulates that logic and provides a cleaner public API for any downstream adapter that constructs `MetricMetadata` directly. ## Test plan - [ ] `MetricMetadataTest` — 8 new builder tests covering: no unit, unit absent/present, counter suffix, counter + unit, UTF-8 name, non-counter, name-required validation - [ ] Existing 4-arg/5-arg constructor tests annotated with `@SuppressWarnings("deprecation")` --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger · 2026-06-11T06:35:50Z

Will undraft once the new prom client release has been published.

zeitlinger · 2026-06-11T11:23:55Z

@psx95 please have another look

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

…slation-strategy # Conflicts: # dependencyManagement/build.gradle.kts

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

psx95

Thanks for following up on the updated spec issue, @zeitlinger !

Overall changes LGTM, I just left a couple of small suggestions and mostly verified the translation logic by looking at the tests.

…n tests Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

psx95

Thanks for addressing the feedback!

jack-berg

Re-reviewed. Two more small nits, but still looks good.

jack-berg · 2026-06-16T22:02:49Z

-    String name = sanitizeMetricName(prometheusName(metricData.getName()));
+  private static String convertLegacyMetricName(String name) {
+    if (name.isEmpty()) {
+      return name;


This returns while convertLegacyLabelName throws for the same case. Should be consistent.

jack-berg · 2026-06-16T22:08:52Z

Would be good to have a test to show UNDERSCORE_ESCAPING_WITHOUT_SUFFIXES + allow-utf-8

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger · 2026-06-17T05:41:50Z

@jack-berg done

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Add Prometheus translation strategy support

1ab1fc2

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger mentioned this pull request Apr 29, 2026

Add translation_strategy configuration for Prometheus exporter #8196

Closed

3 tasks

zeitlinger added 7 commits April 29, 2026 08:39

Simplify Prometheus translation strategy mapping

2cc649c

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Restrict Prometheus strategy parsing to declared values

6986009

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Align Prometheus label translation

ae83c7e

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Document Prometheus label reservation

6f1f18f

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Clarify Prometheus translation ownership

7dfbab2

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Own Prometheus name translation

1ad3600

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Fix Prometheus test checkstyle

c59b24d

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger marked this pull request as ready for review April 29, 2026 12:36

zeitlinger requested a review from a team as a code owner April 29, 2026 12:36

jack-berg reviewed Apr 30, 2026

View reviewed changes

psx95 reviewed May 1, 2026

View reviewed changes

github-actions Bot mentioned this pull request May 4, 2026

Pull Request Dashboard #8366

Closed

Address Prometheus translation review comments

671e437

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

jack-berg approved these changes May 5, 2026

View reviewed changes

zeitlinger mentioned this pull request May 6, 2026

Merge colliding Prometheus label values #8364

Open

github-actions Bot mentioned this pull request May 7, 2026

Pull Request Dashboard #8375

Closed

zeitlinger marked this pull request as draft May 8, 2026 06:54

zeitlinger mentioned this pull request May 13, 2026

refactor: use typed Prometheus family descriptors zeitlinger/opentelemetry-java#14

Closed

Bump prometheus client_java 1.6.1 -> 1.7.0

9c20343

Also bumps protobuf-bom 4.34.1 -> 4.35.0 to match the gencode shipped inside prometheus-metrics-exposition-formats 1.7.0 (runtime must be >= gencode version). Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger force-pushed the codex/prometheus-translation-strategy branch from 9e0b450 to 9c20343 Compare June 4, 2026 17:51

zeitlinger mentioned this pull request Jun 8, 2026

feat: add MetricMetadata.Builder, deprecate wide constructors prometheus/client_java#2202

Merged

2 tasks

jack-berg mentioned this pull request Jun 9, 2026

Prometheus exporter: Clarify interation between content negotiation and translation strategy open-telemetry/opentelemetry-specification#5134

Open

6 tasks

jaydeluca approved these changes Jun 9, 2026

View reviewed changes

jaydeluca self-requested a review June 9, 2026 18:35

Use MetricMetadata builder with local Prometheus snapshot

747e64b

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Add Prometheus negotiation coverage and simplify metadata conversion

eef409b

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger added 3 commits June 11, 2026 12:12

Use Prometheus client 1.8.0

9afaa37

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Merge remote-tracking branch 'origin/main' into codex/prometheus-tran…

a6fcd96

…slation-strategy # Conflicts: # dependencyManagement/build.gradle.kts

Apply Spotless formatting

561208a

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger marked this pull request as ready for review June 11, 2026 12:59

github-actions Bot mentioned this pull request Jun 11, 2026

Pull Request Dashboard #8439

Open

psx95 reviewed Jun 12, 2026

View reviewed changes

Address psx95 review: simplify metric name loop and use argumentSet i…

03ec22e

…n tests Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger requested a review from psx95 June 12, 2026 10:13

psx95 approved these changes Jun 12, 2026

View reviewed changes

jack-berg approved these changes Jun 16, 2026

View reviewed changes

Address Prometheus PR review nits

bdf86f7

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger added 2 commits June 17, 2026 10:34

test: cover Prometheus translation edge cases

d9c634f

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

test: cover remaining Prometheus conversion branches

9e61219

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Conversation

zeitlinger commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes

References

Test plan

Uh oh!

codecov Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

psx95 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jack-berg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zeitlinger commented Jun 11, 2026

Uh oh!

zeitlinger commented Jun 11, 2026

Uh oh!

psx95 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

psx95 left a comment

Choose a reason for hiding this comment

Uh oh!

jack-berg left a comment

Choose a reason for hiding this comment

Uh oh!

jack-berg Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

jack-berg Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

zeitlinger commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zeitlinger commented Apr 29, 2026 •

edited

Loading

codecov Bot commented Apr 29, 2026 •

edited

Loading