Skip to content

OM2: WIP collab 03.2026 #2851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bwplotka wants to merge 5 commits into from
Closed

OM2: WIP collab 03.2026 #2851

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6317f09
om2: pre rc.0 changes from WG
bwplotka Mar 17, 2026
684ec09
Merge branch 'main' into bwplotka-omwg-review
bwplotka Mar 20, 2026
c940d03
update
bwplotka Mar 20, 2026
85e08c9
Merge branch 'main' into bwplotka-omwg-review
bwplotka Mar 30, 2026
2837d3a
updates
bwplotka Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/specs/om/open_metrics_spec_2_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,9 @@ Labels are key-value pairs consisting of strings.

Label names beginning with one or more underscores are RESERVED and MUST NOT be used unless specified by this standard. Such Label names MAY be used in place of TYPE and UNIT metadata in cases where MetricFamilies' metadata might otherwise be conflicting, such as metric federation cases.

<!---
// MAYBE(post-rc.0): Link to where we explain "UTF-8 metrics may reduce usability"
-->
Label names SHOULD follow the restrictions in the ABNF section under the `label-name` section. Label names MAY be any quoted escaped UTF-8 string as described in the ABNF section. Be aware that exposing UTF-8 metrics may reduce usability.

Empty label values SHOULD be treated as if the label was not present.
Expand Down Expand Up @@ -205,6 +208,10 @@ A MetricFamily MAY have zero or more Metrics. Every Metric within a MetricFamily
MetricFamily name:

* MUST be string.

<!---
// TODO(??) give example of unknown metadata? No meta exposed, two differently name metric families.
-->
Comment on lines +212 to +214
Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<!---
// TODO(??) give example of unknown metadata? No meta exposed, two differently name metric families.
-->

* MUST be unique within a MetricSet.
* MUST be the same as every Metric's Name in the family.

Expand All @@ -218,6 +225,9 @@ MetricFamily names beginning with one or more underscores are RESERVED and MUST

###### Discouraged Suffixes

<!---
// TODO: Double check scrape failure modes e.g. rejection MetricSet vs Sample/MetricFamily.
Copy link
Copy Markdown
Member

@krajorama krajorama Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

asked claude:
Two relevant statements, and they are consistent:

Line 380 (Text Format section): "Partial or invalid expositions MUST be considered erroneous in their entirety." — the whole exposition is rejected, not just the affected metric.

Line 1405 (Size Limits section): "If any single value/metric/exposition exceeds such limits then the whole exposition must be rejected." — same conclusion for size limit violations.

The only exception is line 163: "Ingestors MAY reject such MetricFamily" — which allows per-MetricFamily rejection for discouraged name suffixes, but this is a MAY and is specific to that one case.

So the general rule is whole-exposition rejection, with a narrow carve-out for discouraged suffixes.

Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Proposing an update along those lines, thanks!

Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#2940

