From d2162a6fb9ad1e6648d5608507ca8579e0e8f6c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Thu, 2 Oct 2025 09:15:36 +0200 Subject: [PATCH 1/3] feat(om1.1): relax the requirements around unit and total suffixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Allow exposers to expose metrics that do not put `_total` or unit as suffix to metric names. Signed-off-by: György Krajcsovits --- docs/specs/om/open_metrics_spec_1_1.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/specs/om/open_metrics_spec_1_1.md b/docs/specs/om/open_metrics_spec_1_1.md index 195f71b8e..c34375e1c 100644 --- a/docs/specs/om/open_metrics_spec_1_1.md +++ b/docs/specs/om/open_metrics_spec_1_1.md @@ -144,7 +144,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. Be aware that further generation rules might make it an infix in the text format. + +Be aware that exposing metrics without the unit being a suffix of the MetricFamily name directly to end-users may reduce the usability due to confusion about what the metric's unit is. ##### Help @@ -479,7 +481,7 @@ 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. A valid example for a foo_seconds metric with a unit of "seconds": @@ -488,7 +490,7 @@ 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: +A valid example, where the unit is not a suffix on the name: ``` # TYPE foo counter @@ -633,7 +635,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`. If present the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`. + +Be aware that exposing metrics without `_total` being a suffix of the MetricFamily name directly to end-users may reduce the usability due to confusion about what the metric's type is. An example with a Metric with no labels, and a MetricPoint with no timestamp and no created: @@ -665,6 +669,13 @@ foo_total 17.0 1520879607.789 foo_created 1520430000.123 1520879607.789 ``` +An example with a Metric with no labels, and a MetricPoint without the `_total` suffix and with a timestamp and a created: + +```openmetrics-add-eof +# TYPE foo counter +foo 17.0 1520879607.789 +foo_created 1520430000.123 1520879607.789 + Exemplars MAY be attached to the MetricPoint's Total sample. ##### StateSet From 86c97acd602ceca6c6eacad2d063093b0884e836 Mon Sep 17 00:00:00 2001 From: George Krajcsovits Date: Fri, 3 Oct 2025 16:40:53 +0200 Subject: [PATCH 2/3] Update docs/specs/om/open_metrics_spec_1_1.md Co-authored-by: David Ashpole Signed-off-by: George Krajcsovits --- docs/specs/om/open_metrics_spec_1_1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/om/open_metrics_spec_1_1.md b/docs/specs/om/open_metrics_spec_1_1.md index c34375e1c..d8eebb027 100644 --- a/docs/specs/om/open_metrics_spec_1_1.md +++ b/docs/specs/om/open_metrics_spec_1_1.md @@ -490,7 +490,7 @@ A valid example for a foo_seconds metric with a unit of "seconds": # UNIT foo_seconds seconds ``` -A valid example, where the unit is not a suffix on the name: +A valid, but discouraged example, where the unit is not a suffix on the name: ``` # TYPE foo counter From b8b43724f1d9b33802a219fd25af0a7ca436db89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Mon, 6 Oct 2025 11:31:21 +0200 Subject: [PATCH 3/3] fix example format 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_1_1.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/specs/om/open_metrics_spec_1_1.md b/docs/specs/om/open_metrics_spec_1_1.md index d8eebb027..f5d4f7a92 100644 --- a/docs/specs/om/open_metrics_spec_1_1.md +++ b/docs/specs/om/open_metrics_spec_1_1.md @@ -675,6 +675,7 @@ An example with a Metric with no labels, and a MetricPoint without the `_total` # TYPE foo counter foo 17.0 1520879607.789 foo_created 1520430000.123 1520879607.789 +``` Exemplars MAY be attached to the MetricPoint's Total sample.