From f2d28c505408afc9548fbc3ebd7782b18c47473a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Wed, 14 Oct 2026 09:11:17 +0200 Subject: [PATCH] om2/gaugehistogram: prohibit negative count and bucket values MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Even though a negative count may arise from arithmetic operations from on native histograms, we don't believe that the resulting distribution means anything or is useful. Instead of changing the validation of histograms stored in Prometheus , we're making the specification more strict. Note: negative histograms may still be calculated in Prometheus and returned as PromQL query results or used as intermediate values in calculations. As explained by the native histograms specification: https://prometheus.io/docs/specs/native_histograms/#unary-minus-and-negative-histograms Signed-off-by: György Krajcsovits --- docs/specs/om/open_metrics_spec_2_0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 25951e3aa..eb094b8a7 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -339,9 +339,9 @@ GaugeHistograms measure current distributions. Common examples are how long item A GaugeHistogram Sample MUST contain Gcount, Gsum values. -The Gcount value MUST be equal to the number of measurements currently in the GaugeHistogram. The Gcount is a gauge semantically. The Gcount SHOULD be an integer. The Gcount SHOULD NOT be -Inf, +Inf, NAN, or negative. +The Gcount value MUST be equal to the number of measurements currently in the GaugeHistogram. The Gcount is a gauge semantically. The Gcount SHOULD be an integer. The Gcount MUST NOT be negative. The Gcount SHOULD NOT be +Inf, NaN. -Float and negative Gcount is allowed to make it possible to expose results of arithmetic operations on GaugeHistograms, such as the rate of change of a Histogram over time. +Float Gcount is allowed to make it possible to expose results of arithmetic operations on GaugeHistograms, such as the rate of change of a Histogram over time. The Gsum value MUST be equal to the sum of all the measured values currently in the GaugeHistogram. The Gsum is a gauge semantically. @@ -349,9 +349,9 @@ A GaugeHistogram MUST measure values that are not NaN in either [Classic Buckets If a GaugeHistogram stops measuring values in either Classic or Native Buckets and keeps measuring values in the other, it MUST clear and not expose the buckets it stopped measuring into. This avoids exposing different distribution from the two kind of buckets at the same time. -Every Bucket MUST have well-defined boundaries and a value. Boundaries of a Bucket MUST NOT be NaN. Bucket values SHOULD be integers. Semantically, bucket values are gauges and SHOULD NOT be -Inf, +Inf, NaN, or negative. +Every Bucket MUST have well-defined boundaries and a value. Boundaries of a Bucket MUST NOT be NaN. Bucket values SHOULD be integers. Bucket values MUST NOT be negative. Bucket values SHOULD NOT be +Inf, NaN. -Float and negative bucket values are allowed to make it possible to expose results of arithmetic operations on GaugeHistograms, such as the rate of change of a Histogram over time. +Float bucket values are allowed to make it possible to expose results of arithmetic operations on GaugeHistograms, such as the rate of change of a Histogram over time. A GaugeHistogram SHOULD NOT include NaN measurements. If a GaugeHistogram includes NaN measurements, then NaN measurements MUST be counted in the Gcount and the Gsum MUST be NaN.