From 4c85a0970b3f00ea1f43f66677dbc5e8779bf37c Mon Sep 17 00:00:00 2001 From: beorn7 Date: Wed, 13 Aug 2025 15:59:23 +0200 Subject: [PATCH] native histogram spec: Update section about unary minus This clarifies the behavior of unary minus WRT the counter reset hint and that negative histograms are always considered gauges. This concludes https://github.com/prometheus/prometheus/issues/16579 , but we still need sligtly more involved changes here to resolve https://github.com/prometheus/prometheus/issues/16576 . Signed-off-by: beorn7 --- docs/specs/native_histograms.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/specs/native_histograms.md b/docs/specs/native_histograms.md index b219ecad..da16a736 100644 --- a/docs/specs/native_histograms.md +++ b/docs/specs/native_histograms.md @@ -1746,11 +1746,15 @@ be found [below](#functions). The unary minus can be used on native histograms. It returns a histogram where all bucket populations and the count and the sum of observations have their -sign inverted. Everything else stays the same, including the counter reset -hint. Note, however, that explicit counter reset detection will be thrown off -by the inverted signs. (TODO: Maybe we should mark all negative histograms as -gauges?) Negative histograms do not really make sense on their own and are only -supposed to act as intermediate results inside other expressions. +sign inverted. The counter reset hint is set to `GaugeType` in any case. +Everything else stays the same. Enforcing `GaugeType` is needed because +explicit counter reset detection will be thrown off by the inverted sign. + +Generally, histograms with negative bucket populations or a negative count of +observations do not really make sense on their own and are only supposed to act +as intermediate results inside other expressions. They are always considered +gauge histograms within PromQL and when stored as the result of a recording +rule. ### Binary operators