Skip to content

testutil: add native histogram assertion helpers#2020

Open
pedrampdd wants to merge 1 commit into
prometheus:mainfrom
pedrampdd:testutil-native-histograms-1824
Open

testutil: add native histogram assertion helpers#2020
pedrampdd wants to merge 1 commit into
prometheus:mainfrom
pedrampdd:testutil-native-histograms-1824

Conversation

@pedrampdd

Copy link
Copy Markdown
Contributor

Fixes #1824.

cc @kakkoyun — picking up the proposal from the issue (no PR had been opened for it yet).

What

GatherAndCompare compares metrics via the text exposition format, which carries no representation of native (exponential) histogram buckets — only count and sum. So there is currently no way in testutil to assert on a native histogram's contents. This adds four Gatherer-based helpers:

func GatherAndAssertNativeHistogramExists(g prometheus.Gatherer, name string, labels prometheus.Labels) error
func GatherAndAssertNativeHistogramCount(g prometheus.Gatherer, name string, labels prometheus.Labels, want uint64) error
func GatherAndAssertNativeHistogramSum(g prometheus.Gatherer, name string, labels prometheus.Labels, want, tolerance float64) error
func GatherAndAssertNativeHistogramIntervalCount(g prometheus.Gatherer, name string, labels prometheus.Labels, lower, upper, want, tolerance float64) error

These cover the four capabilities the issue asks for: that a native histogram was gathered, its count, its sum, and the number of observations in an interval.

Design notes

  • Naming follows the existing GatherAndCompare / GatherAndCount family. (The issue floated AssertNativeHistogram*; glad to rename if you prefer.)
  • Labels selector — each helper takes a prometheus.Labels to pick a series, so it works with HistogramVec. nil means "no filter", but it still errors if the name resolves to more than one series, so the selected series is unambiguous.
  • Interval count reconstructs the sparse buckets from the spans + deltas (integer histograms) or absolute counts (float histograms), then estimates the count in the half-open (lower, upper] interval via cumulative rank with log2 interpolation for regular buckets and linear interpolation for the zero bucket — the same approach as PromQL histogram_fraction. Because buckets are exponential it is an estimate, hence the tolerance; aligning the bounds to bucket edges gives an exact result. Total count, by contrast, is exact (no tolerance).
  • ScopeGatherer-only for now (no CollectAndAssert* siblings) to keep the surface small; easy to add the symmetry with CollectAndCompare if wanted.

Tests

White-box tests build real native histograms via NewHistogram / NewHistogramVec and assert through the public API, plus a stub Gatherer to exercise the float-histogram path (no public client API produces those). Covered: integer and float histograms; HistogramVec label selection, ambiguity, and no-match; classic-histogram and non-histogram rejection; zero observations; an observation at exactly 0; negative observations; and both boundary-aligned (exact) and straddling (interpolated — quarter/half-bucket and negative-bucket) interval counts. go test -race is green; gofmt and go vet are clean.

The text-based GatherAndCompare cannot represent native (exponential)
histograms, so there was previously no way to assert on them in tests.

Add four Gatherer-based helpers that select a series by name and optional
labels and verify a native histogram:

  - GatherAndAssertNativeHistogramExists
  - GatherAndAssertNativeHistogramCount
  - GatherAndAssertNativeHistogramSum (within a tolerance)
  - GatherAndAssertNativeHistogramIntervalCount

The interval helper reconstructs the sparse buckets from the spans and
deltas and estimates the number of observations in a half-open
(lower, upper] interval using the same log/linear interpolation as
Prometheus' histogram_fraction.

Signed-off-by: pedrampdd <eragon.pedy@gmail.com>
@pedrampdd pedrampdd force-pushed the testutil-native-histograms-1824 branch from 58da3de to 2e51e8f Compare June 8, 2026 22:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Native histograms: testutil to provide ways to verify native histograms

1 participant