From 5c9258985632689cdd02e4110f94d0d4f99ded0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Fri, 13 Jun 2025 13:20:47 +0200 Subject: [PATCH 1/3] feat(om2): relax the rules around unit and total suffixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: György Krajcsovits --- docs/specs/om/open_metrics_spec_2_0.md | 27 +++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 675b3d0b3..8f75770c9 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -32,6 +32,8 @@ author: Created in 2012, Prometheus has been the default for cloud-native observability since 2015. A central part of Prometheus' design is its text metric exposition format, called the Prometheus exposition format 0.0.4, stable since 2014. In this format, special care has been taken to make it easy to generate, to ingest, and to understand by humans. As of 2020, there are more than 700 publicly listed exporters, an unknown number of unlisted exporters, and thousands of native library integrations using this format. Dozens of ingestors from various projects and companies support consuming it. +Since 2019, OpenTelemetry has emerged as an alternative way to define a metrics data model. There is a need to be able to expose that data model within OpenMetrics, such that the transport of OpenTelemetry metrics signal is feasable and doesn't violate the OpenMetrics specification. + With OpenMetrics, we are cleaning up and tightening the specification with the express purpose of bringing it into IETF. We are documenting a working standard with wide and organic adoption while introducing minimal, largely backwards-compatible, and well-considered changes. As of 2020, dozens of exporters, integrations, and ingestors use and preferentially negotiate OpenMetrics already. Given the wide adoption and significant coordination requirements in the ecosystem, sweeping changes to either the Prometheus exposition format 0.0.4 or OpenMetrics 1.0 are considered out of scope. @@ -124,7 +126,11 @@ MetricFamily names beginning with underscores are RESERVED and MUST NOT be used ###### Suffixes -The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_created" as a counter called "foo" could create a "foo_created" in the text format. +The name of a MetricFamily combined with the type and unit MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. + +The name of a MetricFamily alone SHOULD NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. + +An example would be a gauge called "foo_created" as a counter called "foo" could create a "foo_created" in the text format. Exposers SHOULD avoid names that could be confused with the suffixes that text format sample metric names use. @@ -144,7 +150,9 @@ Type specifies the MetricFamily type. Valid values are "unknown", "gauge", "coun ##### Unit -Unit specifies MetricFamily units. If non-empty, it MUST be a suffix of the MetricFamily name separated by an underscore. Be aware that further generation rules might make it an infix in the text format. +Unit specifies MetricFamily units. If non-empty, it SHOULD be a suffix of the MetricFamily name separated by an underscore. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. + +Be aware that further generation rules might make it an infix in the text format. ##### Help @@ -479,7 +487,9 @@ There are four pieces of metadata: The MetricFamily name, TYPE, UNIT and HELP. If no TYPE is exposed, the MetricFamily MUST be of type Unknown. -If a unit is specified it MUST be provided in a UNIT metadata line. In addition, an underscore and the unit MUST be the suffix of the MetricFamily name. +If a unit is specified it MUST be provided in a UNIT metadata line. + +In addition, an underscore and the unit SHOULD be the suffix of the MetricFamily name. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. A valid example for a foo_seconds metric with a unit of "seconds": @@ -488,13 +498,6 @@ A valid example for a foo_seconds metric with a unit of "seconds": # UNIT foo_seconds seconds ``` -An invalid example, where the unit is not a suffix on the name: - -``` -# TYPE foo counter -# UNIT foo seconds -``` - It is also valid to have: ``` @@ -633,7 +636,9 @@ foo 18.0 456 ##### Counter -The MetricPoint's Total Value Sample MetricName MUST have the suffix `_total`. If present the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`. +The MetricPoint's Total Value Sample MetricName SHOULD have the suffix `_total`. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. + +If present the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`. An example with a Metric with no labels, and a MetricPoint with no timestamp and no created: From c6b003c9f852c93258a9bb442997959f7b097ea9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Mon, 16 Jun 2025 09:26:19 +0200 Subject: [PATCH 2/3] More updates to rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: György Krajcsovits --- docs/specs/om/open_metrics_spec_2_0.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 8f75770c9..37cfc2ea5 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -118,7 +118,11 @@ A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, H ##### Name -MetricFamily names are a string and MUST be unique within a MetricSet. Names SHOULD be in snake_case. Metric names MUST follow the restrictions in the ABNF section. +MetricFamily names are a string and combined with the TYPE and UNIT MUST be unique within a MetricSet. + +MetricFamily names SHOULD be uniq within a MetricSet. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. + +Names SHOULD be in snake_case. Metric names MUST follow the restrictions in the ABNF section. Colons in MetricFamily names are RESERVED to signal that the MetricFamily is the result of a calculation or aggregation of a general purpose monitoring system. @@ -162,7 +166,11 @@ Help is a string and SHOULD be non-empty. It is used to give a brief description A MetricSet is the top level object exposed by OpenMetrics. It MUST consist of MetricFamilies and MAY be empty. -Each MetricFamily name MUST be unique. The same label name and value SHOULD NOT appear on every Metric within a MetricSet. +Each MetricFamily name combined with the TYPE and UNIT MUST be unique. + +Each MetricFamily name SHOULD be unique. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. + +The same label name and value SHOULD NOT appear on every Metric within a MetricSet. 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. @@ -295,7 +303,7 @@ Partial or invalid expositions MUST be considered erroneous in their entirety. ### Protocol Negotiation -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. +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. 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. From 04b56bebe07363fb6aa1e7dc87fe7d59392f8c86 Mon Sep 17 00:00:00 2001 From: George Krajcsovits Date: Thu, 26 Jun 2025 09:41:37 +0200 Subject: [PATCH 3/3] Update docs/specs/om/open_metrics_spec_2_0.md Co-authored-by: David Ashpole Signed-off-by: George Krajcsovits --- docs/specs/om/open_metrics_spec_2_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 37cfc2ea5..511f28072 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -120,7 +120,7 @@ A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, H MetricFamily names are a string and combined with the TYPE and UNIT MUST be unique within a MetricSet. -MetricFamily names SHOULD be uniq within a MetricSet. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. +MetricFamily names SHOULD be unique within a MetricSet. This rule relaxes the requirement in previous versions of OpenMetrics and is intended to facilitate exposing OpenTelemetry data model. For other use cases it is highly recommended to continue to adhere to this rule. Names SHOULD be in snake_case. Metric names MUST follow the restrictions in the ABNF section.