Experimental OpenMetrics 2.0 support

[zeitlinger]

The OpenMetrics 2.0 spec is nearing completion. We should start implementing experimental support to validate the design and provide early feedback to the spec authors.

All features are behind opt-in flags (off by default) so there's no risk to existing users. The spec is still in draft, so the API is explicitly experimental and subject to change.

Flag design

Top-level gate + individual feature flags. The top-level gate (enableOpenMetrics2())
has no behavioral effect by itself — it just enables the sub-flags. Each sub-flag
independently controls one OM2 feature.

Java builder API:

PrometheusProperties config = PrometheusProperties.builder()
    .enableOpenMetrics2(om2 -> om2
        .contentNegotiation(true)         // version=2.0.0 content type
        .compositeValues(true)            // single-line histogram/summary + st@
        .exemplarCompliance(true)         // mandatory timestamps, no size limit
        .nativeHistograms(true)           // exponential buckets
    )
    .build();

// Or enable everything at once
PrometheusProperties config = PrometheusProperties.builder()
    .enableOpenMetrics2(om2 -> om2.enableAll())
    .build();

Properties equivalent:

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

Flag	Description	Spec reference
contentNegotiation	Gate OM2 features behind content negotiation: only apply them when the scraper requests version=2.0.0, and return OM1 format when the scraper requests OM1. Without this flag, OM2 features are applied even if the scraper requests OM1	Content Type
compositeValues	Single-line Histogram/Summary/GaugeHistogram with inline st@ start timestamp. Also: reserved label prefix __, Histogram Count/Sum always present, bucket values may be float	CompositeValue, Overall Structure
exemplarCompliance	Exemplar timestamps always emitted (MUST in OM2), 128-char LabelSet hard limit removed	Exemplar
nativeHistograms	Exponential buckets with schema, zero threshold/count, pos/neg spans	Native Buckets

All flags default to false.

Suffix handling (_total, unit suffixes) is not an OM2 config flag — it is handled
at scrape time by each format writer. See #1941 for the design.

PR structure

PR 0: Flag infrastructure (#1939) ✅
│     enableOpenMetrics2() builder, OpenMetrics2Properties class,
│     properties parsing — no behavioral changes
│
├── PR 1: contentNegotiation
│
├── PR 2: compositeValues + exemplarCompliance
│
└── PR 3: nativeHistograms

PRs 1–3 all depend only on PR 0 and can be done in parallel.

Suffix handling (#1941) is independent and can proceed in parallel with all of the above.

PR 0: Flag infrastructure (#1939) ✅

• Add enableOpenMetrics2() to PrometheusProperties.Builder
• Add OpenMetrics2Properties class with all flag fields (defaulting to false)
• Wire up properties parsing for io.prometheus.openmetrics2.*
• No behavioral changes — just the config plumbing

PR 1: Content negotiation

• contentNegotiation: only return OM2 format when the scraper explicitly requests version=2.0.0. Without this flag, OM2 features are applied even if the scraper requests OM1
• Spec: Content Type

PR 2: CompositeValue + start timestamp + exemplar compliance

• compositeValues:
  • Histogram as single line: foo {count:17,sum:324789.3,bucket:[0.1:8,0.25:10,0.5:11,1.0:14,+Inf:17]} 1.0 st@0.5
  • Summary as single line: bar {count:17,sum:324789.3,quantile:[0.95:123.7,0.99:150.0]}
  • GaugeHistogram as single line with count/sum (not gcount/gsum)
  • _created lines replaced by inline st@ start timestamp
  • _count, _sum, _bucket suffixed lines no longer emitted for these types
  • Reserved label prefix changed from _ to __
  • Histogram/GaugeHistogram Count and Sum always present (MUST, was SHOULD for Sum)
  • Histogram bucket values may be float (SHOULD be integer, was MUST)
  • Spec: CompositeValue, Histogram, Summary
• exemplarCompliance:
  • Exemplar timestamps always emitted (OM2: MUST, was MAY in OM1)
  • 128-char LabelSet hard limit removed

PR 3: Native histograms

• nativeHistograms:
  • Exponential bucket model: schema (-4 to 8), zero threshold/count, positive/negative spans and buckets
  • Text serialization: {count:X,sum:X,schema:N,zero_threshold:F,zero_count:X,positive_spans:[...],positive_buckets:[...]}
  • Can coexist with classic buckets on separate lines (native line MUST come first)
  • GaugeHistogram also supports native buckets (same syntax)
  • Multiple exemplars per native histogram sample
  • Spec: Native Buckets, Histogram
• No known blockers:
  • NHCB federation (#312) — still open but WG decided it won't change the spec (solution is a Prometheus scraping config, not an OM change)
  • Exemplar timestamps (#308) — closed, resolved as MUST. We're aligned

Notes

• UTF-8 metric/label names are already supported (shipped in a previous release)
• The OM2 spec is still draft — some details may change, but no known blockers for the features covered here
• See also: OM 2.0 upgrade guide for SDK maintainers

[zeitlinger]

@ArthurSens Question for you: with OM2 relaxing _total from MUST to SHOULD — should client SDKs also stop treating _total as a reserved suffix in validation and sanitization? i.e. stop stripping it from incoming metric names and stop rejecting it?

That would be needed for disableSuffixAppending to work correctly, and would also fix Dropwizard name collisions like #1321.