OpenMetrics 2.0: Migration Guide by ywwg · Pull Request #2908 · prometheus/docs

ywwg · 2026-03-19T17:10:18Z

Migration guide for SDK authors on how to update SDKs for OM2.0

claude did the initial drafting and then I went over it carefully and refined / corrected based on my own understanding.

- MetricFamily name must match MetricName subsection with counter example - Counter _total SHOULD and Info _info MUST suffix rules with tradeoff tip - Reserved suffixes warning with collision scenario - Realistic multi-metric OM 2.0 exposition example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add Metric Name Quoting subsection with regex and escaping rules - Add Label Name Quoting subsection with regex pattern - Add Alternative Brace Syntax subsection with TYPE/UNIT/HELP example - OTel bridge motivation opener with cross-ref to _total tradeoff Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Link to both Naming Changes section and Counter and Info Suffix Rules subsection Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Counter before/after: _created sample replaced by inline st@ - Histogram before/after: _created replaced by st@ on CompositeValue line - Sample line ordering template: value [timestamp] [st@] [# exemplar...] - Combined practice example with labels, timestamps, st@, and exemplar - Forward link to Exemplars section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Conceptual intro explaining single-line CompositeValue replacing multi-line expanded samples - Counter Value Simplification subsection (DMOD-02) - Summary subsection with MUST rule for count/sum/quantiles (COMP-03, DMOD-01) - Histogram full before/after treatment (COMP-02) - GaugeHistogram full before/after with queue_depth_bytes (COMP-04) - Combined CompositeValues in Practice example with all types Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ive-only subsection - Exponential bucket schema concept explanation - All CompositeValue fields listed (count, sum, schema, zero_threshold, zero_count, spans, buckets) - Span encoding syntax explained with offset:length pairs - Complete native histogram example with st@ timestamp Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…e subsections - Combined Classic and Native subsection with field ordering and example - GaugeHistogram with Native Buckets one-liner with spec link - Native Histograms in Practice example with native-only and combined metrics Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Mandatory timestamps (MAY to MUST) with counter example - Multiple exemplars per sample with two-exemplar example - W3C Trace Context key recommendations (trace_id, span_id) - Size limit relaxation (hard 128-char cap to soft SHOULD NOT) - Histogram exemplar placement shift to CompositeValue line - Spec link to Exemplars section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Insert Quick Reference table after "How to use this guide" section - 16 data rows covering all OM 1.0->2.0 changes from phases 1-7 - 8 group headers linking to main section headings - Individual change names link to subsection anchors - Add closing paragraph with links to full spec and issue tracker Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Signed-off-by: Owen Williams <owen.williams@grafana.com>

docs/tutorials/open_metrics_2_0_migration.md

Signed-off-by: Owen Williams <owen.williams@grafana.com>

docs/tutorials/open_metrics_2_0_migration.md

Signed-off-by: Owen Williams <owen.williams@grafana.com>

…ions - Expand escaping paragraph with ABNF relaxation (BS normal-char) and SHOULD guidance - Add StateSet section documenting MetricGroup terminology change - Add Unknown Type section noting CompositeValue allowance - Add Quick Reference table rows for StateSet and Unknown Type - Add spec cross-reference links for all new content Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Signed-off-by: Owen Williams <owen.williams@grafana.com>

- Add formal Breaking definition to "How to use this guide" section - Change Info _info from Non-breaking to Breaking (TYPE line changes) - Change UTF-8 Names from Breaking to Non-breaking (additive feature) - Change Native Histograms from Breaking to Non-breaking (new feature) - Add HTTP header scope clarification to Content-Type section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Split Counter _total / Info _info into separate rows with correct labels - Change Content-Type to Yes* with footnote about HTTP header scope - Change UTF-8 Names from Yes to No - Change Native Histograms from Yes to No Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Signed-off-by: Owen Williams <owen.williams@grafana.com>

ywwg · 2026-03-20T19:52:26Z

Addressed comments, including the new definition of "breaking" (which is, something that used to be valid in om 1.0 that is invalid in om 2.0)

ywwg and others added 10 commits March 17, 2026 11:24

fix(03-01): add explicit Naming Changes cross-reference in UTF-8 section

29d4a63

- Link to both Naming Changes section and Counter and Info Suffix Rules subsection Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hand edits and fixes

9aaafa1

Signed-off-by: Owen Williams <owen.williams@grafana.com>

ywwg force-pushed the owilliams/om2-migration branch from 8edfbbb to 9aaafa1 Compare March 19, 2026 17:10

ywwg added 2 commits March 19, 2026 13:24

breaking/non-breaking adjustments

1f3ee04

Signed-off-by: Owen Williams <owen.williams@grafana.com>

some more text and edits

875f781

Signed-off-by: Owen Williams <owen.williams@grafana.com>

ywwg marked this pull request as ready for review March 19, 2026 17:46

ywwg commented Mar 19, 2026

View reviewed changes