From 5517c4b76ffaae04d22fe7253adc51adfd0367de Mon Sep 17 00:00:00 2001 From: discord9 Date: Mon, 16 Nov 2026 16:26:52 +0800 Subject: [PATCH] refactor(promql): let the legacy histogram path read the native kernel (#10420) * refactor(promql): read the legacy histogram estimators from the native kernel `prom_native_histogram_quantile` and `prom_native_histogram_fraction` estimated from `common_query`'s `NativeHistogram` bucket walk: exponential bucket bounds computed as `2^x`, and a forward walk from the lowest bucket only. The native kernel in `histogram_eval` walks the same histogram the way Prometheus does -- the bound table in `bounds`, and a walk from the highest bucket down once a finite-sum quantile reaches the median -- so one histogram had two answers that differ in their last places. Read the `NativeHistogram` through the borrowed `HistogramView` both representations share and return the kernel's answer, mapping its outcome back onto the NaN-observation notes the legacy UDFs record. Their signatures and the notes are unchanged; only the arithmetic behind them moves. The `2^x` estimator in `common_query::native_histogram` stays for that crate's public API and is annotated as such: no PromQL path reaches it any more. Signed-off-by: discord9 * refactor(promql): delegate the legacy histogram arithmetic to the native kernel `prom_native_histogram_add`, `_sub`, `_mul_scalar`, `_scalar_mul`, `_div_scalar`, `_neg`, the sum/avg accumulators, `delta`/`idelta`/`rate`/`increase`, and the weighted mean that merges partial states all scaled and combined `NativeHistogram`s with that type's own reconciliation: its own zero-bucket widening, schema reduction and custom-bound intersection, over `2^x` bounds. `FloatHistogram::add`/`sub`/`mul`/`div` already implement Prometheus's rules (`addBuckets`, `reconcileZeroBuckets`, `CopyToSchema`, `intersectCustomBucketBounds`) and the native kernel's golden tests cover them, so this keeps one implementation of the semantics. `AddOutcome` folds into the existing semantics rather than being dropped: `custom_bounds_reconciled` is the intersection the kernel keeps in `custom_values`, which the callers already announce from the operands, and `counter_reset_collision` is the contradiction the kernel answers with the unknown hint the legacy arithmetic derived from two hints that disagree; both are asserted in debug builds. The public `NativeHistogram` signatures are unchanged, the sums are compacted as before so `promql_eq` and the serialized spans keep their answers, and unary minus goes through the kernel's multiplication like the other scalings. Signed-off-by: discord9 * test(promql): pin the legacy delegation's observable answers Comparing the bridge against the kernel it calls only shows they agree today; it cannot show what either answer means. These tests pin the answers themselves. - quantile with a NaN sum over several buckets answers 32.0 with NaNSkew, because the NaN walk leaves the last bucket for the interpolation; below the rank it answers NaN with NaNResult. - an exact tie answers 1.0 through the legacy walk and 2.0 through the kernel, on a fixture with an empty bucket between the two, and neither records a note. - assert_same_payload now compares every field, including the start timestamp policy, custom values, the complete span segmentation and the bucket bits. - round-tripping preserves reset hints, custom values, zero-length spans and gaps. - add/sub reconcile the reset hint and the custom bounds, compact cancelled buckets, and keep promql_eq's expanded-index equality. - scale/divide_by keep the field-by-field fallback for an unreadable layout -- mismatched counts, a backwards span, an overflowing index, a negative length -- and preserve its start timestamp; add/sub answer None for the same layouts. Zero, negative and NaN factors are pinned. - rate/increase/delta/idelta/irate clear the start timestamp of a derived histogram, while a single-sample sum aggregate keeps its stored one. A layout whose later span steps backwards is refused before the kernel sees it: the legacy bucket_indices rejected it, while side_from_view would have accepted repeated indices. Signed-off-by: discord9 * test(http): pin the legacy histogram route's rate, NaN quantile and derived windows The delegation changes what three kinds of well-formed data answer, so assert it where a user sees it. Every request runs without the native hint and asserts !executes_fused_series on the observed plan, which proves the legacy route rather than assuming it from the missing hint. - rate and increase over a raw sample with a start timestamp inside the window still extrapolate from the synthetic zero: count 8/3 and sum 10/3 for a rate, 8 and 10 for an increase, with no infos or warnings. - histogram_quantile(0.5) over schema 0, buckets [8, 1], count 10 and a NaN sum answers 32.0 and reports the NaN-observation info, matching Prometheus's walk that leaves the last bucket for the interpolation. The previous estimator answered 2^-0.375. - rate over a raw window answers one series while the same window over h*1 answers none: the derived sample carries no start timestamp, so it has no synthetic zero to extrapolate from. Both phases are covered, memtable and flushed SST. The native-histogram test now installs the route interceptor the way its sibling tests do, so the plan can be observed; all of its original assertions are unchanged. Signed-off-by: discord9 --------- Signed-off-by: discord9 --- pr-histshared-body.md | 117 ++ src/common/query/src/native_histogram.rs | 17 + .../src/extension_plan/fused_series/tests.rs | 5 +- src/promql/src/functions/native_histogram.rs | 120 +- src/promql/src/histogram_eval.rs | 1 + .../src/histogram_eval/float_histogram.rs | 9 +- .../src/histogram_eval/legacy_bridge.rs | 1341 +++++++++++++++++ tests-integration/tests/http.rs | 223 ++- 8 files changed, 1801 insertions(+), 32 deletions(-) create mode 100644 pr-histshared-body.md create mode 100644 src/promql/src/histogram_eval/legacy_bridge.rs diff --git a/pr-histshared-body.md b/pr-histshared-body.md new file mode 100644 index 00000000000..6bcb50a2e29 --- /dev/null +++ b/pr-histshared-body.md @@ -0,0 +1,117 @@ +I hereby agree to the terms of the [GreptimeDB CLA](https://github.com/GreptimeTeam/.github/blob/main/CLA.md). + +## Refer to a related PR or issue link (optional) + +- Follow-up to #10086 / #10178 / #10199, which made the native route read, fold and average stored native histograms. +- Tracking issue: #8887 (native histogram stabilization). + +## What's changed and what's your intention? + +The legacy PromQL path still evaluates histogram UDFs through `common_query::NativeHistogram`, a second +complete implementation of the same arithmetic. The two disagree — `NativeHistogram` computes exponential +bucket bounds as `2^x`, the native kernel uses the bound table; `NativeHistogram` walks quantiles only from +the lowest bucket, the kernel walks from the highest once a finite-sum quantile reaches the median. So one +histogram has two answers that differ in their last places, and a bug fixed in one is still present in the +other. + +This PR makes the legacy path read the native kernel instead of re-deriving the answer. It does not change +`FloatHistogram`, does not touch `servers`/`mito2`/`operator`, and keeps every legacy signature. + +### What moves + +- `histogram_eval/legacy_bridge.rs` (new): borrows a `NativeHistogram` as the `HistogramView` both + representations share, calls `histogram_eval::native::{quantile, fraction}`, and maps the kernel's outcome + back onto the NaN-observation notes the legacy UDFs record. +- The same bridge carries `add` / `sub` / `scale` / `divide_by` onto `FloatHistogram::{add, sub, mul, div}`, + folding `AddOutcome` into the existing semantics. That reaches `neg`, the sum/avg accumulators, + `delta`/`idelta`/`rate`/`increase`, and the arithmetic UDFs. +- `FloatHistogram::spans()` widens to `pub(crate)` (no semantic change) so the bridge can read a view's span + layout. +- `common_query::NativeHistogram` keeps its own estimator for the API surface that still calls it: + `promql_string`, `estimated_stdvar` and `to_prometheus_buckets` share `all_buckets`/`get_bound`, and + `quantile_from_parts` is reached only through `quantile_with_info` (now delegating) and the public + `quantile_histogram_view`. Removing any of it is a separate `common-query` cleanup: that crate cannot + depend on `promql`, and retiring `quantile`/`fraction`/`negated` and `quantile_histogram_view` means + auditing their public API and remaining tests first. + +### Behaviour changes that are not last-place differences + +Delegating means the legacy answers are now the kernel's answers. Six differences are observable, and all +six are cases where the legacy code did something the kernel does not. Three of them change what ordinary, +well-formed data answers and need an explicit decision; the other three are only reachable through input that +violates Prometheus's invariants, so reviewing them is a compatibility call rather than a correctness one. +This list is what two review passes found; it is not claimed to be exhaustive. + +**Well-formed data (decision required)** + +1. **`start_timestamp` is cleared when a histogram is derived from another.** Legacy `add`/`sub`/`scale`/ + `divide_by` kept the input's field; `FloatHistogram` clears it on every operation that derives a value. + That is this module's own policy, documented at `float_histogram.rs`: Prometheus's `FloatHistogram` has no + such field, so nothing here is a Prometheus rule being newly enforced. `rate`, `delta`, `increase`, + `idelta`, the arithmetic UDFs and `-h` therefore answer `start_timestamp = None`. The sum/avg aggregates + clear it only once they combine **two or more** samples: the first sample is passed through untouched, so + a single-row aggregate keeps its stored start timestamp. +2. **`sum = NaN` with more than one bucket.** A NaN sum marks NaN observations, which is legal data. The + kernel reproduces Prometheus's branch that walks the remaining buckets and leaves the last one for the + interpolation, so the answer comes from the top bucket rather than the bucket the rank fell into. For + schema 0, `span(0, 2)`, counts `[8, 1]`, `count = 10`, `q = 0.5`: legacy answered `2^-0.375 ~ 0.7711` + (the bucket the rank lands in), the kernel answers `2^5 = 32`. + `quantile_with_nan_sum_uses_the_last_bucket` pins `32.0`, and `quantile_with_info_is_the_native_quantile` + pins agreement with the kernel across every fixture. +3. **Quantile ties at an exact bucket boundary.** Legacy always walked upward; Prometheus walks from the + highest bucket once a finite-sum quantile reaches 0.5. At an exact tie the two pick different buckets whose + bounds are both defensible; the kernel's answer now wins. + +**Input that violates Prometheus's invariants (reviewer sign-off, not a data-path regression)** + +4. **Zero-bucket widening clamps differently.** Both representations merge every bucket inside the raised + threshold into `zero_count` and remove it from the spans, so the ordinary case agrees. They differ when a + populated bucket straddles the new threshold: the kernel widens the threshold to that bucket's upper bound + instead of splitting it, while legacy decides each bucket by its own upper bound and keeps the straddler. + Legacy also does nothing at all when the threshold is unchanged. +5. **`count` larger than the buckets' total with a finite `sum`.** Legacy returned `NaN`; Prometheus clamps + and interpolates, which the kernel now does. +6. **Custom buckets carrying a positive `zero_count`.** The kernel refuses ("histograms with custom buckets + have no zero bucket") on `zero_count > 0` in the quantile path and `zero_count != 0` in the fraction path, + so legacy now answers `NaN` where it used to estimate. + +Two details that are not semantics: `add`/`sub` still `compact()` the sum so `promql_eq` and the serialized +spans keep their previous answers, and `scale`/`divide_by` fall back to the field-by-field multiplication for +a layout a view cannot express (spans disagreeing with the counts, or a bucket index leaving `i32`) — verified +to still scale such a histogram rather than dropping it, while `add`/`sub` return `None` for it exactly as +before. + +## Verification + +- `cargo nextest run -p promql -p common-query -p datatypes` — **1808 passed, 0 skipped, 0 failed**. +- `cargo clippy -p promql -p common-query --all-targets -- -D warnings` — clean. +- `cargo fmt --all -- --check` — clean. +- Both commits were rebuilt independently and checked: commit 1 alone passes fmt, clippy and + `nextest -p promql -p common-query` (1384 passed). + +Bit-equality tests in `histogram_eval/legacy_bridge.rs` (all passing): + +| test | what it pins | +| --- | --- | +| `quantile_with_info_is_the_native_quantile` | six histograms (custom, gapped exponential, NaN sum, both sides + zero bucket, zero-bucket-only, empty) × 11 quantiles (`-inf, -0.1, 0, 0.001, 0.25, 0.5, 0.75, 1, 1.1, +inf, NaN`), compared with `to_bits()` | +| `fraction_with_info_is_the_native_fraction` | the same shape over eight bound pairs | +| `add_is_the_native_add` / `sub_is_the_native_sub` | bucket counts by index (`to_bits()`) plus `schema`/`zero_threshold`/`count`/`sum`/`zero_count` over five pairs (same layout, schema reduction, zero-threshold growth, mismatched custom bounds, NaN sum) | +| `scale_and_divide_by_are_the_native_mul_and_div` | the same comparison over factors `2, 0.5, -1, 0, +inf` | +| `nan_notes_follow_the_kernel_outcome` | locks the annotation mapping (NaNSkew vs NaNResult vs none) | + +## Checklist + +- [x] I have written the necessary rustdoc comments. +- [x] I have added the necessary unit tests and integration tests. +- [ ] This PR requires documentation updates. +- [ ] API changes are backward compatible. +- [x] Schema or data changes are backward compatible. +- [ ] This PR needs to be backported to release branches, and I have added the `backport-` labels (e.g. `backport-v1.3` targets `release/v1.3`). + +### Notes + +- `NativeHistogram::{add,sub,scale,divide_by,quantile_with_info,fraction_with_info}` remain in `common_query` + (public API, still covered by that crate's own tests) but no PromQL path reaches them any more. Deleting them + is a follow-up in `common_query` alone. +- The next step in this direction is moving the legacy aggregate accumulator onto the native + `HistogramAccumulator` fold/merge, so the sum/avg partial state has one implementation too. diff --git a/src/common/query/src/native_histogram.rs b/src/common/query/src/native_histogram.rs index 637a26644b9..05527b02cc8 100644 --- a/src/common/query/src/native_histogram.rs +++ b/src/common/query/src/native_histogram.rs @@ -984,6 +984,14 @@ fn add_reset_hint(left: CounterResetHint, right: CounterResetHint) -> CounterRes } /// Estimates a quantile from histogram metadata and a lazily materialized bucket sequence. +/// +/// This is the estimator [`NativeHistogram::quantile_with_info`] and [`quantile_histogram_view`] +/// expose, so it stays for callers of this crate. The PromQL `histogram_quantile` does not use it: +/// that function reads the same histogram through the native kernel in the `promql` crate, which +/// walks the buckets the way Prometheus does -- from the highest bucket down for a quantile above +/// the median -- so one histogram has one answer instead of two that differ in their last places. +/// The exponential boundary below interpolates with `2^x`, which likewise stays only for this +/// estimator; the kernel interpolates with `exp2` over Prometheus's bound table. fn quantile_from_parts( q: f64, schema: i32, @@ -1391,6 +1399,15 @@ pub fn exponential_overflow_bucket_index(schema: i32) -> Option { i32::try_from(last_finite.checked_add(1)?).ok() } +/// The bound of bucket `idx`: a custom bound, an infinity sentinel, or `2^(idx / 2^schema)`. +/// +/// The exponential case computes its bound instead of reading one, while Prometheus reads +/// `ExponentialBounds`: those entries are not all correctly rounded, because a bound becomes a zero +/// threshold that is compared exactly, and a computed one would not compare as the sender's did. +/// So the computed bound here agrees with the table the native histogram kernel uses only to within +/// an ulp. This function keeps serving the renderers and the estimators of this crate's public +/// `NativeHistogram` API (`promql_string`, `estimated_stdvar`, the legacy quantile above, the +/// zero-threshold reconciliation in `add`); the PromQL estimators read the kernel's `bound`. fn get_bound(idx: i32, schema: i32, custom_values: &[f64]) -> Option { if schema == CUSTOM_BUCKETS_SCHEMA { return match idx { diff --git a/src/promql/src/extension_plan/fused_series/tests.rs b/src/promql/src/extension_plan/fused_series/tests.rs index a0d21edca07..20740e87025 100644 --- a/src/promql/src/extension_plan/fused_series/tests.rs +++ b/src/promql/src/extension_plan/fused_series/tests.rs @@ -6082,7 +6082,7 @@ async fn decode_state_batches(batches: Vec) -> Vec { assert_eq!(FrameContent::AggregateState, declaration.content()); let series = Arc::new(declaration.series().clone()); let state = Arc::new(declaration.aggregate_state().unwrap().to_owned()); - let decoded = unpack_aggregate_state( + unpack_aggregate_state( Box::pin(RecordBatchStreamAdapter::new( schema, futures::stream::iter(batches.into_iter().map(Ok)), @@ -6093,8 +6093,7 @@ async fn decode_state_batches(batches: Vec) -> Vec { .unwrap() .try_collect::>() .await - .unwrap(); - decoded + .unwrap() } /// State is keyed by the cut aggregate's grouping, not by the tags its scan was bound with. diff --git a/src/promql/src/functions/native_histogram.rs b/src/promql/src/functions/native_histogram.rs index f53a1c3b741..15093f0314d 100644 --- a/src/promql/src/functions/native_histogram.rs +++ b/src/promql/src/functions/native_histogram.rs @@ -39,6 +39,7 @@ use crate::functions::{ MinOverTime, PredictLinear, QuantileOverTime, Rate, StddevOverTime, StdvarOverTime, SumOverTime, extract_array, extract_range_dict, }; +use crate::histogram_eval::legacy_bridge; use crate::range_array::{RangeArray, unpack}; fn extract_histogram_array(value: &ColumnarValue, func_name: &str) -> DfResult { @@ -568,11 +569,11 @@ impl NativeHistogramAdd { } pub fn scalar_udf() -> ScalarUDF { - histogram_pair_udf(Self::name(), NativeHistogram::add) + histogram_pair_udf(Self::name(), legacy_bridge::add) } pub fn scalar_udf_with_collector(collector: Option) -> ScalarUDF { - histogram_pair_udf_with_collector(Self::name(), NativeHistogram::add, collector) + histogram_pair_udf_with_collector(Self::name(), legacy_bridge::add, collector) } } @@ -584,11 +585,11 @@ impl NativeHistogramSub { } pub fn scalar_udf() -> ScalarUDF { - histogram_pair_udf(Self::name(), NativeHistogram::sub) + histogram_pair_udf(Self::name(), legacy_bridge::sub) } pub fn scalar_udf_with_collector(collector: Option) -> ScalarUDF { - histogram_pair_udf_with_collector(Self::name(), NativeHistogram::sub, collector) + histogram_pair_udf_with_collector(Self::name(), legacy_bridge::sub, collector) } } @@ -605,7 +606,7 @@ impl NativeHistogramMulScalar { vec![native_histogram_arrow_type(), DataType::Float64], 0, 1, - |histogram, scalar| Some(histogram.scale(scalar)), + |histogram, scalar| Some(legacy_bridge::scale(&histogram, scalar)), ) } } @@ -623,7 +624,7 @@ impl NativeHistogramScalarMul { vec![DataType::Float64, native_histogram_arrow_type()], 1, 0, - |histogram, scalar| Some(histogram.scale(scalar)), + |histogram, scalar| Some(legacy_bridge::scale(&histogram, scalar)), ) } } @@ -641,7 +642,7 @@ impl NativeHistogramDivScalar { vec![native_histogram_arrow_type(), DataType::Float64], 0, 1, - |histogram, scalar| Some(histogram.divide_by(scalar)), + |histogram, scalar| Some(legacy_bridge::divide_by(&histogram, scalar)), ) } } @@ -654,7 +655,9 @@ impl NativeHistogramNeg { } pub fn scalar_udf() -> ScalarUDF { - histogram_transform_udf(Self::name(), NativeHistogram::negated) + histogram_transform_udf(Self::name(), |histogram| { + legacy_bridge::scale(&histogram, -1.0) + }) } } @@ -814,7 +817,7 @@ impl NativeHistogramQuantile { vec![DataType::Float64], move |histogram, input, row, len, name| { let q = read_scalar_f64_arg(&input[1], row, len, name)?; - let (value, info) = histogram.quantile_with_info(q); + let (value, info) = legacy_bridge::quantile_with_info(histogram, q); if let Some(info) = info { let message = match info { NativeHistogramQuantileInfo::NaNSkew => { @@ -850,7 +853,8 @@ impl NativeHistogramFraction { move |histogram, input, row, len, name| { let lower = read_scalar_f64_arg(&input[1], row, len, name)?; let upper = read_scalar_f64_arg(&input[2], row, len, name)?; - let (value, excluded_nans) = histogram.fraction_with_info(lower, upper); + let (value, excluded_nans) = + legacy_bridge::fraction_with_info(histogram, lower, upper); if excluded_nans { record_info( &collector, @@ -987,7 +991,7 @@ impl NativeHistogramAggregateAccumulator { Some(value) => { record_custom_reconciliation(&self.collector, self.kind.name(), &value, &histogram); let combined = match self.kind { - NativeHistogramAggregateKind::Sum => value.add(&histogram), + NativeHistogramAggregateKind::Sum => legacy_bridge::add(&value, &histogram), NativeHistogramAggregateKind::Avg => { weighted_histogram_mean(value, self.count, histogram, count, combined_count) } @@ -1035,8 +1039,10 @@ fn weighted_histogram_mean( total_count: u64, ) -> Option { let total_count = total_count as f64; - left.scale(left_count as f64 / total_count) - .add(&right.scale(right_count as f64 / total_count)) + legacy_bridge::add( + &legacy_bridge::scale(&left, left_count as f64 / total_count), + &legacy_bridge::scale(&right, right_count as f64 / total_count), + ) } fn range_fold_histograms( @@ -1063,7 +1069,7 @@ fn range_fold_histograms( record_custom_reconciliation(collector, name, &value, &histogram); let next_count = count.checked_add(1)?; let combined = match kind { - NativeHistogramAggregateKind::Sum => value.add(&histogram), + NativeHistogramAggregateKind::Sum => legacy_bridge::add(&value, &histogram), NativeHistogramAggregateKind::Avg => { weighted_histogram_mean(value, count, histogram, 1, next_count) } @@ -2419,9 +2425,7 @@ fn histogram_delta( } if !is_counter { - return samples - .last()? - .sub(samples.first()?) + return legacy_bridge::sub(samples.last()?, samples.first()?) .map(NativeHistogram::into_gauge); } @@ -2433,14 +2437,14 @@ fn histogram_delta( } else { (samples[0].clone(), 1) }; - let mut result = samples.last()?.sub(&initial)?; + let mut result = legacy_bridge::sub(samples.last()?, &initial)?; for index in reset_scan_start..samples.len() { if samples[index].detect_counter_reset( &samples[index - 1], timestamps[index - 1], timestamps[index], ) { - result = result.add(&samples[index - 1])?; + result = legacy_bridge::add(&result, &samples[index - 1])?; } } Some(result.into_gauge()) @@ -2461,11 +2465,11 @@ fn idelta_value( let result = if is_rate && current.detect_counter_reset(previous, previous_ts, current_ts) { current.clone() } else { - current.sub(previous)? + legacy_bridge::sub(current, previous)? }; Some( if is_rate { - result.scale(1.0 / sampled_interval_secs) + legacy_bridge::scale(&result, 1.0 / sampled_interval_secs) } else { result } @@ -2599,7 +2603,7 @@ fn native_extrapolated_rate( continue; }; if synthetic_zero_start && length > 1 { - let Some(with_synthetic_zero) = histogram.add(&samples[0]) else { + let Some(with_synthetic_zero) = legacy_bridge::add(&histogram, &samples[0]) else { record_warning( &collector, format!( @@ -2656,7 +2660,7 @@ fn native_extrapolated_rate( if IS_RATE { factor /= range_length_secs; } - histogram = histogram.scale(factor).into_gauge(); + histogram = legacy_bridge::scale(&histogram, factor).into_gauge(); result.push(Some(histogram)); } @@ -3359,6 +3363,41 @@ mod tests { assert!(histogram.quantile(0.5) < 2.0); } + #[test] + fn sum_aggregate_keeps_the_start_timestamp_of_a_single_sample() { + let mut histogram = sample_histogram(2.0, 3.0, vec![2.0]); + histogram.start_timestamp = Some(1_234); + + let mut accumulator = + NativeHistogramAggregateAccumulator::new(NativeHistogramAggregateKind::Sum, None); + accumulator.push_histogram(histogram, 1).unwrap(); + + assert_eq!( + accumulator.value.unwrap().start_timestamp, + Some(1_234), + "the first sample is passed through untouched, so its start timestamp survives" + ); + } + + #[test] + fn sum_aggregate_clears_the_start_timestamp_once_it_combines_two_samples() { + let mut first = sample_histogram(2.0, 3.0, vec![2.0]); + first.start_timestamp = Some(1_234); + let mut second = sample_histogram(2.0, 3.0, vec![2.0]); + second.start_timestamp = Some(5_678); + + let mut accumulator = + NativeHistogramAggregateAccumulator::new(NativeHistogramAggregateKind::Sum, None); + accumulator.push_histogram(first, 1).unwrap(); + accumulator.push_histogram(second, 1).unwrap(); + + assert_eq!( + accumulator.value.unwrap().start_timestamp, + None, + "a derived sum carries no start timestamp of its own" + ); + } + #[test] fn comparison_observes_explicit_sparse_zero_buckets() { let mut left = sample_histogram(1.0, 1.0, vec![1.0, 0.0]); @@ -3955,6 +3994,41 @@ mod tests { assert_eq!(increase.sum, 4.0); } + /// The raw range functions report a derived difference or quotient, so none of them keeps the + /// start timestamp of the samples it read: the field names the start of the window one sample + /// belongs to, and a result that spans several samples has no single such window. + #[test] + fn raw_range_functions_clear_the_start_timestamp() { + let mut first = sample_histogram(2.0, 2.0, vec![2.0]); + first.start_timestamp = Some(1_000); + let mut last = sample_histogram(4.0, 4.0, vec![4.0]); + last.start_timestamp = Some(2_000); + + for udf in [ + NativeHistogramRate::scalar_udf(), + NativeHistogramIncrease::scalar_udf(), + NativeHistogramDelta::scalar_udf(), + ] { + let name = udf.name().to_string(); + let result = run_extrapolated_histogram_udf(udf, vec![first.clone(), last.clone()]); + assert_eq!( + result.start_timestamp, None, + "{name}: the range functions derive a value of their own" + ); + } + for udf in [ + NativeHistogramIDelta::scalar_udf(), + NativeHistogramIRate::scalar_udf(), + ] { + let name = udf.name().to_string(); + let result = run_histogram_range_udf(udf, vec![first.clone(), last.clone()]); + assert_eq!( + result.start_timestamp, None, + "{name}: the range functions derive a value of their own" + ); + } + } + #[test] fn extrapolated_rate_requires_strictly_in_range_start_timestamp() { for (start_timestamp, range_end, range_length) in [ diff --git a/src/promql/src/histogram_eval.rs b/src/promql/src/histogram_eval.rs index 49215dd9eb7..84e6498ee1e 100644 --- a/src/promql/src/histogram_eval.rs +++ b/src/promql/src/histogram_eval.rs @@ -24,6 +24,7 @@ mod classic; // functions and binary operators, which build on other branches. #[cfg_attr(not(test), allow(dead_code))] pub(crate) mod float_histogram; +pub(crate) mod legacy_bridge; mod native; #[cfg(test)] mod tests; diff --git a/src/promql/src/histogram_eval/float_histogram.rs b/src/promql/src/histogram_eval/float_histogram.rs index a64f3d934e1..015ab028629 100644 --- a/src/promql/src/histogram_eval/float_histogram.rs +++ b/src/promql/src/histogram_eval/float_histogram.rs @@ -123,8 +123,13 @@ impl FloatHistogram { .saturating_add(layout) } - /// The spans of each side. - fn spans(&self) -> [Vec<(i32, i32)>; 2] { + /// The spans of each side: the layout a view was read with, or the compacted layout of a + /// histogram this crate derived. + /// + /// [`crate::histogram_eval::legacy_bridge`] reads them to build the legacy + /// `NativeHistogram`, whose spans are explicit where this type keeps them in the bucket + /// indices. + pub(crate) fn spans(&self) -> [Vec<(i32, i32)>; 2] { self.layout .clone() .unwrap_or_else(|| [&self.positive, &self.negative].map(canonical_spans)) diff --git a/src/promql/src/histogram_eval/legacy_bridge.rs b/src/promql/src/histogram_eval/legacy_bridge.rs new file mode 100644 index 00000000000..a83d47533e2 --- /dev/null +++ b/src/promql/src/histogram_eval/legacy_bridge.rs @@ -0,0 +1,1341 @@ +// Copyright 2023 Greptime Team +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +//! The legacy native-histogram estimators, delegated to the native kernel. +//! +//! `prom_native_histogram_quantile` and `prom_native_histogram_fraction` used to estimate with the +//! bucket walk inside `NativeHistogram` itself: exponential bucket bounds computed as `2^x`, and a +//! forward walk from the lowest bucket only. The native kernel (`histogram_eval`) walks the same +//! histogram the way Prometheus does -- the bound table in `bounds` and, for a quantile above the +//! median of a histogram whose sum is not NaN, a walk from the highest bucket down -- so keeping +//! both estimators leaves two answers for one histogram that differ in their last places. +//! +//! These functions read a [`NativeHistogram`] through the borrowed [`HistogramView`] that both +//! representations share, hand it to the kernel as the [`FloatHistogram`] the kernel owns, and +//! return the answer in the shape the legacy UDFs report it. The scalar arithmetic -- `add`, `sub`, +//! `scale`, `divide_by` -- takes the same route below the estimators, so Prometheus's rules for +//! reconciling a zero bucket, reducing a schema and intersecting custom bounds live in one place. + +use common_query::native_histogram::{ + CounterResetHint, NativeHistogram, NativeHistogramQuantileInfo, Span, +}; +use datafusion::error::Result; +use datatypes::series::histogram::{BucketSideView, HistogramView}; + +use crate::histogram_eval::float_histogram::FloatHistogram; +use crate::histogram_eval::native; + +/// A [`NativeHistogram`] borrowed as a [`HistogramView`], the form the native kernel reads. +/// +/// A view holds its spans as two parallel slices while a `NativeHistogram` holds them as +/// [`Span`]s, so the offsets and lengths are copied here and the counts, bounds and metadata stay +/// borrowed for as long as the view lives. +pub(crate) struct LegacyView<'a> { + histogram: &'a NativeHistogram, + positive_offsets: Vec, + positive_lengths: Vec, + negative_offsets: Vec, + negative_lengths: Vec, +} + +impl<'a> LegacyView<'a> { + pub(crate) fn new(histogram: &'a NativeHistogram) -> Self { + let (positive_offsets, positive_lengths) = span_columns(&histogram.positive_spans); + let (negative_offsets, negative_lengths) = span_columns(&histogram.negative_spans); + Self { + histogram, + positive_offsets, + positive_lengths, + negative_offsets, + negative_lengths, + } + } + + /// The view of the histogram these span columns were taken from. + pub(crate) fn view(&self) -> HistogramView<'_> { + HistogramView { + schema: self.histogram.schema, + zero_threshold: self.histogram.zero_threshold, + sum: self.histogram.sum, + count: self.histogram.count, + zero_count: self.histogram.zero_count, + reset_hint: self.histogram.reset_hint, + start_timestamp: self.histogram.start_timestamp, + custom_values: &self.histogram.custom_values, + positive: BucketSideView { + span_offsets: &self.positive_offsets, + span_lengths: &self.positive_lengths, + buckets: &self.histogram.positive_buckets, + }, + negative: BucketSideView { + span_offsets: &self.negative_offsets, + span_lengths: &self.negative_lengths, + buckets: &self.histogram.negative_buckets, + }, + } + } +} + +fn span_columns(spans: &[Span]) -> (Vec, Vec) { + spans.iter().map(|span| (span.offset, span.length)).unzip() +} + +/// `histogram_quantile(q, histogram)`, with the NaN-observation note the legacy UDF records. +pub(crate) fn quantile_with_info( + histogram: &NativeHistogram, + q: f64, +) -> (f64, Option) { + let view = LegacyView::new(histogram); + match native::quantile(q, &view.view(), &mut Vec::new()) { + Ok(value) => (value, nan_observation_info(histogram, q)), + // The kernel refuses a layout it cannot walk, a custom histogram carrying a zero count + // among them. The legacy estimator reported a histogram it could not read as no estimate, + // which is the same NaN without a note about NaN observations. + Err(_) => (f64::NAN, None), + } +} + +/// `histogram_fraction(lower, upper, histogram)`, with whether NaN observations were excluded. +pub(crate) fn fraction_with_info( + histogram: &NativeHistogram, + lower: f64, + upper: f64, +) -> (f64, bool) { + let view = LegacyView::new(histogram); + match native::fraction(lower, upper, &view.view(), &mut Vec::new()) { + Ok(value) => { + // The same answer the legacy estimator gave: a fraction is degenerate, and reports + // nothing, unless it runs for a non-empty histogram over an increasing pair of bounds. + let excluded_nans = histogram.count != 0.0 + && !lower.is_nan() + && !upper.is_nan() + && lower < upper + && histogram.sum.is_nan() + && bucket_total(histogram) < histogram.count; + (value, excluded_nans) + } + Err(_) => (f64::NAN, false), + } +} + +/// The note for a NaN observation, which the kernel accounts for but does not report. +/// +/// A NaN observation leaves the sum NaN and puts fewer observations in the buckets than the count +/// holds them (Prometheus marks it the same way). The kernel then walks the buckets forward from +/// the lowest, so the note distinguishes the two outcomes: the estimate is skewed higher when the +/// requested rank falls inside the buckets' total, and NaN when it falls past it because the +/// observations the buckets cannot carry were the highest ones. +fn nan_observation_info( + histogram: &NativeHistogram, + q: f64, +) -> Option { + if histogram.count == 0.0 || !(0.0..=1.0).contains(&q) { + return None; + } + let total = bucket_total(histogram); + if !(histogram.sum.is_nan() && total < histogram.count) { + return None; + } + Some(if total < q * histogram.count { + NativeHistogramQuantileInfo::NaNResult + } else { + NativeHistogramQuantileInfo::NaNSkew + }) +} + +/// What the populated buckets hold, summed in the order the kernel walks them: the negative side +/// from its highest index down, the zero bucket, then the positive side upwards. +fn bucket_total(histogram: &NativeHistogram) -> f64 { + let mut total = 0.0; + for count in histogram.negative_buckets.iter().rev() { + total += count; + } + total += histogram.zero_count; + for count in &histogram.positive_buckets { + total += count; + } + total +} + +/// The native kernel's owned form of `histogram`. +/// +/// A view borrows the offsets and lengths it needs from two temporary slices, so the copy happens +/// here and the `FloatHistogram` owns the counts that result. +fn float_histogram(histogram: &NativeHistogram) -> Result { + if steps_backwards(&histogram.positive_spans) || steps_backwards(&histogram.negative_spans) { + return Err(datafusion::error::DataFusionError::Execution( + "native histogram has an invalid layout".into(), + )); + } + let view = LegacyView::new(histogram); + FloatHistogram::try_from_view(&view.view()) +} + +/// Whether a span list steps backwards, which the legacy `bucket_indices` refused. +/// +/// The kernel's `side_from_view` adds each offset to a running index and accepts a later span that +/// steps backwards, so the expanded indices repeat or go negative. Legacy refused such a list +/// outright, so the bridge refuses it too: `add`/`sub` answer `None` as they did, and +/// `scale`/`divide_by` keep their field-by-field fallback. +fn steps_backwards(spans: &[Span]) -> bool { + spans.iter().skip(1).any(|span| span.offset < 0) +} + +/// The legacy representation of `histogram`, with the span layout it carries. +fn legacy_histogram(histogram: &FloatHistogram) -> NativeHistogram { + let [positive, negative] = histogram.spans(); + NativeHistogram { + schema: histogram.schema, + zero_threshold: histogram.zero_threshold, + sum: histogram.sum, + reset_hint: histogram.reset_hint, + start_timestamp: histogram.start_timestamp, + custom_values: histogram.custom_values.clone(), + positive_spans: legacy_spans(positive), + negative_spans: legacy_spans(negative), + count: histogram.count, + zero_count: histogram.zero_count, + positive_buckets: bucket_counts(&histogram.positive), + negative_buckets: bucket_counts(&histogram.negative), + } +} + +fn legacy_spans(spans: Vec<(i32, i32)>) -> Vec { + spans + .into_iter() + .map(|(offset, length)| Span { offset, length }) + .collect() +} + +fn bucket_counts(buckets: &[(i32, f64)]) -> Vec { + buckets.iter().map(|&(_, count)| count).collect() +} + +/// `left + right`, or `None` for a pair the kernel refuses to combine. +pub(crate) fn add(left: &NativeHistogram, right: &NativeHistogram) -> Option { + combine(left, right, false) +} + +/// `left - right`, a gauge histogram the way Prometheus's `-` leaves it. +pub(crate) fn sub(left: &NativeHistogram, right: &NativeHistogram) -> Option { + combine(left, right, true) +} + +fn combine( + left: &NativeHistogram, + right: &NativeHistogram, + subtract: bool, +) -> Option { + let mut combined = float_histogram(left).ok()?; + let other = float_histogram(right).ok()?; + let outcome = if subtract { + combined.sub(&other) + } else { + combined.add(&other) + } + .ok()?; + // The outcome reports what the kernel already folded into the result, and the legacy callers + // report both from the operands before the call: `custom_bounds_reconciled` is the intersection + // the kernel keeps in `custom_values`, which `needs_custom_reconciliation` announces, and a + // `counter_reset_collision` is the contradiction the kernel answers with an unknown hint, which + // is what the legacy arithmetic derived from two hints that disagree. Holding the kernel to + // both keeps a change there from dropping either. + debug_assert_eq!( + outcome.custom_bounds_reconciled, + left.needs_custom_reconciliation(right) + ); + if outcome.counter_reset_collision { + debug_assert_eq!(combined.reset_hint, CounterResetHint::Unknown); + } + if subtract { + combined.reset_hint = CounterResetHint::Gauge; + } + // The legacy arithmetic compacted a sum, so a bucket the two sides cancel out of leaves no + // span behind; the kernel keeps the bucket until a caller drops it. + combined.compact(); + Some(legacy_histogram(&combined)) +} + +/// `histogram * factor`, a gauge histogram for a negative factor. +pub(crate) fn scale(histogram: &NativeHistogram, factor: f64) -> NativeHistogram { + let Ok(mut scaled) = float_histogram(histogram) else { + // A layout the kernel cannot read -- spans that disagree with the counts, or a bucket index + // that leaves `i32` once expanded -- keeps the field-by-field scaling the legacy caller + // had, so such a histogram is still multiplied instead of dropped, and reports its layout + // when it is serialized. Scaling has no bounds to reconcile, so nothing is lost here. + return field_scaled(histogram, factor); + }; + scaled.mul(factor); + legacy_histogram(&scaled) +} + +/// `histogram / divisor`, with no buckets left for a zero divisor. +pub(crate) fn divide_by(histogram: &NativeHistogram, divisor: f64) -> NativeHistogram { + let Ok(mut divided) = float_histogram(histogram) else { + return field_divided(histogram, divisor); + }; + divided.div(divisor); + legacy_histogram(÷d) +} + +fn field_scaled(histogram: &NativeHistogram, factor: f64) -> NativeHistogram { + let mut scaled = histogram.clone(); + scaled.count *= factor; + scaled.zero_count *= factor; + scaled.sum *= factor; + for count in scaled + .positive_buckets + .iter_mut() + .chain(&mut scaled.negative_buckets) + { + *count *= factor; + } + if factor < 0.0 { + scaled.reset_hint = CounterResetHint::Gauge; + } + scaled +} + +fn field_divided(histogram: &NativeHistogram, divisor: f64) -> NativeHistogram { + let mut divided = histogram.clone(); + divided.count /= divisor; + divided.zero_count /= divisor; + divided.sum /= divisor; + if divisor == 0.0 { + divided.positive_spans.clear(); + divided.positive_buckets.clear(); + divided.negative_spans.clear(); + divided.negative_buckets.clear(); + } else { + for count in divided + .positive_buckets + .iter_mut() + .chain(&mut divided.negative_buckets) + { + *count /= divisor; + } + } + if divisor < 0.0 { + divided.reset_hint = CounterResetHint::Gauge; + } + divided +} + +#[cfg(test)] +mod tests { + use common_query::native_histogram::{ + CUSTOM_BUCKETS_SCHEMA, CounterResetHint, NativeHistogram, NativeHistogramQuantileInfo, Span, + }; + use datatypes::series::histogram::{BucketSideView, HistogramView}; + + use super::{ + add, divide_by, float_histogram, fraction_with_info, legacy_histogram, quantile_with_info, + scale, sub, + }; + use crate::histogram_eval::float_histogram::FloatHistogram; + use crate::histogram_eval::native; + + /// Every kind of histogram the legacy representation can hold: exponential and custom, one + /// side and two, a zero bucket, gaps between the spans, a NaN sum standing for NaN + /// observations, and a histogram with no buckets at all. + fn fixtures() -> Vec<(&'static str, NativeHistogram)> { + let mut custom = empty(CUSTOM_BUCKETS_SCHEMA, 0.0, 7.0, 21.0, 0.0); + custom.custom_values = vec![1.0, 2.0, 4.0]; + custom.positive_spans = vec![span(0, 3)]; + custom.positive_buckets = vec![2.0, 0.0, 5.0]; + + let mut spaced = empty(3, 0.0, 6.0, 6.0, 0.0); + spaced.positive_spans = vec![span(-3, 2), span(5, 2)]; + spaced.positive_buckets = vec![2.0, 1.0, 2.5, 0.5]; + + let mut nan_sum = empty(0, 0.0, 10.0, f64::NAN, 0.0); + nan_sum.positive_spans = vec![span(0, 1)]; + nan_sum.positive_buckets = vec![8.0]; + + // With more than one bucket, the kernel's NaN branch walks the remaining buckets and leaves + // the last one behind for the interpolation, so the chosen bucket is not the one the rank + // fell into. A single-bucket fixture cannot reach that path. + let mut nan_sum_multi_bucket = empty(0, 0.0, 10.0, f64::NAN, 0.0); + nan_sum_multi_bucket.positive_spans = vec![span(0, 2)]; + nan_sum_multi_bucket.positive_buckets = vec![8.0, 1.0]; + + let mut both_sides = empty(2, 0.5, 20.0, -3.0, 3.0); + both_sides.positive_spans = vec![span(0, 3)]; + both_sides.positive_buckets = vec![4.0, 2.0, 5.0]; + both_sides.negative_spans = vec![span(0, 2)]; + both_sides.negative_buckets = vec![3.0, 3.0]; + + // Its zero bucket holds observations of its own, so the layout is not empty even though + // no span is populated. + let zero_bucket_only = empty(1, 1.0, 4.0, 2.0, 4.0); + let empty_histogram = empty(0, 0.0, 0.0, 0.0, 0.0); + + vec![ + ("custom", custom), + ("spaced", spaced), + ("nan_sum", nan_sum), + ("nan_sum_multi_bucket", nan_sum_multi_bucket), + ("both_sides", both_sides), + ("zero_bucket_only", zero_bucket_only), + ("empty", empty_histogram), + ] + } + + fn empty( + schema: i32, + zero_threshold: f64, + count: f64, + sum: f64, + zero_count: f64, + ) -> NativeHistogram { + NativeHistogram { + schema, + zero_threshold, + sum, + reset_hint: CounterResetHint::Unknown, + start_timestamp: None, + custom_values: Vec::new(), + positive_spans: Vec::new(), + negative_spans: Vec::new(), + count, + zero_count, + positive_buckets: Vec::new(), + negative_buckets: Vec::new(), + } + } + + fn span(offset: i32, length: i32) -> Span { + Span { offset, length } + } + + fn columns(spans: &[Span]) -> (Vec, Vec) { + spans.iter().map(|span| (span.offset, span.length)).unzip() + } + + /// The view of `histogram`, written out here rather than through [`super::LegacyView`] so that + /// a conversion mistake shows up as a failed comparison instead of cancelling out. + fn view<'a>( + histogram: &'a NativeHistogram, + positive: &'a (Vec, Vec), + negative: &'a (Vec, Vec), + ) -> HistogramView<'a> { + HistogramView { + schema: histogram.schema, + zero_threshold: histogram.zero_threshold, + sum: histogram.sum, + count: histogram.count, + zero_count: histogram.zero_count, + reset_hint: histogram.reset_hint, + start_timestamp: histogram.start_timestamp, + custom_values: &histogram.custom_values, + positive: BucketSideView { + span_offsets: &positive.0, + span_lengths: &positive.1, + buckets: &histogram.positive_buckets, + }, + negative: BucketSideView { + span_offsets: &negative.0, + span_lengths: &negative.1, + buckets: &histogram.negative_buckets, + }, + } + } + + /// The legacy UDFs read their quantile out of the kernel now, so the two must agree to the + /// last bit for every kind of histogram the legacy representation can hold. + #[test] + fn quantile_with_info_is_the_native_quantile() { + for (name, histogram) in fixtures() { + let positive = columns(&histogram.positive_spans); + let negative = columns(&histogram.negative_spans); + for q in [ + f64::NEG_INFINITY, + -0.1, + 0.0, + 0.001, + 0.25, + 0.5, + 0.75, + 1.0, + 1.1, + f64::INFINITY, + f64::NAN, + ] { + let (value, _) = quantile_with_info(&histogram, q); + let expected = + native::quantile(q, &view(&histogram, &positive, &negative), &mut Vec::new()) + .unwrap(); + assert_eq!( + value.to_bits(), + expected.to_bits(), + "{name} q {q}: {value} vs {expected}" + ); + } + } + } + + /// Prometheus's NaN branch walks the remaining buckets and leaves the last one for the + /// interpolation, so a multi-bucket `sum = NaN` histogram answers with the top bucket rather + /// than the bucket the rank fell into. Pinning the number here, rather than only comparing + /// against the kernel, keeps a future kernel change from silently re-deciding it. + #[test] + fn quantile_with_nan_sum_uses_the_last_bucket() { + let mut histogram = empty(0, 0.0, 10.0, f64::NAN, 0.0); + histogram.positive_spans = vec![span(0, 2)]; + histogram.positive_buckets = vec![8.0, 1.0]; + + // The nine observations the buckets hold are fewer than the count of ten and the sum is + // NaN, so the note reports the skew: the rank still falls inside what the buckets carry. + let (value, info) = quantile_with_info(&histogram, 0.5); + assert_eq!( + value.to_bits(), + 32.0f64.to_bits(), + "rank 5 lands in (0.5, 1] (0.7711), but the NaN walk leaves (1, 2] behind and \ + fraction 5 / 1 puts the answer at 2^5" + ); + assert_eq!( + info, + Some(NativeHistogramQuantileInfo::NaNSkew), + "a rank inside the bucket total is still an estimate" + ); + } + + /// The other half of the same note: a rank past the total the buckets carry is no estimate at + /// all, because the observations the buckets cannot hold were the highest ones. + #[test] + fn quantile_with_nan_sum_below_the_rank_is_nan() { + let mut histogram = empty(0, 0.0, 10.0, f64::NAN, 0.0); + histogram.positive_spans = vec![span(0, 2)]; + histogram.positive_buckets = vec![8.0, 1.0]; + + // The rank 0.95 * 10 = 9.5 lies past the 9 observations the buckets hold, so the forward + // walk never reaches it and the estimate is NaN rather than the last bucket's bound. + let (value, info) = quantile_with_info(&histogram, 0.95); + assert!( + value.is_nan(), + "a rank the buckets cannot reach has no estimate, got {value}" + ); + assert_eq!( + info, + Some(NativeHistogramQuantileInfo::NaNResult), + "the note says the NaN observations were the highest ones" + ); + + // The single-bucket fixture the earlier note test uses reaches the same branch: the rank + // 0.9 * 10 = 9 lies past the 8 observations the one bucket holds. + let mut single = empty(0, 0.0, 10.0, f64::NAN, 0.0); + single.positive_spans = vec![span(0, 1)]; + single.positive_buckets = vec![8.0]; + assert!(quantile_with_info(&single, 0.9).0.is_nan()); + assert_eq!( + quantile_with_info(&single, 0.9).1, + Some(NativeHistogramQuantileInfo::NaNResult) + ); + } + + /// A tie between two buckets that do not touch resolves differently in the two walks, and that + /// difference is why the kernel replaced the estimator: the legacy walk goes up from the lowest + /// bucket and stops at the first one the rank fits in, while the kernel walks a finite-sum + /// histogram at or above the median down from the highest. Both numbers are pinned as literals, + /// the legacy one computed through the estimator still in `common/query`, so that a later + /// change to either walk shows up as an arithmetic difference instead of a quiet one. + #[test] + fn exact_tie_answers_one_from_the_legacy_walk_and_two_from_the_kernel() { + let mut tie = empty(0, 0.0, 2.0, 3.75, 0.0); + // Index 0 and index 2 hold one observation each, and index 1 is empty, so the two buckets + // do not touch and nothing interpolates across the gap. + tie.positive_spans = vec![span(0, 1), span(1, 1)]; + tie.positive_buckets = vec![1.0, 1.0]; + + // `NativeHistogram::quantile_with_info` is the estimator the legacy UDF used before the + // kernel replaced it and is still in the workspace: rank 0.5 * 2 = 1 fills the bucket at + // index 0 exactly, whose fraction is 1, so the answer is that bucket's upper bound. + assert_eq!( + tie.quantile_with_info(0.5), + (1.0, None), + "the legacy walk answers with the upper bound of (0.5, 1]" + ); + + // The kernel's backwards walk meets the bucket at index 2 first, and the rank inside it is + // 0, so the answer is the lower bound of (2, 4]. + let (value, info) = quantile_with_info(&tie, 0.5); + assert_eq!( + value.to_bits(), + 2.0f64.to_bits(), + "the kernel's walk answers with the lower bound of (2, 4]" + ); + assert_eq!( + info, None, + "a tie between two buckets is not a NaN observation" + ); + } + + /// The same agreement for `histogram_fraction`, whose legacy wrapper also returns a note. + #[test] + fn fraction_with_info_is_the_native_fraction() { + for (name, histogram) in fixtures() { + let positive = columns(&histogram.positive_spans); + let negative = columns(&histogram.negative_spans); + for (lower, upper) in [ + (f64::NEG_INFINITY, f64::INFINITY), + (-2.0, 0.5), + (0.0, 1.0), + (1.0, 4.0), + (2.0, 2.0), + (3.0, 1.0), + (f64::NAN, 1.0), + (0.0, f64::NAN), + ] { + let (value, _) = fraction_with_info(&histogram, lower, upper); + let expected = native::fraction( + lower, + upper, + &view(&histogram, &positive, &negative), + &mut Vec::new(), + ) + .unwrap(); + assert_eq!( + value.to_bits(), + expected.to_bits(), + "{name} [{lower}, {upper}]: {value} vs {expected}" + ); + } + } + } + + /// Pairs the legacy arithmetic has to reconcile: the same layout, a resolution difference, a + /// zero bucket one side has to grow into the other, mismatched custom bounds, and NaN + /// observations. + fn pairs() -> Vec<(&'static str, NativeHistogram, NativeHistogram)> { + let mut same_left = empty(2, 0.0, 6.0, 6.0, 1.0); + same_left.positive_spans = vec![span(0, 2)]; + same_left.positive_buckets = vec![2.0, 3.0]; + same_left.negative_spans = vec![span(0, 1)]; + same_left.negative_buckets = vec![1.0]; + let mut same_right = empty(2, 0.0, 5.0, 8.0, 0.0); + same_right.positive_spans = vec![span(-1, 3)]; + same_right.positive_buckets = vec![1.0, 2.0, 2.0]; + same_right.negative_spans = vec![span(1, 1)]; + same_right.negative_buckets = vec![2.0]; + + let mut fine = empty(3, 0.0, 2.0, 2.0, 0.0); + fine.positive_spans = vec![span(0, 2)]; + fine.positive_buckets = vec![1.0, 1.0]; + let mut coarse = empty(0, 0.0, 4.0, 5.0, 0.0); + coarse.positive_spans = vec![span(0, 1)]; + coarse.positive_buckets = vec![4.0]; + + let mut narrow_zero = empty(0, 0.0, 3.0, 3.0, 0.0); + narrow_zero.positive_spans = vec![span(0, 1)]; + narrow_zero.positive_buckets = vec![3.0]; + let mut wide_zero = empty(0, 2.0, 4.0, 5.0, 1.0); + wide_zero.positive_spans = vec![span(1, 1)]; + wide_zero.positive_buckets = vec![3.0]; + + let mut custom_left = empty(CUSTOM_BUCKETS_SCHEMA, 0.0, 6.0, 12.0, 0.0); + custom_left.custom_values = vec![1.0, 2.0, 4.0]; + custom_left.positive_spans = vec![span(0, 3)]; + custom_left.positive_buckets = vec![1.0, 3.0, 2.0]; + let mut custom_right = empty(CUSTOM_BUCKETS_SCHEMA, 0.0, 6.0, 14.0, 0.0); + custom_right.custom_values = vec![2.0, 3.0, 4.0]; + custom_right.positive_spans = vec![span(0, 3)]; + custom_right.positive_buckets = vec![4.0, 1.0, 1.0]; + + let mut nan_left = empty(1, 0.0, 10.0, f64::NAN, 0.0); + nan_left.positive_spans = vec![span(0, 2)]; + nan_left.positive_buckets = vec![3.0, 5.0]; + let mut nan_right = empty(1, 0.0, 2.0, 2.0, 0.0); + nan_right.positive_spans = vec![span(0, 1)]; + nan_right.positive_buckets = vec![2.0]; + + // Every operand carries a start timestamp of its own, because the arithmetic is expected to + // clear it: a sum differs from both samples it was derived from, so it names no start. + same_left.start_timestamp = Some(1_000); + same_right.start_timestamp = Some(2_000); + fine.start_timestamp = Some(3_001); + coarse.start_timestamp = Some(3_002); + narrow_zero.start_timestamp = Some(3_003); + wide_zero.start_timestamp = Some(3_004); + custom_left.start_timestamp = Some(3_005); + custom_right.start_timestamp = Some(3_006); + nan_left.start_timestamp = Some(3_007); + nan_right.start_timestamp = Some(3_008); + + vec![ + ("same_layout", same_left, same_right), + ("schema_reduction", fine, coarse), + ("zero_threshold", narrow_zero, wide_zero), + ("custom_bounds", custom_left, custom_right), + ("nan_sum", nan_left, nan_right), + ] + } + + /// The buckets a side holds that carry observations, by index and bit pattern. + fn populated_buckets(spans: &[Span], buckets: &[f64]) -> Vec<(i32, u64)> { + let (offsets, lengths) = columns(spans); + let mut index = 0; + let mut out = Vec::new(); + let mut counts = buckets.iter(); + for (position, (offset, length)) in offsets.into_iter().zip(lengths).enumerate() { + index = if position == 0 { + offset + } else { + index + offset + }; + for _ in 0..length { + let count = *counts.next().unwrap(); + if count != 0.0 { + out.push((index, count.to_bits())); + } + index += 1; + } + } + out + } + + fn populated(side: &[(i32, f64)]) -> Vec<(i32, u64)> { + side.iter() + .filter(|(_, count)| *count != 0.0) + .map(|(index, count)| (*index, count.to_bits())) + .collect() + } + + /// Bucket counts by their exact bit patterns, so a comparison also holds for a NaN or a signed + /// zero a scaling left behind. + fn count_bits(counts: &[f64]) -> Vec { + counts.iter().map(|count| count.to_bits()).collect() + } + + fn side_count_bits(side: &[(i32, f64)]) -> Vec { + side.iter().map(|&(_, count)| count.to_bits()).collect() + } + + /// A span list as the `(offset, length)` pairs [`FloatHistogram::spans`] reports. + fn segments(spans: &[Span]) -> Vec<(i32, i32)> { + spans + .iter() + .map(|span| (span.offset, span.length)) + .collect() + } + + /// Every field of the legacy payload against the kernel's, span segmentation included: a + /// comparison of the populated buckets alone cannot tell one span of two buckets from two + /// spans of one bucket each, and says nothing about the metadata beside the counts. + /// + /// `expected_start_timestamp` states the policy of the operation that produced the payload. One + /// that derives a histogram from its input -- `add`, `sub`, `scale`, `divide_by` -- clears the + /// start timestamp, because the field names the start of the sample the payload was read from + /// and a derived value is not that sample; the kernel clears it in the same step, so both sides + /// must carry the value passed here. `scale` and `divide_by` keep a field-by-field fallback for + /// a layout the kernel cannot read, which derives nothing and copies the field, and the test + /// that exercises it asserts `Some(..)` where it belongs. `quantile_with_info` and + /// `fraction_with_info` return no payload and leave their input untouched, so they have no + /// start timestamp to compare here. + fn assert_same_payload( + name: &str, + legacy: &NativeHistogram, + native: &FloatHistogram, + expected_start_timestamp: Option, + ) { + assert_eq!(legacy.schema, native.schema, "{name} schema"); + assert_eq!( + legacy.zero_threshold.to_bits(), + native.zero_threshold.to_bits(), + "{name} zero_threshold" + ); + assert_eq!( + legacy.count.to_bits(), + native.count.to_bits(), + "{name} count" + ); + assert_eq!(legacy.sum.to_bits(), native.sum.to_bits(), "{name} sum"); + assert_eq!( + legacy.zero_count.to_bits(), + native.zero_count.to_bits(), + "{name} zero_count" + ); + assert_eq!(legacy.reset_hint, native.reset_hint, "{name} reset_hint"); + assert_eq!( + legacy.custom_values, native.custom_values, + "{name} custom_values" + ); + assert_eq!( + legacy.start_timestamp, expected_start_timestamp, + "{name} start_timestamp" + ); + assert_eq!( + native.start_timestamp, expected_start_timestamp, + "{name} kernel start_timestamp" + ); + + let [positive, negative] = native.spans(); + assert_eq!( + segments(&legacy.positive_spans), + positive, + "{name} positive spans" + ); + assert_eq!( + segments(&legacy.negative_spans), + negative, + "{name} negative spans" + ); + assert_eq!( + count_bits(&legacy.positive_buckets), + side_count_bits(&native.positive), + "{name} positive buckets" + ); + assert_eq!( + count_bits(&legacy.negative_buckets), + side_count_bits(&native.negative), + "{name} negative buckets" + ); + assert_eq!( + populated_buckets(&legacy.positive_spans, &legacy.positive_buckets), + populated(&native.positive), + "{name} positive bucket indices" + ); + assert_eq!( + populated_buckets(&legacy.negative_spans, &legacy.negative_buckets), + populated(&native.negative), + "{name} negative bucket indices" + ); + } + + /// The added histogram is the kernel's addition, bucket for bucket and bit for bit. + #[test] + fn add_is_the_native_add() { + for (name, left, right) in pairs() { + let combined = add(&left, &right).unwrap(); + let mut native = float_histogram(&left).unwrap(); + native.add(&float_histogram(&right).unwrap()).unwrap(); + // The bridge compacts a sum, dropping the buckets the two sides left empty, so the + // kernel's own addition needs the same step before the two payloads can be compared + // bucket for bucket. + native.compact(); + assert_same_payload(name, &combined, &native, None); + } + } + + /// The same for subtraction, which the kernel reports as an addition of the negation. + #[test] + fn sub_is_the_native_sub() { + for (name, left, right) in pairs() { + let combined = sub(&left, &right).unwrap(); + assert_eq!(combined.reset_hint, CounterResetHint::Gauge, "{name}"); + let mut native = float_histogram(&left).unwrap(); + native.sub(&float_histogram(&right).unwrap()).unwrap(); + native.reset_hint = CounterResetHint::Gauge; + native.compact(); + assert_same_payload(name, &combined, &native, None); + } + } + + /// Scaling and dividing move every count and leave the layout alone, as the kernel's own + /// multiplication and division do. + #[test] + fn scale_and_divide_by_are_the_native_mul_and_div() { + for (name, histogram, _) in pairs() { + for factor in [2.0, 0.5, -1.0, 0.0, f64::INFINITY] { + let scaled = scale(&histogram, factor); + let mut native = float_histogram(&histogram).unwrap(); + native.mul(factor); + assert_same_payload(name, &scaled, &native, None); + + let divided = divide_by(&histogram, factor); + let mut native = float_histogram(&histogram).unwrap(); + native.div(factor); + assert_same_payload(name, ÷d, &native, None); + } + } + } + + /// The note the legacy UDFs turn into an annotation follows the kernel's outcome instead of a + /// second reading of the histogram. + #[test] + fn nan_notes_follow_the_kernel_outcome() { + use NativeHistogramQuantileInfo::{NaNResult, NaNSkew}; + + let nan_sum = fixtures() + .into_iter() + .find(|(name, _)| *name == "nan_sum") + .map(|(_, histogram)| histogram) + .unwrap(); + assert_eq!(quantile_with_info(&nan_sum, 0.5).1, Some(NaNSkew)); + assert_eq!(quantile_with_info(&nan_sum, 0.9).1, Some(NaNResult)); + assert_eq!(quantile_with_info(&nan_sum, 0.0).1, Some(NaNSkew)); + assert_eq!(quantile_with_info(&nan_sum, 1.0).1, Some(NaNResult)); + assert_eq!(quantile_with_info(&nan_sum, -1.0).1, None); + assert_eq!(quantile_with_info(&nan_sum, 2.0).1, None); + assert_eq!(quantile_with_info(&nan_sum, f64::NAN).1, None); + + let mut complete = empty(0, 0.0, 8.0, 8.0, 0.0); + complete.positive_spans = vec![span(0, 1)]; + complete.positive_buckets = vec![8.0]; + assert_eq!(quantile_with_info(&complete, 0.5).1, None); + + assert!(fraction_with_info(&nan_sum, f64::NEG_INFINITY, f64::INFINITY).1); + assert!(!fraction_with_info(&complete, f64::NEG_INFINITY, f64::INFINITY).1); + assert!(!fraction_with_info(&nan_sum, f64::NAN, 1.0).1); + assert!(!fraction_with_info(&nan_sum, 1.0, 1.0).1); + assert!(!fraction_with_info(&nan_sum, 2.0, 1.0).1); + } + + /// The two conversions are inverse: the payload survives `NativeHistogram` to + /// [`FloatHistogram`] and back field for field, including the parts a comparison of the counts + /// alone would not see. + #[test] + fn round_trip_preserves_the_payload_and_its_span_layout() { + let mut exponential = empty(2, 0.5, 12.0, -7.5, 1.0); + exponential.reset_hint = CounterResetHint::NotCounterReset; + exponential.start_timestamp = Some(1_234_567); + // A zero-length span carries nothing but its offset, and the two gaps between the three + // populated segments are part of the layout the legacy representation reports: the counts + // live at indices 2 and 3 and then 5, with nothing at 4. + exponential.positive_spans = vec![span(0, 0), span(2, 2), span(1, 1)]; + exponential.positive_buckets = vec![1.0, 3.0, 2.0]; + exponential.negative_spans = vec![span(-2, 2)]; + exponential.negative_buckets = vec![2.5, 1.5]; + + let mut custom = empty(CUSTOM_BUCKETS_SCHEMA, 0.0, 6.0, 9.0, 0.0); + custom.reset_hint = CounterResetHint::Gauge; + custom.start_timestamp = Some(42); + custom.custom_values = vec![1.0, 2.0, 4.0, 8.0]; + custom.positive_spans = vec![span(0, 1), span(1, 2)]; + custom.positive_buckets = vec![1.0, 2.0, 3.0]; + + for (name, original) in [("exponential", exponential), ("custom", custom)] { + let round_tripped = legacy_histogram(&float_histogram(&original).unwrap()); + + assert_eq!( + round_tripped.reset_hint, original.reset_hint, + "{name} reset_hint" + ); + assert_eq!( + round_tripped.start_timestamp, original.start_timestamp, + "{name} start_timestamp" + ); + assert_eq!( + round_tripped.custom_values, original.custom_values, + "{name} custom_values" + ); + assert_eq!( + round_tripped.positive_spans, original.positive_spans, + "{name} positive spans, zero-length and gapped segments included" + ); + assert_eq!( + round_tripped.negative_spans, original.negative_spans, + "{name} negative spans" + ); + assert_eq!( + count_bits(&round_tripped.positive_buckets), + count_bits(&original.positive_buckets), + "{name} positive buckets" + ); + assert_eq!( + count_bits(&round_tripped.negative_buckets), + count_bits(&original.negative_buckets), + "{name} negative buckets" + ); + // Everything else the payload holds -- schema, zero threshold, count, sum and the zero + // count -- is compared in one place above. + assert_eq!( + round_tripped, original, + "{name}: the round trip changed the histogram" + ); + } + } + + /// A histogram an operation derived carries no start timestamp: the field names the start of + /// the sample the payload was read from, and a sum, a difference, a product or a quotient is + /// not that sample. + #[test] + fn the_arithmetic_clears_the_start_timestamp() { + let mut left = empty(0, 0.0, 2.0, 3.0, 0.0); + left.start_timestamp = Some(1_000); + left.positive_spans = vec![span(0, 1)]; + left.positive_buckets = vec![2.0]; + let mut right = empty(0, 0.0, 1.0, 1.0, 0.0); + right.start_timestamp = Some(2_000); + right.positive_spans = vec![span(0, 1)]; + right.positive_buckets = vec![1.0]; + + for (name, derived) in [ + ("add", add(&left, &right).unwrap()), + ("sub", sub(&left, &right).unwrap()), + ("scale", scale(&left, 2.0)), + ("divide_by", divide_by(&left, 2.0)), + ] { + assert_eq!( + derived.start_timestamp, None, + "{name}: a derived histogram names no start" + ); + } + // Reading the operands is not deriving from them. + assert_eq!(left.start_timestamp, Some(1_000)); + assert_eq!(right.start_timestamp, Some(2_000)); + } + + /// The estimators read the buckets rather than the sample's start timestamp, and neither of + /// them hands back a payload, so the field neither changes the answer nor changes itself. + #[test] + fn the_estimators_leave_the_start_timestamp_alone() { + let mut timed = empty(2, 0.5, 20.0, -3.0, 3.0); + timed.start_timestamp = Some(1_700_000_000_000); + timed.positive_spans = vec![span(0, 3)]; + timed.positive_buckets = vec![4.0, 2.0, 5.0]; + timed.negative_spans = vec![span(0, 2)]; + timed.negative_buckets = vec![3.0, 3.0]; + let mut untimed = timed.clone(); + untimed.start_timestamp = None; + + for q in [0.0, 0.25, 0.5, 0.75, 1.0] { + assert_eq!( + quantile_with_info(&timed, q).0.to_bits(), + quantile_with_info(&untimed, q).0.to_bits(), + "q {q}: the start timestamp takes no part in the estimate" + ); + } + for (lower, upper) in [(-1.0, 2.0), (0.0, 1.0)] { + assert_eq!( + fraction_with_info(&timed, lower, upper).0.to_bits(), + fraction_with_info(&untimed, lower, upper).0.to_bits(), + "[{lower}, {upper}]: the start timestamp takes no part in the estimate" + ); + } + assert_eq!( + timed.start_timestamp, + Some(1_700_000_000_000), + "estimating from a histogram must not rewrite it" + ); + } + + /// The arithmetic reconciles what the two operands disagree about, and reports it in the + /// payload: the reset hint combination and the custom bounds. + #[test] + fn add_and_sub_reconcile_the_reset_hint_and_the_custom_bounds() { + // A reset and a confirmation contradict each other, so a sum of the two cannot claim + // either: the kernel answers with the hint that must be inspected. + let mut reset = empty(0, 0.0, 2.0, 2.0, 0.0); + reset.reset_hint = CounterResetHint::CounterReset; + reset.positive_spans = vec![span(0, 1)]; + reset.positive_buckets = vec![2.0]; + let mut confirmed = empty(0, 0.0, 1.0, 1.0, 0.0); + confirmed.reset_hint = CounterResetHint::NotCounterReset; + confirmed.positive_spans = vec![span(0, 1)]; + confirmed.positive_buckets = vec![1.0]; + + let sum = add(&reset, &confirmed).unwrap(); + assert_eq!( + sum.reset_hint, + CounterResetHint::Unknown, + "a contradiction the payload has to be inspected for" + ); + assert_eq!(sum.count.to_bits(), 3.0f64.to_bits()); + assert_eq!(sum.sum.to_bits(), 3.0f64.to_bits()); + assert_eq!(sum.positive_buckets, vec![3.0]); + assert_eq!( + add(&confirmed, &reset).unwrap().reset_hint, + CounterResetHint::Unknown, + "the same contradiction in the other order" + ); + assert_eq!( + add(&confirmed, &confirmed).unwrap().reset_hint, + CounterResetHint::NotCounterReset, + "two counters that agree keep their agreement" + ); + assert_eq!( + sub(&reset, &confirmed).unwrap().reset_hint, + CounterResetHint::Gauge, + "subtraction is a gauge operation whatever the operands said" + ); + + // Custom bounds that disagree leave the result with the bounds both sides carry. + let mut left = empty(CUSTOM_BUCKETS_SCHEMA, 0.0, 6.0, 12.0, 0.0); + left.custom_values = vec![1.0, 2.0, 4.0]; + left.positive_spans = vec![span(0, 3)]; + left.positive_buckets = vec![1.0, 3.0, 2.0]; + let mut right = empty(CUSTOM_BUCKETS_SCHEMA, 0.0, 6.0, 14.0, 0.0); + right.custom_values = vec![2.0, 3.0, 4.0]; + right.positive_spans = vec![span(0, 3)]; + right.positive_buckets = vec![4.0, 1.0, 1.0]; + + let combined = add(&left, &right).unwrap(); + assert_eq!( + combined.custom_values, + vec![2.0, 4.0], + "the intersection of (1, 2, 4) and (2, 3, 4)" + ); + assert_eq!(combined.count.to_bits(), 12.0f64.to_bits()); + assert_eq!(combined.sum.to_bits(), 26.0f64.to_bits()); + // Each side's buckets land in the interval of the merged bounds they fall in: `(-inf, 2]` + // takes 1 + 3 from the left and 4 from the right, and `(2, 4]` takes 2 from the left and + // 1 + 1 from the right. The empty `(4, inf)` bucket is dropped before it reaches a span. + assert_eq!(combined.positive_buckets, vec![8.0, 4.0]); + assert_eq!(combined.positive_spans, vec![span(0, 2)]); + } + + /// A bucket the two sides cancel out of leaves no span behind, and `promql_eq` reads the + /// buckets the spans expand to rather than the span list they are written with. + #[test] + fn sub_compacts_the_buckets_it_cancels_and_promql_eq_expands_the_spans() { + let mut left = empty(2, 0.5, 4.0, 6.0, 0.0); + left.positive_spans = vec![span(0, 2)]; + left.positive_buckets = vec![2.0, 1.5]; + left.negative_spans = vec![span(0, 1)]; + left.negative_buckets = vec![0.5]; + + let difference = sub(&left, &left).unwrap(); + assert_eq!(difference.count.to_bits(), 0.0f64.to_bits()); + assert_eq!(difference.sum.to_bits(), 0.0f64.to_bits()); + assert_eq!(difference.zero_count.to_bits(), 0.0f64.to_bits()); + assert!( + difference.positive_spans.is_empty(), + "a cancelled bucket leaves no span behind, got {:?}", + difference.positive_spans + ); + assert!(difference.positive_buckets.is_empty()); + assert!(difference.negative_spans.is_empty()); + assert!(difference.negative_buckets.is_empty()); + // The same histogram as no histogram at all. + assert!( + difference.promql_eq(&empty(2, 0.5, 0.0, 0.0, 0.0)), + "the cancelling subtraction is the empty histogram" + ); + + // Two spans of one bucket each describe the same buckets as one span of two: the first + // span's offset is the bucket index, and each later offset is the gap after the previous + // span, so `(0, 1), (0, 1)` puts the second bucket at index 1 while `(0, 1), (1, 1)` + // leaves index 1 empty and puts it at index 2. + let mut one_span = empty(0, 0.0, 3.0, 3.0, 0.0); + one_span.positive_spans = vec![span(0, 2)]; + one_span.positive_buckets = vec![1.0, 2.0]; + let mut two_spans = empty(0, 0.0, 3.0, 3.0, 0.0); + two_spans.positive_spans = vec![span(0, 1), span(0, 1)]; + two_spans.positive_buckets = vec![1.0, 2.0]; + assert!( + one_span.promql_eq(&two_spans), + "the same indices and counts under a different segmentation" + ); + + let mut gapped = empty(0, 0.0, 3.0, 3.0, 0.0); + gapped.positive_spans = vec![span(0, 1), span(1, 1)]; + gapped.positive_buckets = vec![1.0, 2.0]; + assert!( + !one_span.promql_eq(&gapped), + "the same counts at indices 0 and 2 are not the same histogram" + ); + let mut other_counts = two_spans.clone(); + other_counts.positive_buckets = vec![2.0, 1.0]; + assert!( + !one_span.promql_eq(&other_counts), + "the same indices with other counts are not the same histogram" + ); + } + + /// Payloads the legacy caller could still produce and the kernel refuses to read: a span whose + /// length disagrees with the counts, a span list that steps backwards, an index that leaves + /// `i32` once expanded, and a negative span length. All four carry the same numbers, so the + /// field-by-field answers below are the same for each of them. + fn unreadable_layouts() -> Vec<(&'static str, NativeHistogram, Option)> { + // The span claims one bucket and the counts hold two. + let mut short_counts = empty(0, 0.0, 3.0, 5.0, 1.0); + short_counts.reset_hint = CounterResetHint::NotCounterReset; + short_counts.positive_spans = vec![span(0, 1)]; + short_counts.positive_buckets = vec![1.0, 2.0]; + let mut backwards = short_counts.clone(); + backwards.positive_spans = vec![span(0, 1), span(-1, 1)]; + let mut overflow = short_counts.clone(); + overflow.positive_spans = vec![span(i32::MAX, 2)]; + let mut negative_length = short_counts.clone(); + negative_length.positive_spans = vec![span(0, -1)]; + + vec![ + ("short_counts", short_counts, Some(4_242)), + ("backwards", backwards, Some(4_243)), + ("overflow", overflow, Some(4_244)), + ("negative_length", negative_length, Some(4_245)), + ] + .into_iter() + .map(|(name, mut histogram, start_timestamp)| { + histogram.start_timestamp = start_timestamp; + (name, histogram, start_timestamp) + }) + .collect() + } + + /// A layout the kernel cannot walk keeps the field-by-field scaling and division the legacy + /// caller had, so such a histogram is still multiplied instead of dropped, and keeps the start + /// timestamp it was stored with. + #[test] + fn scale_and_divide_fall_back_to_the_fields_for_an_unreadable_layout() { + for (name, histogram, start_timestamp) in unreadable_layouts() { + // A negative factor turns the histogram into a gauge; the untouched hint otherwise. + let negated = scale(&histogram, -0.5); + assert_eq!(negated.count, -1.5, "{name} count"); + assert_eq!(negated.sum, -2.5, "{name} sum"); + assert_eq!(negated.zero_count, -0.5, "{name} zero_count"); + assert_eq!( + negated.positive_buckets, + vec![-0.5, -1.0], + "{name} positive" + ); + assert_eq!(negated.reset_hint, CounterResetHint::Gauge, "{name} hint"); + assert_eq!( + negated.start_timestamp, start_timestamp, + "{name}: the field-by-field fallback copies the payload, so the start timestamp \ + survives where the kernel path clears it" + ); + assert_eq!( + negated.positive_spans, histogram.positive_spans, + "{name}: the fallback keeps the layout it cannot expand" + ); + + let doubled = scale(&histogram, 2.0); + assert_eq!(doubled.count, 6.0, "{name} count"); + assert_eq!(doubled.sum, 10.0, "{name} sum"); + assert_eq!(doubled.zero_count, 2.0, "{name} zero_count"); + assert_eq!(doubled.positive_buckets, vec![2.0, 4.0], "{name} positive"); + assert_eq!( + doubled.reset_hint, + CounterResetHint::NotCounterReset, + "{name}: a positive factor leaves a hint alone" + ); + assert_eq!(doubled.start_timestamp, start_timestamp, "{name}"); + + let quartered = divide_by(&histogram, 4.0); + assert_eq!(quartered.count, 0.75, "{name} count"); + assert_eq!(quartered.sum, 1.25, "{name} sum"); + assert_eq!(quartered.zero_count, 0.25, "{name} zero_count"); + assert_eq!( + quartered.positive_buckets, + vec![0.25, 0.5], + "{name} positive" + ); + assert_eq!( + quartered.reset_hint, + CounterResetHint::NotCounterReset, + "{name}: a positive divisor leaves a hint alone" + ); + assert_eq!(quartered.start_timestamp, start_timestamp, "{name}"); + + // A zero divisor empties the buckets on this path too. + let over_zero = divide_by(&histogram, 0.0); + assert_eq!(over_zero.count, f64::INFINITY, "{name} count"); + assert_eq!(over_zero.sum, f64::INFINITY, "{name} sum"); + assert_eq!(over_zero.zero_count, f64::INFINITY, "{name} zero_count"); + assert!(over_zero.positive_spans.is_empty(), "{name}"); + assert!(over_zero.positive_buckets.is_empty(), "{name}"); + assert_eq!(over_zero.start_timestamp, start_timestamp, "{name}"); + + // The addition and the subtraction refuse the same layout outright, as the legacy + // arithmetic did, rather than answering with a payload the kernel never built. + assert!( + add(&histogram, &histogram).is_none(), + "{name}: a layout the kernel cannot read has no sum" + ); + assert!( + sub(&histogram, &histogram).is_none(), + "{name}: a layout the kernel cannot read has no difference" + ); + } + } + + /// The factors that are not a plain finite number, on a layout the kernel can walk: a zero + /// divisor leaves no bucket, a NaN factor reaches every count, and a negative one turns the + /// histogram into a gauge. + #[test] + fn scale_and_divide_by_the_edge_factors() { + let mut histogram = empty(0, 0.0, 4.0, 6.0, 0.0); + histogram.reset_hint = CounterResetHint::NotCounterReset; + histogram.start_timestamp = Some(7); + histogram.positive_spans = vec![span(0, 2)]; + histogram.positive_buckets = vec![3.0, 1.0]; + histogram.negative_spans = vec![span(0, 1)]; + histogram.negative_buckets = vec![1.0]; + + let over_zero = divide_by(&histogram, 0.0); + assert_eq!(over_zero.count, f64::INFINITY, "a positive count over zero"); + assert_eq!(over_zero.sum, f64::INFINITY, "a positive sum over zero"); + assert!( + over_zero.zero_count.is_nan(), + "a zero count over zero is NaN" + ); + assert!(over_zero.positive_spans.is_empty()); + assert!(over_zero.positive_buckets.is_empty()); + assert!(over_zero.negative_spans.is_empty()); + assert!(over_zero.negative_buckets.is_empty()); + assert_eq!(over_zero.start_timestamp, None); + assert_eq!( + over_zero.reset_hint, + CounterResetHint::NotCounterReset, + "a zero divisor is not a negative one" + ); + + // A negative zero is still zero, so the buckets go the same way, and the quotients it + // leaves behind are the negative infinities. + let over_negative_zero = divide_by(&histogram, -0.0); + assert_eq!( + over_negative_zero.count, + f64::NEG_INFINITY, + "a positive count over negative zero" + ); + assert_eq!( + over_negative_zero.sum, + f64::NEG_INFINITY, + "a positive sum over negative zero" + ); + assert!(over_negative_zero.zero_count.is_nan()); + assert!(over_negative_zero.positive_spans.is_empty()); + assert!(over_negative_zero.positive_buckets.is_empty()); + assert_eq!(over_negative_zero.start_timestamp, None); + assert_eq!( + over_negative_zero.reset_hint, + CounterResetHint::NotCounterReset, + "negative zero is not a negative factor" + ); + + let over_nan = scale(&histogram, f64::NAN); + assert!(over_nan.count.is_nan() && over_nan.sum.is_nan()); + assert!(over_nan.positive_buckets.iter().all(|count| count.is_nan())); + assert!(over_nan.negative_buckets.iter().all(|count| count.is_nan())); + assert_eq!( + over_nan.positive_spans, + vec![span(0, 2)], + "a NaN factor moves the counts, not the layout" + ); + assert_eq!(over_nan.start_timestamp, None); + assert_eq!( + over_nan.reset_hint, + CounterResetHint::NotCounterReset, + "a NaN factor is not a negative one" + ); + + let negated = scale(&histogram, -2.0); + assert_eq!(negated.count, -8.0); + assert_eq!(negated.sum, -12.0); + assert_eq!(negated.positive_buckets, vec![-6.0, -2.0]); + assert_eq!(negated.negative_buckets, vec![-2.0]); + assert_eq!(negated.positive_spans, vec![span(0, 2)]); + assert_eq!(negated.reset_hint, CounterResetHint::Gauge); + assert_eq!(negated.start_timestamp, None); + + let negated_division = divide_by(&histogram, -2.0); + assert_eq!(negated_division.count, -2.0); + assert_eq!(negated_division.sum, -3.0); + assert_eq!(negated_division.positive_buckets, vec![-1.5, -0.5]); + assert_eq!(negated_division.negative_buckets, vec![-0.5]); + assert_eq!(negated_division.reset_hint, CounterResetHint::Gauge); + assert_eq!(negated_division.start_timestamp, None); + } +} diff --git a/tests-integration/tests/http.rs b/tests-integration/tests/http.rs index 8289ee1a47e..35a79f8ae84 100644 --- a/tests-integration/tests/http.rs +++ b/tests-integration/tests/http.rs @@ -5931,6 +5931,43 @@ pub async fn test_remote_write_v2_histogram_native_composition(store_type: Stora tests_integration::test_util::execute_sql(instance.fe_instance(), sql).await; } + // A counter histogram with a start timestamp strictly inside `(0, 3000]`, its window's only + // sample: `rate` can answer that window through the start timestamp alone. + let start_request = remote_write_v2::request_with_labels_and_histograms( + vec![ + (prom_store::METRIC_NAME_LABEL, "native_comp_start"), + ("job", "api"), + ], + vec![Histogram { + count: Some(Count::CountInt(8)), + sum: 10.0, + schema: 1, + positive_spans: vec![BucketSpan { + offset: 0, + length: 2, + }], + positive_deltas: vec![4, 0], + reset_hint: 2, + start_timestamp: 1_500, + timestamp: 3_000, + ..Default::default() + }], + ); + let payload = prom_store::snappy_compress(&start_request.encode_to_vec()).unwrap(); + let written = client + .post("/v1/prometheus/write") + .header("Content-Encoding", "snappy") + .header( + "Content-Type", + "application/x-protobuf;proto=io.prometheus.write.v2.Request", + ) + .body(payload) + .send() + .await; + let status = written.status(); + let body = written.text().await; + assert_eq!(status, StatusCode::NO_CONTENT, "write rejected: {body}"); + // The first sample has two equal buckets of 5; h2 has two equal buckets of 2. // Repeat the same public requests after flushing so the source can be memtable or SST. for phase in ["memtable", "flushed"] { @@ -5940,6 +5977,7 @@ pub async fn test_remote_write_v2_histogram_native_composition(store_type: Stora "native_comp_h2", "native_comp_dups", "native_comp_f", + "native_comp_start", ] { tests_integration::test_util::execute_sql( instance.fe_instance(), @@ -6217,6 +6255,56 @@ pub async fn test_remote_write_v2_histogram_native_composition(store_type: Stora } assert!(body.get("infos").is_none(), "{phase}: {query}: {body}"); assert!(body.get("warnings").is_none(), "{phase}: {query}: {body}"); + + // The same two windows asked without a hint, so the legacy route answers them and the + // observer proves it did. This is where the delegated kernel has to agree with the native + // route: the raw sample's start timestamp is what lets `rate` measure the window, while + // `* 1` gives that timestamp up, so the derived window has nothing to measure against. + for (query, expected_count) in [ + ("rate(native_comp_start[3s])", Some(8.0 / 3.0)), + ("rate((native_comp_start * 1)[3s:1s])", None), + ] { + let res = client + .get(&format!( + "/v1/prometheus/api/v1/query?query={}&time=3", + encode(query) + )) + .send() + .await; + let status = res.status(); + let body: Value = res.json().await; + assert_eq!(status, StatusCode::OK, "{phase}: {query}: {body}"); + let results = body["data"]["result"] + .as_array() + .unwrap_or_else(|| panic!("{phase}: {query}: no result in {body}")); + match expected_count { + Some(count) => { + assert_eq!(results.len(), 1, "{phase}: {query}: {body}"); + let reported: f64 = body["data"]["result"][0]["histogram"][1]["count"] + .as_str() + .unwrap_or_else(|| panic!("{phase}: {query}: no count in {body}")) + .parse() + .unwrap(); + assert!( + (reported - count).abs() < 1e-12, + "{phase}: {query}: expected count {count}, got {body}" + ); + } + None => assert!( + results.is_empty(), + "{phase}: {query}: `* 1` clears the start timestamp, so the derived window \ + has nothing to measure: {body}" + ), + } + assert!( + body.get("infos").is_none() && body.get("warnings").is_none(), + "{phase}: {query}: a counter histogram has nothing to report: {body}" + ); + assert!( + !executes_fused_series(&route.take_plan()), + "{phase}: {query} did not run on the legacy route" + ); + } } } @@ -6755,12 +6843,22 @@ pub async fn test_remote_write_v2_histogram_count_and_group_native_route(store_t pub async fn test_prometheus_remote_write_v2_native_histogram(store_type: StorageType) { common_telemetry::init_default_ut_logging(); - let (app, mut guard) = setup_test_prom_app_with_frontend( - store_type, + // The histogram answers at the end of this test are legacy ones, so the route observer is what + // proves the route they ran on: the engine-wide option stays off and no request carries a hint. + let route = Arc::new(PromRouteObserver::default()); + let plugins = Plugins::default(); + plugins.insert::>(route.clone()); + let mut instance = tests_integration::standalone::GreptimeDbStandaloneBuilder::new( "prometheus_remote_write_v2_native_histogram", ) + .with_default_store_type(store_type) + .with_plugin(plugins) + .build() .await; - let client = TestClient::new(app).await; + let server = build_test_prom_server(instance.fe_instance().clone(), false, None) + .with_greptime_config_options(instance.opts.datanode_options().to_toml().unwrap()) + .build(); + let client = TestClient::new(server.build(server.make_app()).unwrap()).await; let mut write_request = remote_write_v2::request_with_labels_and_samples( vec![ @@ -6914,6 +7012,123 @@ pub async fn test_prometheus_remote_write_v2_native_histogram(store_type: Storag ) .await; + // The raw sample carries a start timestamp of 1500, strictly inside the window `(0, 3000]` of + // the requests below, and it is the window's only sample. A legacy `rate`/`increase` can only + // answer such a window through that start timestamp: the whole sample is what the increase + // since the synthetic zero measures, and `rate` is that over the window's seconds. + for (query, count, sum) in [ + ( + "rate(remote_write_v2_latency_seconds[3s])", + 8.0 / 3.0, + 10.0 / 3.0, + ), + ("increase(remote_write_v2_latency_seconds[3s])", 8.0, 10.0), + ] { + let res = client + .get(&format!( + "/v1/prometheus/api/v1/query?query={}&time=3", + encode(query) + )) + .send() + .await; + let status = res.status(); + let body: Value = res.json().await; + assert_eq!(status, StatusCode::OK, "{query}: {body}"); + assert_eq!(body["data"]["resultType"], "vector", "{query}: {body}"); + assert_eq!( + body["data"]["result"].as_array().map(Vec::len), + Some(1), + "{query}: {body}" + ); + let histogram = &body["data"]["result"][0]["histogram"][1]; + let reported = |field: &str| -> f64 { + histogram[field] + .as_str() + .unwrap_or_else(|| panic!("no histogram {field} in {body}")) + .parse() + .unwrap() + }; + assert!( + (reported("count") - count).abs() < 1e-12 && (reported("sum") - sum).abs() < 1e-12, + "{query}: expected count {count} and sum {sum}, got {body}" + ); + assert!( + body.get("infos").is_none() && body.get("warnings").is_none(), + "{query}: a counter histogram with a start timestamp has nothing to report: {body}" + ); + assert!( + !executes_fused_series(&route.take_plan()), + "{query} did not run on the legacy route" + ); + } + + // A NaN observation: the buckets hold nine of the count's ten observations and the sum is NaN, + // which is how Prometheus marks the rest. Prometheus's NaN branch walks the buckets forward and + // leaves the top bucket for the interpolation, so the half quantile reads 2^5 rather than the + // 0.7711 the buckets' own rank gives - and the response has to say why. + let nan_request = remote_write_v2::request_with_labels_and_histograms( + vec![ + ( + prom_store::METRIC_NAME_LABEL, + "remote_write_v2_nan_quantile", + ), + ("job", "api"), + ], + vec![Histogram { + count: Some(Count::CountInt(10)), + sum: f64::NAN, + // A bucket's upper bound is 2^(index * 2^-schema), so schema 0 makes the two buckets + // (0.5, 1] and (1, 2]; the deltas hold 8 and then 1. + schema: 0, + positive_spans: vec![BucketSpan { + offset: 0, + length: 2, + }], + positive_deltas: vec![8, -7], + reset_hint: 2, + timestamp: 3_000, + ..Default::default() + }], + ); + let payload = prom_store::snappy_compress(&nan_request.encode_to_vec()).unwrap(); + let written = client + .post("/v1/prometheus/write") + .header("Content-Encoding", "snappy") + .header( + "Content-Type", + "application/x-protobuf;proto=io.prometheus.write.v2.Request", + ) + .body(payload) + .send() + .await; + let status = written.status(); + let body = written.text().await; + assert_eq!(status, StatusCode::NO_CONTENT, "write rejected: {body}"); + + let res = client + .get(&format!( + "/v1/prometheus/api/v1/query?query={}&time=3", + encode("histogram_quantile(0.5, remote_write_v2_nan_quantile)") + )) + .send() + .await; + assert_eq!(res.status(), StatusCode::OK); + let body: Value = res.json().await; + assert_eq!(body["data"]["resultType"], "vector", "{body}"); + assert_eq!( + body["data"]["result"][0]["value"][1], "32.0", + "the NaN walk leaves the top bucket: {body}" + ); + assert_eq!( + body["infos"], + json!(["input to histogram_quantile has NaN observations, result is skewed higher"]), + "{body}" + ); + assert!( + !executes_fused_series(&route.take_plan()), + "`histogram_quantile` did not run on the legacy route" + ); + for flushed in [false, true] { if flushed { flush_table(&client, "remote_write_v2_latency_seconds").await; @@ -7209,7 +7424,7 @@ pub async fn test_prometheus_remote_write_v2_native_histogram(store_type: Storag ) .await; - guard.remove_all().await; + instance.guard.remove_all().await; } #[apply(both_deployment_cases)]