-->
MetricFamily name SHOULD NOT end with `_count`, `_sum`, `_gcount`, `_gsum`, `_bucket`. Specifically, a name SHOULD NOT create a MetricName collision when converted to [the OpenMetrics 1.0 Text](https://prometheus.io/docs/specs/om/open_metrics_spec). Ingestors MAY reject such MetricFamily.

A non-compliant example would be a gauge called `foo_bucket` and a histogram called `foo`. Exposers negotiating the older OpenMetrics or Text formats, or ingestors which support only the older data model could end up storing the `foo` histogram in the classic representation (`foo_bucket`, `foo_count`, `foo_sum`), which would clash with the gauge and cause a scrape rejection or dropped data.
Expand All @@ -244,6 +254,9 @@ Each MetricFamily name MUST be unique. The same label name and value SHOULD NOT

There is no specific ordering of MetricFamilies required within a MetricSet. An exposer MAY make an exposition easier to read for humans, for example sort alphabetically if the performance tradeoff makes sense.

<!---
// MAYBE(post-rc.0): What about other info metrics?
-->
If present, an Info MetricFamily called "target_info" per the [Supporting target metadata in both push-based and pull-based systems](#supporting-target-metadata-in-both-push-based-and-pull-based-systems) section below SHOULD be first.

### MetricFamily Types
Expand Down Expand Up @@ -288,6 +301,7 @@ MetricFamilies of Type StateSets MUST have an empty Unit string.

Info metrics are used to expose textual information which SHOULD NOT change during process lifetime. Common examples are an application's version, revision control commit, and the version of a compiler.

// CONSISTENCY: Last pass of Name/name (definition)
Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO

Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// CONSISTENCY: Last pass of Name/name (definition)
<!---
// CONSISTENCY(post-rc.0): Last pass of Name/name (definition)
-->

The MetricFamily name for Info metrics MUST end in `_info`.

MetricFamilies of Type Info MUST have an empty Unit string.
Expand All @@ -306,6 +320,9 @@ The Sum value MUST be equal to the sum of all the measured event values. The Sum

A Histogram MUST measure values that are not NaN in either [Classic Buckets](#classic-buckets) or [Native Buckets](#native-buckets) or both. Measuring NaN is different for Classic and Native Buckets, see in their respective sections.

<!---
// MAYBE(post-rc.0): DRY? common pattern with count.
-->
Every Bucket MUST have well-defined boundaries and a value. The bucket value is called the bucket count colloquially. Boundaries of a Bucket MUST NOT be NaN. Bucket values are counters semantically. Bucket values SHOULD be integers. Bucket values MUST NOT be negative. Bucket values SHOULD NOT be +Inf, NaN.

Float bucket values are allowed to make it possible to expose results of arithmetic operations on histograms, such as addition that may result in values beyond the range of integers.
Expand Down Expand Up @@ -432,6 +449,9 @@ A Sample in a metric with the Unknown Type MUST have a Number or CompositeValue

The OpenMetrics formats are Regular Chomsky Grammars, making writing quick and small parsers possible.

<!---
// MAYBE: Be clear on failure modes.
Copy link
Copy Markdown
Member

@krajorama krajorama Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

asked claude:
Two relevant statements, and they are consistent:

Line 380 (Text Format section): "Partial or invalid expositions MUST be considered erroneous in their entirety." — the whole exposition is rejected, not just the affected metric.

Line 1405 (Size Limits section): "If any single value/metric/exposition exceeds such limits then the whole exposition must be rejected." — same conclusion for size limit violations.

The only exception is line 163: "Ingestors MAY reject such MetricFamily" — which allows per-MetricFamily rejection for discouraged name suffixes, but this is a MAY and is specific to that one case.

So the general rule is whole-exposition rejection, with a narrow carve-out for discouraged suffixes.

Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#2940

-->
Partial or invalid expositions MUST be considered erroneous in their entirety.

> NOTE: Previous versions of [OpenMetrics](https://prometheus.io/docs/specs/om/open_metrics_spec/#protobuf-format) used to specify a [OpenMetric protobuf format](https://github.com/prometheus/OpenMetrics/blob/3bb328ab04d26b25ac548d851619f90d15090e5d/proto/openmetrics_data_model.proto). OpenMetrics 2.0 does not include the protobuf representation. For available formats, including the official [Prometheus protobuf wire format](https://prometheus.io/docs/instrumenting/exposition_formats/#protobuf-format), see [exposition formats documentation](https://prometheus.io/docs/instrumenting/exposition_formats).
Expand All @@ -440,8 +460,10 @@ Partial or invalid expositions MUST be considered erroneous in their entirety.

All ingestor implementations MUST be able to ingest data secured with TLS 1.2 or later. All exposers SHOULD be able to emit data secured with TLS 1.2 or later. Ingestor implementations SHOULD be able to ingest data from HTTP without TLS. All implementations SHOULD use TLS to transmit data.

// TODO: Fix the sentence
Copy link
Copy Markdown
Member

@krajorama krajorama Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what we meant here. Out-of-band means to me that the negotiation isn't part of the OM2.0 text format, which it isn't so that tracks.

Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For example for pull-based exposition over HTTP standard HTTP content type negotiation is used, and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.

This is not really english, still TODO

Negotiation of what version of the OpenMetrics format to use is out-of-band. For example for pull-based exposition over HTTP standard HTTP content type negotiation is used, and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.
Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Negotiation of what version of the OpenMetrics format to use is out-of-band. For example for pull-based exposition over HTTP standard HTTP content type negotiation is used, and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.
Negotiation of what version of the OpenMetrics format to use is out-of-band. For example, for pull-based exposition over HTTP standard, when HTTP content type negotiation is used, it MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.

Copy link
Copy Markdown
Member

@ywwg ywwg Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Negotiation of what version of the OpenMetrics format to use is out-of-band. For example for pull-based exposition over HTTP standard HTTP content type negotiation is used, and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.
Negotiation of which version of the OpenMetrics format to use is out-of-band. For example, for HTTP pull-based exposition, standard HTTP content type negotiation is used and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.


// MAYBE: Exposer? Also fallback to text format?
Copy link
Copy Markdown
Member Author

@bwplotka bwplotka Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// MAYBE: Exposer? Also fallback to text format?

Push-based negotiation is inherently more complex, as the exposer typically initiates the connection. Producers MUST use the oldest version of the standard (i.e. 1.0.0) unless requested otherwise by the ingestor.

### ABNF
Expand Down
Loading