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

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:

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

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?

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.

@arnabnandy7

I'm spelling it out in more detail to make it easier to discuss in the upcoming sig meeting.
@arnabnandy7 please double check I'm getting the use case correctly.

I want to clarify the intended default: OM2 should preserve metric names exactly as registered, like the Go client. Suffixing should not be on by default.

The migration question is whether an opt-in compatibility setting, such as io.prometheus.openmetrics2.suffixes=true, would help existing Java users move over gradually:

Migration step	Producer registers	OM1 exposes	OM2 with default (`suffixes=false`)	OM2 with opt-in compatibility (`suffixes=true`)
Before OM2 is enabled	`Counter("events")`	`events_total`	—	—
Enable OM2; keep compatibility mode off	`Counter("events")`	`events_total`	`events`	—
Enable OM2 compatibility mode	`Counter("events")`	`events_total`	—	`events_total`
Update producers gradually; keep compatibility mode on	A mix of `events` and `events_total`	`events_total`	—	`events_total`
All producers use canonical names; turn compatibility mode off	`Counter("events_total")`	`events_total`	`events_total`	—

With the default, switching to OM2 changes the exposed name for producers still registering events. With compatibility mode enabled, OM2 can retain the OM1 name while producer registrations are updated; consumers can keep querying events_total. Once registrations use canonical names, compatibility mode can be turned off without changing the exposed name.

@zeitlinger

4. I'm spelling it out in more detail to make it easier to discuss in the upcoming sig meeting.
@arnabnandy7 please double check I'm getting the use case correctly.

@zeitlinger yes, this captures the use case correctly.

One small clarification the mix of events and events_total during a gradual migration would normally be across application instances or deployment versions. Registering both in the same registry would cause a collision because they resolve to the same exposition name in compatibility mode.

The same migration flow should also apply to unit suffixes. For example, compatibility mode would keep Counter("req").unit(BYTES) exposed as req_bytes_total while producers gradually move to registering the complete name explicitly.

With those clarifications, suffixes=false by default and suffixes=true as an opt-in migration aid matches the intended behavior.

Navigation Menu

Repository navigation

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

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	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);

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

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

Description

Activity

zeitlinger commented on Oct 7, 2026

arnabnandy7 commented on Oct 7, 2026

zeitlinger commented on Oct 9, 2026

arnabnandy7 commented on Oct 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions