Skip to content

Drop negative-bucket histogram _sum and _count only in OpenMetrics 1.0 output - #1254

Merged
csmarchbanks merged 3 commits into
prometheus:masterfrom
haeganm:negative-bucket-histogram-count
Nov 13, 2026
Merged

csmarchbanks merged 3 commits into
prometheus:masterfrom
haeganm:negative-bucket-histogram-count

Conversation

@haeganm

@haeganm haeganm commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Histogram leaves out _sum when its lowest bucket is negative, since OpenMetrics 1.0 says a histogram with negative buckets MUST NOT contain a sum. MultiProcessCollector never did that check, so in multiprocess mode the same histogram still had a _sum, OM 1.0 output included:

# Histogram('temp_delta', 'help', buckets=[-1, 0, 1]).observe(-0.5), multiprocess
temp_delta_sum -0.5
temp_delta_bucket{le="-1.0"} 0.0
temp_delta_bucket{le="0.0"} 1.0
temp_delta_bucket{le="1.0"} 1.0
temp_delta_bucket{le="+Inf"} 1.0
temp_delta_count 1.0

OpenMetrics 2.0 goes the other way (every histogram has count and sum), so per review this keeps _sum in Histogram's samples (single and multiprocess) and filters it at exposition instead:

  • Histogram always emits _sum
  • openmetrics.exposition.generate_latest drops _sum and _count for histograms with a negative bucket when version is below 2.0.0, since 1.0 only allows _count alongside a sum (same as HistogramMetricFamily)
  • the histogram docs say which output leaves them out

behavior changes: OM 1.0 scrapes no longer have _count for these, and multiprocess ones lose _sum too (the +Inf bucket still has the count). the classic text format now shows _sum for these histograms in single process too.

test_histogram_negative_buckets in tests/test_multiprocess.py fails on master (b'h_sum' unexpectedly found in the OM 1.0 output) and passes here, and the OM exposition test now checks that 1.0 leaves out _sum and _count (and parses with the library's OM parser) while 2.0 keeps both. full suite passes on 3.12 (Windows), and flake8, isort and mypy are clean.

@csmarchbanks

Histogram leaves out _sum when its lowest bucket is negative, since
OpenMetrics 1.0 doesn't allow a sum there. MultiProcessCollector builds
its own histogram samples and kept the _sum from the mmap files, so the
same histogram exposed an extra series in multiprocess mode.

Drop _sum on the accumulate path when the lowest bucket bound is
negative. merge(accumulate=False) still returns the raw value.

Signed-off-by: Haegan McGarry <haeganm@gmail.com>

@csmarchbanks csmarchbanks left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Since OM 2.0 is adding sum back in everywhere I would learn towards at lest keeping it in the samples. That said, we should probably filter it out in exposition for at least OM 1.0 users.