feat(docs): document classic vs NHCB query result expectations #13689
+10
−0
Conversation
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
Contributor
|
💻 Deploy preview available (feat(docs): document classic vs NHCB query result expectations): |
Signed-off-by: György Krajcsovits <gyorgy.krajcsovits@grafana.com>
krajorama
force-pushed
the
krajo/nhcb-doc-precision
branch
from
33fe227 to
bbf7c63
Compare
tacole02
approved these changes
Nov 28, 2025
Contributor
tacole02
left a comment
tacole02
left a comment
There was a problem hiding this comment.
Docs look good! I left a few minor suggestions. Thank you, @krajorama !
|
|
||
| * [ENHANCEMENT] Add Azure object store workload identity example configuration. #13135 | ||
| * [ENHANCEMENT] Ruler: clarify that internal distributor applies to both operational modes. #13300 | ||
| * [ENHANCEMENT] Native histograms: set expectations on querying classic histograms versus NHCBs. #13689 |
Contributor
There was a problem hiding this comment.
Suggested change
| * [ENHANCEMENT] Native histograms: set expectations on querying classic histograms versus NHCBs. #13689 | |
| * [ENHANCEMENT] Native histograms: Set expectations on querying classic histograms versus NHCBs. #13689 |
|
|
||
| ## Query result equivalence | ||
|
|
||
| NHCBs contain the same information as classic histograms, however that doesn't mean that all queries return exactly the same result. Here are some edge cases when query results may be different. |
Contributor
There was a problem hiding this comment.
Suggested change
| NHCBs contain the same information as classic histograms, however that doesn't mean that all queries return exactly the same result. Here are some edge cases when query results may be different. | |
| NHCBs contain the same information as classic histograms. However, this doesn't mean that all queries return exactly the same result. Here are some edge cases when query results may be different: |
|
|
||
| NHCBs contain the same information as classic histograms, however that doesn't mean that all queries return exactly the same result. Here are some edge cases when query results may be different. | ||
|
|
||
| - Classic histograms are stored in independent series which might be lost or delayed independently from each other, whereas NHCBs are stored in a single series. This means that a classic histogram might be inconsistent compared to an NHCB and query results will be different. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Classic histograms are stored in independent series which might be lost or delayed independently from each other, whereas NHCBs are stored in a single series. This means that a classic histogram might be inconsistent compared to an NHCB and query results will be different. | |
| - Classic histograms are stored in independent series which might be lost or delayed independently from each other, whereas NHCBs are stored in a single series. This means that a classic histogram might be inconsistent compared to an NHCB and query results might differ. |
| NHCBs contain the same information as classic histograms, however that doesn't mean that all queries return exactly the same result. Here are some edge cases when query results may be different. | ||
|
|
||
| - Classic histograms are stored in independent series which might be lost or delayed independently from each other, whereas NHCBs are stored in a single series. This means that a classic histogram might be inconsistent compared to an NHCB and query results will be different. | ||
| - In a normal case when classic histograms series are not lot or delayed, the bucket counts, overall count and sum of observation will be equal between the classic histograms and NHCBs. |
Contributor
There was a problem hiding this comment.
Suggested change
| - In a normal case when classic histograms series are not lot or delayed, the bucket counts, overall count and sum of observation will be equal between the classic histograms and NHCBs. | |
| - In a normal case when classic histograms series are not lost or delayed, the bucket counts, overall count, and sum of observations are equal between the classic histograms and NHCBs. |
|
|
||
| - Classic histograms are stored in independent series which might be lost or delayed independently from each other, whereas NHCBs are stored in a single series. This means that a classic histogram might be inconsistent compared to an NHCB and query results will be different. | ||
| - In a normal case when classic histograms series are not lot or delayed, the bucket counts, overall count and sum of observation will be equal between the classic histograms and NHCBs. | ||
| - Rate, increase, and delta calculation results might differ even when both the classic histograms and NHCBs are in sync. This occurs when the rate interval overlaps with one or more buckets transitioning from being empty to being in use, which can happen if the series just came into existence or when buckets transition from 0 value to some positive value. The reason is that the PromQL function [`rate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate) and related functions use extrapolation that is applied to classic histograms series independently resulting in potentially different 0 points and slope being calculated. For NHCBs the extrapolation is consistent across all buckets. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Rate, increase, and delta calculation results might differ even when both the classic histograms and NHCBs are in sync. This occurs when the rate interval overlaps with one or more buckets transitioning from being empty to being in use, which can happen if the series just came into existence or when buckets transition from 0 value to some positive value. The reason is that the PromQL function [`rate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate) and related functions use extrapolation that is applied to classic histograms series independently resulting in potentially different 0 points and slope being calculated. For NHCBs the extrapolation is consistent across all buckets. | |
| - Rate, increase, and delta calculation results might differ, even when both the classic histograms and NHCBs are in sync. This occurs when the rate interval overlaps with one or more buckets transitioning from being empty to being in use. This can happen if the series just came into existence or when buckets transition from a value of `0` to a positive value. The reason is that the PromQL function [`rate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate) and related functions use extrapolation that is applied to classic histograms series independently resulting in potentially different calculations for `0` points and slopes. For NHCBs, the extrapolation is consistent across all buckets. |
| - Classic histograms are stored in independent series which might be lost or delayed independently from each other, whereas NHCBs are stored in a single series. This means that a classic histogram might be inconsistent compared to an NHCB and query results will be different. | ||
| - In a normal case when classic histograms series are not lot or delayed, the bucket counts, overall count and sum of observation will be equal between the classic histograms and NHCBs. | ||
| - Rate, increase, and delta calculation results might differ even when both the classic histograms and NHCBs are in sync. This occurs when the rate interval overlaps with one or more buckets transitioning from being empty to being in use, which can happen if the series just came into existence or when buckets transition from 0 value to some positive value. The reason is that the PromQL function [`rate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate) and related functions use extrapolation that is applied to classic histograms series independently resulting in potentially different 0 points and slope being calculated. For NHCBs the extrapolation is consistent across all buckets. | ||
| - In general the PromQL warning "input to histogram_quantile needed to be fixed for monotonicity" that sometimes happens for classic histograms should not happen for NHCBs as NHCBs are atomic, self consistent and extrapolated consistently. |
Contributor
There was a problem hiding this comment.
Suggested change
| - In general the PromQL warning "input to histogram_quantile needed to be fixed for monotonicity" that sometimes happens for classic histograms should not happen for NHCBs as NHCBs are atomic, self consistent and extrapolated consistently. | |
| - In general, the PromQL warning "input to histogram_quantile needed to be fixed for monotonicity" that sometimes happens for classic histograms should not happen for NHCBs, as NHCBs are atomic, self-consistent, and extrapolated consistently. |
beorn7
approved these changes
Dec 2, 2025
Contributor
beorn7
left a comment
beorn7
left a comment
There was a problem hiding this comment.
Approving for technically correct content. I leave language to the experts. :)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 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.
What this PR does
Set expectations on classic histograms vs NHCBs when it comes to query results.
Which issue(s) this PR fixes or relates to
Related to #7154
Checklist
CHANGELOG.mdupdated - the order of entries should be[CHANGE],[FEATURE],[ENHANCEMENT],[BUGFIX]. If changelog entry is not needed, please add thechangelog-not-neededlabel to the PR.about-versioning.mdupdated with experimental features.Note
Clarifies query result differences between classic histograms and NHCBs and records the change in the changelog.
## Query result equivalencesection todocs/sources/mimir/send/native-histograms/_custom_buckets.md, clarifying when queries over classic histograms vs NHCBs may differ (inconsistent series, rate/increase/delta extrapolation, monotonicity warning behavior).CHANGELOG.mdwith an enhancement entry noting the new guidance for native histograms vs NHCB queries.Written by Cursor Bugbot for commit bbf7c63. This will update automatically on new commits. Configure here.