OpenMetrics 2.0: option to keep _total and unit suffixes, so switching from OM1 doesn't rename series

[bwplotka]

With io.prometheus.openmetrics2.enabled, the OM2 writer exposes names exactly as passed to the builder. It never appends _total or the unit suffix:

client_java/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetrics2TextFormatWriter.java

Lines 174 to 179 in 9e9deb6

	private void writeCounter(Writer writer, CounterSnapshot snapshot, EscapingScheme scheme)
	throws IOException {
	MetricMetadata metadata = snapshot.getMetadata();
	// OM2: use the original name, no _total or unit suffix appending.
	String counterName = getOriginalMetadataName(metadata, scheme);
	writeMetadataWithName(writer, counterName, "counter", metadata);

This is documented in

client_java/docs/content/exporters/openmetrics2.md

Lines 57 to 77 in 9e9deb6

	## Naming Behavior
	OpenMetrics 2.0 removes OM1 suffix rewriting.
	- Counters do not get `_total` appended automatically.
	- Units do not get appended automatically.
	- Info metrics still end in `_info` because that is required by the spec.
	Examples:
	| Metric builder input | OM1 output | OM2 output |
	| ---------------------------------- | ----------------- | -------------- |
	| `Counter("events")` | `events_total` | `events` |
	| `Counter("events_total")` | `events_total` | `events_total` |
	| `Counter("req").unit(BYTES)` | `req_bytes_total` | `req` |
	| `Counter("req_bytes").unit(BYTES)` | `req_bytes_total` | `req_bytes` |
	| `Info("target")` | `target_info` | `target_info` |
	This means OpenMetrics 2.0 does not apply OM1 suffix behavior such as appending `_total` or unit
	suffixes, while the legacy OpenMetrics 1.0 and Prometheus text formats keep that existing suffix
	behavior.

, e.g. Counter("req").unit(BYTES) is req_bytes_total in OM1 but req in OM2.

The problem is that switching a target from OM1 to OM2 renames every counter, and every metric with a unit, that was instrumented the way client_java has always recommended (Counter.builder().name("events")). Prometheus then stores them as new series, so existing queries, dashboards and alerts silently stop matching.

Note

I hit this with a demo that scrapes the same client_java app with OM1 and OM2 and diffs the stored series: the JVM metrics match (they already have the suffixes in their names), but http_requests_total (OM1) became http_requests (OM2), and http_request_size_bytes_total became http_request_size. Demo: https://35-204-166-191.sslip.io/, code: bwplotka/prometheus#7.

The OM2 spec relaxed _total and the unit suffix from MUST to SHOULD, mainly for OpenTelemetry compatibility (https://github.com/prometheus/docs/blob/605cf81fefc2e8e91f8ba89bb1555ae52a43a318/docs/guides/open_metrics_2_0_migration.md?plain=1#L140). Both are still recommended though (https://github.com/prometheus/docs/blob/605cf81fefc2e8e91f8ba89bb1555ae52a43a318/docs/specs/om/open_metrics_spec_2_0.md?plain=1#L220 and https://github.com/prometheus/docs/blob/605cf81fefc2e8e91f8ba89bb1555ae52a43a318/docs/specs/om/open_metrics_spec_2_0.md?plain=1#L664). Today there is no way to get them in OM2 other than renaming every metric in code; OpenMetrics2Properties has no option for it.

Proposal:

1. add a property, e.g. io.prometheus.openmetrics2.suffixes (or a naming mode), that keeps the OM1 suffix behaviour in the OM2 writer: append _total to counters and the unit suffix where missing, as expositionBaseName already does for OM1.
2. I'd argue it should default to on, so that negotiating OM2 doesn't change any series names, and users who want names exactly as written (e.g. for OTel-style names) can opt out.

For comparison, client_golang keeps the names users register (which by convention include _total and the unit), so there OM1 and OM2 produce the same series.

[zeitlinger]

For comparison, client_golang keeps the names users register

• this is exactly the goal of the redesign - keep names as passed by the user
• this is a major goal of the redesign
• this was the expressed wish of the prometheus maintainers when we discussed this about a year ago

For that reason I would argue that whenever options we add - if any - they should make migration easier for existing applications.

The migration story I planned for would be that everyone who switches to OM2 would also adopt the new convention that metric names are not modified.

Would that work?

[arnabnandy7]

Keeping application-provided names unchanged as the long-term OM2 behavior makes sense.

The migration concern raised here still seems relevant, especially with content negotiation enabled. The same endpoint can serve OM1 and OM2 at the same time, so an existing Counter("events") could appear as events_total to one scraper and events to another. Updating applications, dashboards, alerts, and recording rules may not always be possible in one step.

Would an opt-in migration flag be a reasonable compromise? OM2 could preserve registered names by default, while io.prometheus.openmetrics2.suffixes=true temporarily retains the existing exposition names. Users could enable it while introducing OM2, migrate metric registrations and downstream queries, and then disable it.

The current PR defaults this option to true, but I can change it to false and document it specifically as a migration aid if that better matches the intended design.