Skip to content

fix: Preserve original metric names in OM2 output - #2058

Merged
zeitlinger merged 1 commit into
mainfrom
codex/om2-original-names-docs
Apr 27, 2026
Merged

fix: Preserve original metric names in OM2 output#2058
zeitlinger merged 1 commit into
mainfrom
codex/om2-original-names-docs

Conversation

@zeitlinger

@zeitlinger zeitlinger commented Apr 27, 2026

Copy link
Copy Markdown
Member

Refs #1954.

Summary

This fixes OM2 name preservation in the text writer.

  • Use original metric metadata names in OM2 output instead of OM1 exposition base names.
  • Preserve original names for default classic histogram output instead of delegating that path to OM1.
  • Keep the OM2 _info exception for info metrics.
  • Add builder-based regression coverage for counters and classic/native histograms with .unit(...).

Why

openmetrics2.enabled=true is documented as preserving metric names as written by the application. The writer still used OM1-derived names in several paths, and classic histograms delegated to the OM1 writer, so .unit(...) could still leak unit-suffixed names into OM2 output.

Smoking gun

prometheus-metrics-core/src/test/java/io/prometheus/metrics/core/metrics/OpenMetrics2TextFormatWriterTest.java
adds counterPreservesOriginalNameWhenUnitIsConfigured().

That test builds a real counter through the public builder API:

Counter.builder().name("my_counter").unit(Unit.SECONDS)

It then asserts that OM1 still emits the legacy name my_counter_seconds_total, while OM2 emits
my_counter and does not contain my_counter_seconds.

I verified this test fails against pre-fix origin/main when only the test is applied:

OpenMetrics2TextFormatWriterTest.counterPreservesOriginalNameWhenUnitIsConfigured

Expecting actual:
  "# TYPE my_counter_seconds counter
# UNIT my_counter_seconds seconds
# HELP my_counter_seconds Test counter
my_counter_seconds{method="GET"} 42.0 st@...
# EOF
"
to contain:
  "# TYPE my_counter counter
"

That is the bug this PR fixes: OM2 was still using the OM1 unit-suffixed metric name.

Validation

  • ./mvnw test -pl prometheus-metrics-core,prometheus-metrics-exposition-textformats -am -Dtest=OpenMetrics2TextFormatWriterTest -Dcoverage.skip=true -Dcheckstyle.skip=true -Dsurefire.failIfNoSpecifiedTests=false
  • mise run build
  • mise run lint
  • git diff --check
@zeitlinger zeitlinger changed the title [codex] Fix OM2 metric name preservation Apr 27, 2026
@zeitlinger zeitlinger changed the title docs: Fix OM2 metric name preservation Apr 27, 2026
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
zeitlinger force-pushed the codex/om2-original-names-docs branch from 034ad7a to 4eb69b8 Compare April 27, 2026 08:22
@zeitlinger zeitlinger mentioned this pull request Apr 27, 2026
@zeitlinger
zeitlinger marked this pull request as ready for review April 27, 2026 08:35
@zeitlinger
zeitlinger merged commit 59a7a6d into main Apr 27, 2026
16 checks passed
@zeitlinger
zeitlinger deleted the codex/om2-original-names-docs branch April 27, 2026 11:44
zeitlinger added a commit that referenced this pull request Apr 27, 2026
🤖 I have created a release *beep* *boop*
---


##
[1.6.1](v1.6.0...v1.6.1)
(2026-04-27)


### Bug Fixes

* Preserve original metric names in OM2 output
([#2058](#2058))
([59a7a6d](59a7a6d))


### Documentation

* clarify 1.6.0 release notes
([#2062](#2062))
([9e5d591](9e5d591))
* Document semantic PR title guidance
([#2060](#2060))
([7277889](7277889))

---
> [!IMPORTANT]
> Close and reopen this PR to trigger CI checks.

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
zeitlinger added a commit that referenced this pull request Apr 28, 2026
Fixes #1954.

## Summary

This adds the OpenMetrics 2.0 preview documentation and clarifies
related naming behavior.

- Add a dedicated OpenMetrics 2.0 preview page covering enablement, name
preservation, feature flags, content negotiation, and native histograms.
- Describe `io.prometheus.openmetrics2.enabled` by its observable
behavior: metric names are preserved as written by the application.
- Clarify that OM1/Prometheus text still apply suffix behavior, while
OM2 does not append `_total` or unit suffixes automatically.
- Document the OpenTelemetry exporter `preserve_names` option.

## Notes

The behavior fix is split into #2058. This PR is docs-only.

## Validation

- `mise run lint`
- `git diff --check`

---------

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants