OpenMetrics 2.0 Preview

The Prometheus Java client library includes experimental support for the OpenMetrics 2.0 text format.

OpenMetrics 2.0 support is opt-in, experimental, and subject to change while the specification is still in draft.

Enable OpenMetrics 2.0

To switch OpenMetrics responses from the legacy OM1 writer to the OM2 writer, set:

io.prometheus.openmetrics2.enabled=true

Programmatic configuration:

PrometheusProperties properties = PrometheusProperties.builder()
    .enableOpenMetrics2(om2 -> {})
    .build();

Enabling enableOpenMetrics2(...) also enables the top-level enabled flag automatically, so you only need to configure the sub-flags you want.

With enabled=true alone:

OpenMetrics requests use the OM2 writer.
Registered metric names are preserved; the required _info suffix is still emitted for info metrics.
Optional OM2 features such as composite_values, exemplar_compliance, and native_histograms remain off.

To enable OM2 only when the scraper explicitly requests version=2.0.0, set:

io.prometheus.openmetrics2.enabled=true
io.prometheus.openmetrics2.content_negotiation=true

Programmatic equivalent:

PrometheusProperties properties = PrometheusProperties.builder()
    .enableOpenMetrics2(om2 -> om2.contentNegotiation(true))
    .build();

Naming Behavior

By default, the OpenMetrics 2.0 writer preserves registered metric names:

Counter and unit suffixes are not appended.
Info metrics end in _info because that is required by the spec.

Set suffixes=true to append missing counter and unit suffixes. Existing suffixes are not duplicated.

Examples:

Metric builder input	OM1 output	Default 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`

To retain the previous OM1-compatible suffix behavior during migration, set:

io.prometheus.openmetrics2.suffixes=true

Feature Flags

OpenMetrics 2.0 feature flags default to false. Set suffixes=true to preserve OM1 series names while migrating.

Property	Effect
`io.prometheus.openmetrics2.enabled`	Enable the OpenMetrics 2.0 writer.
`io.prometheus.openmetrics2.content_negotiation`	Apply OM2 behavior only when the scraper requests `version=2.0.0`.
`io.prometheus.openmetrics2.composite_values`	Emit histograms, summaries, and gauge histograms as single composite lines with `st@`.
`io.prometheus.openmetrics2.exemplar_compliance`	Emit only OM2-compliant exemplars with timestamps.
`io.prometheus.openmetrics2.native_histograms`	Emit OM2 native histogram text fields.
`io.prometheus.openmetrics2.suffixes`	Append counter and unit suffixes to preserve OM1 series names (opt-in).

Enable all flags at once:

PrometheusProperties properties = PrometheusProperties.builder()
    .enableOpenMetrics2(om2 -> om2.enableAll())
    .build();

Equivalent properties:

io.prometheus.openmetrics2.enabled=true
io.prometheus.openmetrics2.content_negotiation=true
io.prometheus.openmetrics2.composite_values=true
io.prometheus.openmetrics2.exemplar_compliance=true
io.prometheus.openmetrics2.native_histograms=true
io.prometheus.openmetrics2.suffixes=true

Content Negotiation

If content_negotiation=false, OpenMetrics 2.0 behavior is applied to OpenMetrics responses even if the scraper requested OpenMetrics 1.0.

If content_negotiation=true, OpenMetrics 2.0 behavior is only used when the scraper explicitly requests version=2.0.0. Otherwise the legacy OpenMetrics 1.0 response is returned.

Native Histograms

With io.prometheus.openmetrics2.native_histograms=true, the OpenMetrics 2.0 writer emits native histogram fields such as:

schema
zero_threshold
zero_count
positive and negative spans
positive and negative buckets

OM2 native histogram output can coexist with classic histogram buckets. When both are present, the native histogram sample is written first.