feat(metrics): let native histograms recover lost resolution - #255
Merged
Conversation
`NativeHistogramBuilder` never passed a minimum reset duration to `prometheus-client`, so when a histogram exceeded `max_buckets` the only available mitigation was reducing its schema by one step. Nothing restored the original schema afterwards, making the resolution loss permanent for the lifetime of the process, per label set, and ratcheting further on every subsequent breach. Expose `min_reset_duration` on the builder and forward it to the wrapped configuration. Once the duration has elapsed, a bucket limit breach resets the histogram and restores its configured schema instead of degrading it. The default of one hour bounds any resolution loss; `Duration::ZERO` disables resets and preserves the previous behaviour. Bounding degradation is what makes finer bucket factors practical: callers no longer have to choose a coarse factor purely to stay clear of the bucket cap. Note that a reset also clears the counts, sum, and classic buckets, which is visible as a counter reset in `_bucket`, `_sum`, and `_count` series.
TheJokr
self-requested a review
August 18, 2026 11:00
TheJokr
approved these changes
Aug 18, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
NativeHistogramBuildernever passed a minimum reset duration toprometheus-client, so exceedingmax_bucketsreduced the schema by one step with nothing to restore it. Resolution loss was permanent for the life of the process, per label set, and ratcheted further on each subsequent breach. That forces callers to pick a coarsebucket_factorpurely to stay clear of the cap.Change
Forward
min_reset_durationtoNativeHistogramConfig. Once it has elapsed, a limit breach resets the histogram and restores its configured schema instead of degrading it. Default is one hour;Duration::ZEROdisables resets and preserves the current behaviour. No timer needed because the wrapped crate resets lazily fromreset_if_scheduled, which runs on both the observe and snapshot paths.A reset also clears counts, sum, and classic buckets, so it surfaces as a counter reset in
_bucket/_sum/_count.rate()handles that by design, but worth knowing if you are dual-emitting during a migration.Breaking change
min_reset_durationis a new public field, so full struct-literal initialisers need updating;..NativeHistogramBuilder::new(..)and thewith_*setters are unaffected. Happy to default it insideconfig()without a public field instead if you would rather avoid the break.