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 83.42857% with 29 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.98%. Comparing base (327f564) to head (03ec22e).

Files with missing lines	Patch %	Lines
...try/exporter/prometheus/PrometheusUnitsHelper.java	66.66%	6 Missing and 7 partials ⚠️
.../exporter/prometheus/Otel2PrometheusConverter.java	88.67%	5 Missing and 7 partials ⚠️
...ometheus/internal/PrometheusComponentProvider.java	55.55%	3 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #8346      +/-   ##
============================================
- Coverage     91.04%   90.98%   -0.06%     
- Complexity     7822     7898      +76     
============================================
  Files           893      894       +1     
  Lines         23721    23884     +163     
  Branches       2364     2393      +29     
============================================
+ Hits          21596    21732     +136     
- Misses         1407     1421      +14     
- Partials        718      731      +13

☔ 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

psx95 · 2026-05-01T22:14:29Z

              new LinkedBlockingQueue<>(),
              new DaemonThreadFactory("prometheus-http-server"));
    }
+    HTTPServer.Builder httpServerBuilder = HTTPServer.builder();


Question: Based on the "Interaction with Translation Strategy" spec, I was expecting to see some content negotiation, basically reading accept headers somewhere.

let's park this until open-telemetry/opentelemetry-specification#5062 is resolved.

I revisited this against the clarification in open-telemetry/opentelemetry-specification#5134 and added parameterized coverage in PrometheusHttpServerTest to exercise translation strategy vs negotiated escaping. The new cases show the current behavior matches the clarified model: permissive strategies like NO_TRANSLATION still get restricted by the negotiated Accept escaping, while stricter configured translation is not undone by a more permissive request. This is now covered by commit eef409b.

psx95 · 2026-05-01T22:21:42Z

+
+      assertThat(response.status()).isEqualTo(HttpStatus.OK);
+      assertThat(response.headers().get(HttpHeaderNames.CONTENT_TYPE))
+          .isEqualTo("application/openmetrics-text; version=1.0.0; charset=utf-8");


Shouldn't the accept header here also have the escaping scheme like shown here?

let's park this until open-telemetry/opentelemetry-specification#5062 is resolved.

Yep — I added explicit escaping= variants to the OpenMetrics negotiation tests so we now cover the spec-relevant request shape directly instead of relying only on the generic application/openmetrics-text header. See the new parameterized cases in PrometheusHttpServerTest from commit eef409b.

psx95 · 2026-05-01T22:24:01Z

@@ -239,6 +239,50 @@ void fetchOpenMetrics() {
                + "# EOF\n");
  }



I think there should be more tests that test behavior with other possible escaping schemes?

The spec only mentions two in the examples, but I imagine its because its meant to be non-exhaustive list.

let's park this until open-telemetry/opentelemetry-specification#5062 is resolved.

Agreed. I added parameterized coverage for the key combinations from the clarified spec / content-negotiation behavior: permissive strategy + escaping=underscores, permissive strategy + escaping=allow-utf-8, and stricter configured translation + permissive request. That gives us direct coverage for the non-default escaping-scheme behavior we rely on here. Commit eef409b.

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

jack-berg

Some small comments and ideas. Thanks!

jack-berg · 2026-05-05T21:32:16Z

+    throw new IllegalStateException("Unknown strategy: " + translationStrategy);
+  }
+
+  private static MetricMetadata convertMetadataEscapedWithSuffixes(MetricData metricData) {


I find these convert methods in the weeds and hard to follow / verify. Going to have to trust that you've done the research.

Could help improve the readability by:

Computing the MetricMetadata constructor params in a consistent order the same as MetricMetadata accepts (i.e. name, expositionName, originalName, help, unit)

Using variable names which are the same as the param names of MetricMetadata

Always using the same constructor overload so its explicit which things we're setting to null

For example, applied to this method it might look like:

private static MetricMetadata convertMetadataEscapedWithSuffixes(MetricData metricData) { String name = convertLegacyMetricName(metricData.getName()); name = stripReservedMetricSuffixes(name); String expositionBaseName = name; String originalName = name; String help = metricData.getDescription(); Unit unit = PrometheusUnitsHelper.convertUnit(metricData.getUnit()); if (unit != null && !name.endsWith(unit.toString())) { name = name + "_" + unit; } validateNormalizedMetricName(metricData.getName(), name); return new MetricMetadata(name, expositionBaseName, originalName, help, unit); }

Something to think about to make it easier for humans to reason about / maintain.

Applied to convertMetadataEscapedWithSuffixes (consistent ordering, single 5-arg MetricMetadata ctor) per your example. Left the other three strategy methods as-is for now since they read OK to me; happy to apply the same shape across all four if you'd prefer consistency. Commit 957e2e7.

Hmm... let me think about this more.

Circling back on this one: I went ahead and applied the consistency cleanup across the strategy helpers while keeping the current metadata semantics intact. The methods now compute the metadata pieces in a consistent shape (name, expositionBaseName, originalName, help, unit) before building MetricMetadata, which made them much easier to audit. That landed in commit eef409b.

- 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.

psx95 · 2026-06-12T03:54:14Z

+    }
+  }
+
+  private static Stream<Arguments> translationStrategyContentNegotiationArgs() {


Should we add a test case for unrecognized escaping as well?

The prometheus escaping schemes also contain dots and values which are not supported on the OTel side IIUC, but I imagine someone could send an accept header with such escaping as well.

The Prometheus Java library owns content negotiation for the escaping scheme — unrecognized values fall back to its default behavior. Testing that here would be testing the library rather than OTel translation logic, so I'll leave it out for now.

…n tests 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

		@@ -239,6 +239,50 @@ void fetchOpenMetrics() {
		+ "# EOF\n");
		}

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jack-berg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

zeitlinger commented Apr 29, 2026 •

edited

Loading

codecov Bot commented Apr 29, 2026 •

edited

Loading