From 8e0125f42719a5fd24a3cfa532565f2acf5d8af2 Mon Sep 17 00:00:00 2001 From: zzylol <50204836+zzylol@users.noreply.github.com> Date: Mon, 16 Nov 2026 04:33:29 +0000 Subject: [PATCH 1/3] feat(types, cost, planner): warn about each data fact a plan assumed because the workload does not declare it A plan now names every undeclared data fact it rests on, with the default used and whether the accuracy target depends on it: - a DDSketch state over a column without column_magnitudes is costed for the assumed [1, 1e9] (cost only: the DDSketch store grows without collapsing, so its alpha holds for any range); - an ingestion-time rate, increase or irate state over PromQL samples without a declared max_out_of_order_ms takes them to arrive in order (the plan may miss its accuracy target if they do not). The cost model records the first on NodeCost, Stage 2 reports the second next to the rule that relies on it, and the planner facade gathers both into SelectedPlanReport::assumed_data_facts; asap_planner prints each as a warning. --- crates/cost/src/node/state_bytes/mod.rs | 54 ++++-- crates/cost/src/node/usage/mod.rs | 45 ++++- crates/cost/src/node/usage/tests.rs | 146 +++++++++++++- crates/cost/src/plan/cost.rs | 21 +- crates/devtools/src/bin/asap_planner.rs | 43 ++-- crates/devtools/tests/asap_planner.rs | 137 +++++++++++++ crates/planner/src/installable/mod.rs | 31 ++- crates/planner/src/lib.rs | 6 +- crates/planner/tests/runtime_install.rs | 82 ++++++++ .../src/candidate.rs | 89 +++++++-- .../stage2-physical-optimization/src/lib.rs | 1 + .../types/src/workload/assumed_data_fact.rs | 183 ++++++++++++++++++ crates/types/src/workload/data.rs | 16 ++ crates/types/src/workload/mod.rs | 6 +- 14 files changed, 797 insertions(+), 63 deletions(-) create mode 100644 crates/types/src/workload/assumed_data_fact.rs diff --git a/crates/cost/src/node/state_bytes/mod.rs b/crates/cost/src/node/state_bytes/mod.rs index 54f15b94f..b07215318 100644 --- a/crates/cost/src/node/state_bytes/mod.rs +++ b/crates/cost/src/node/state_bytes/mod.rs @@ -226,7 +226,15 @@ pub fn sketch_state_bytes(params: &SketchParams, input_rows: StateInputRows) -> SketchParams::DDSketch { alpha } if !(*alpha > 0.0 && *alpha < 1.0) => { std::mem::size_of::() as u64 } - SketchParams::DDSketch { alpha } => ddsketch_state_bytes(*alpha, input_rows), + // Over the declared magnitude range, or the one assumed when none + // is declared (`assumed_magnitude_range`). + SketchParams::DDSketch { alpha } => ddsketch_state_bytes( + *alpha, + input_rows, + input_rows + .value_magnitude_range + .or_else(|| assumed_magnitude_range(params, input_rows)), + ), SketchParams::Hll { precision, .. } => { HyperLogLog::::estimated_memory_bytes(usize::from(*precision)) as u64 } @@ -314,6 +322,27 @@ const ASSUMED_HEAP_KEY_BYTES: usize = 3 * (1 + 4 + 16); /// A sample value's key owns no bytes, so this bounds it too. const ASSUMED_VALUE_KEY_BYTES: usize = 1 + 16; +/// The magnitude range a DDSketch state of `params` over `input_rows` is +/// costed for when its values declare none, the one place that default is +/// applied: [`DDSKETCH_ASSUMED_MAGNITUDE_RANGE`] for a DDSketch with α in +/// (0, 1) whose values declare no range; `None` for a declared range, an α +/// costed as an empty sketch, or any other sketch, whose bytes assume +/// none. E.g. a DDSketch at α = 0.01 over a `value` without +/// `column_magnitudes` gives `Some([1, 1e9])`. +pub fn assumed_magnitude_range( + params: &SketchParams, + input_rows: StateInputRows, +) -> Option { + match params { + SketchParams::DDSketch { alpha } + if *alpha > 0.0 && *alpha < 1.0 && input_rows.value_magnitude_range.is_none() => + { + Some(DDSKETCH_ASSUMED_MAGNITUDE_RANGE) + } + _ => None, + } +} + /// The range of value magnitudes a DDSketch is assumed to see at most when /// its column declares no `column_magnitudes`: nine decades, e.g. /// latencies from 1 ns to 1 s, costed as magnitudes in `[1, 1e9]` (its @@ -354,11 +383,11 @@ fn exponential_values_magnitude_ratio(rows: u64) -> f64 { /// counter per bucket its values span beyond the first. /// /// The span is that of the values the state folds, not of the column: the -/// smallest of the magnitude ratio its rows are assumed to span -/// ([`exponential_values_magnitude_ratio`]), the ratio of its column's -/// declared `column_magnitudes` (`input_rows.value_magnitude_range`) and -/// that of `DDSKETCH_ASSUMED_MAGNITUDE_RANGE`; without known rows, the -/// smaller of the last two. The library's worst case over every order of +/// smaller of the magnitude ratio its rows are assumed to span +/// ([`exponential_values_magnitude_ratio`]) and the ratio of +/// `column_range`, its column's declared `column_magnitudes`, or the range +/// [`assumed_magnitude_range`] assumes when none is declared; without known +/// rows, the ratio of `column_range`. The library's worst case over every order of /// inserts and merges (`estimated_memory_bytes`) is about twice the span /// over the whole range, which is not what a state holds on average. /// @@ -368,7 +397,11 @@ fn exponential_values_magnitude_ratio(rows: u64) -> f64 { /// against 5,769 held. The library's bound for either is 18,752. A gauge /// declared within [90, 110] spans a ratio of 1.22, 11 buckets: 1,248 /// bytes for any number of rows. -fn ddsketch_state_bytes(alpha: f64, input_rows: StateInputRows) -> u64 { +fn ddsketch_state_bytes( + alpha: f64, + input_rows: StateInputRows, + column_range: Option, +) -> u64 { use asap_sketchlib::DdSketch; let struct_bytes = std::mem::size_of::() as u64; // One value allocates one store's first block. @@ -393,12 +426,9 @@ fn ddsketch_state_bytes(alpha: f64, input_rows: StateInputRows) -> u64 { let rows_per_store = input_rows .rows_per_state .map(|rows| rows.div_ceil(stores).max(1)); - // The most the column's values span: its declared range, at most the + // The most the column's values span: its declared range, else the // assumed one. - let column_ratio = input_rows - .value_magnitude_range - .map_or(f64::INFINITY, |range| range.magnitude_ratio()) - .min(DDSKETCH_ASSUMED_MAGNITUDE_RANGE.magnitude_ratio()); + let column_ratio = column_range.map_or(f64::INFINITY, |range| range.magnitude_ratio()); let span = buckets_spanned(rows_per_store.map_or(column_ratio, |rows| { exponential_values_magnitude_ratio(rows).min(column_ratio) })); diff --git a/crates/cost/src/node/usage/mod.rs b/crates/cost/src/node/usage/mod.rs index 4b803f379..3faa76dcb 100644 --- a/crates/cost/src/node/usage/mod.rs +++ b/crates/cost/src/node/usage/mod.rs @@ -34,8 +34,8 @@ use crate::node::operator_statistics::{ EdgeStatistics, OperatorStatistics, PartitionStatistics, UnaryEdgeStatistics, }; use crate::node::state_bytes::{ - keeps_every_value, row_bytes, sketch_state_bytes, state_bytes_per_row, - state_row_bytes_beside_state, summary_state_bytes, StateInputRows, + assumed_magnitude_range, keeps_every_value, row_bytes, sketch_state_bytes, + state_bytes_per_row, state_row_bytes_beside_state, summary_state_bytes, StateInputRows, }; use crate::{aggregate_lookup, lookup, StateFamily}; use crate::{ @@ -56,7 +56,7 @@ use asap_types::workload::bounds::{ declared_non_negative, declared_series, declared_value_magnitude_range, group_count_bound, source_name, source_rows_per_ms, unchanged_source_columns, }; -use asap_types::workload::{DataWorkload, ONE_SECOND_MS}; +use asap_types::workload::{AssumedDataFact, DataFactAssumption, DataWorkload, ONE_SECOND_MS}; /// One node's cost per second of wall time, with how it was measured. A /// node is one operator node of the candidate's physical plan DAG @@ -90,6 +90,9 @@ pub struct NodeCost { /// Whether its CPU operations were costed from the measured table or /// from the formulas. pub cost_source: NodeCostSource, + /// The data facts the data workload does not declare that its cost + /// assumed, each once, e.g. a DDSketch's value magnitude range. + pub assumed_data_facts: Vec, } /// The state family of `node` whose first producer has `producer_family`: @@ -554,6 +557,8 @@ pub fn node_resource_usage_and_cost<'a>( .and_then(|p| p.memory_bytes_per_state) .map(|bytes| bytes.round() as u64); let mut cost_source = NodeCostSource::Analytical; + // The undeclared data facts its cost assumed. + let mut assumed_data_facts = Vec::new(); let input = inputs .first() .copied() @@ -633,6 +638,37 @@ pub fn node_resource_usage_and_cost<'a>( state_bytes_per_row(producer.output, producer.output_schema) }) }; + // The magnitude range a summary built here over `input_rows` is costed + // for when its values declare none (`assumed_magnitude_range`), named + // with the sources that declare no range for the column it folds (every + // source when it folds computed values). None when the measured table + // gives its bytes, which assume no range. + let assumed_magnitude_range_fact = |update: &SummaryUpdate, input_rows: StateInputRows| { + if measured_state_bytes.is_some() { + return None; + } + let assumed_range = assumed_magnitude_range(node.parameters.as_ref()?, input_rows)?; + let column = producers + .first() + .and_then(|producer| producer.unchanged_column(&update.weight)); + let undeclared = sources + .iter() + .copied() + .filter(|&source| { + column.is_none_or(|column| { + declared_value_magnitude_range(data, [source], column).is_none() + }) + }) + .map(|source| source.to_string()) + .collect(); + Some(AssumedDataFact { + sources: undeclared, + assumption: DataFactAssumption::DDSketchValueMagnitudeRange { + column: column.map(str::to_string), + assumed_range, + }, + }) + }; let unary = |output| UnaryEdgeStatistics { input, output, @@ -1053,6 +1089,7 @@ pub fn node_resource_usage_and_cost<'a>( node.parameters.as_ref(), input_rows, )?); + assumed_data_facts.extend(assumed_magnitude_range_fact(update, input_rows)); let update_ops = update_operations_per_row( family, node.parameters.as_ref(), @@ -1122,6 +1159,7 @@ pub fn node_resource_usage_and_cost<'a>( node.parameters.as_ref(), input_rows, )?); + assumed_data_facts.extend(assumed_magnitude_range_fact(update, input_rows)); let update_ops = update_operations_per_row( family, node.parameters.as_ref(), @@ -1599,6 +1637,7 @@ pub fn node_resource_usage_and_cost<'a>( multiplier, detail, cost_source, + assumed_data_facts, }, }) } diff --git a/crates/cost/src/node/usage/tests.rs b/crates/cost/src/node/usage/tests.rs index 7ec108d6d..d6d1f2a2c 100644 --- a/crates/cost/src/node/usage/tests.rs +++ b/crates/cost/src/node/usage/tests.rs @@ -1512,6 +1512,17 @@ fn ddsketch_state_bytes( column: &str, unchanged_columns: BTreeSet<&str>, ) -> u64 { + ddsketch_build_cost(data, producer, source, column, unchanged_columns).0 +} + +/// [`ddsketch_state_bytes`] and the build's [`NodeCost`]. +fn ddsketch_build_cost( + data: &DataWorkload, + producer: Payload, + source: &str, + column: &str, + unchanged_columns: BTreeSet<&str>, +) -> (u64, NodeCost) { use asap_types::ir::schema::{DataType, Field}; use asap_types::summary_type::SketchAlgorithm; let producer = PhysicalASAPDAGNode { @@ -1547,10 +1558,10 @@ fn ddsketch_state_bytes( state_input_rows: None, }; let settings = CostInputs::default(); - node_resource_usage_and_cost(&build, &[producer_output], (1, 1.0), None, data, &settings) - .unwrap() - .output - .bytes + let usage = + node_resource_usage_and_cost(&build, &[producer_output], (1, 1.0), None, data, &settings) + .unwrap(); + (usage.output.bytes, usage.cost) } /// The bytes `sketch_state_bytes` gives a DDSketch state at α = 0.01 over 600 @@ -1640,6 +1651,133 @@ fn a_ddsketch_over_a_scan_is_costed_at_its_declared_value_magnitude_range() { assert!(ddsketch_costed_bytes(false, Some(latency)) <= ddsketch_costed_bytes(false, None)); } +/// A DDSketch over a scan of `latency` whose `value` declares no +/// `column_magnitudes` is costed over the assumed nine decades, and its +/// node cost names that assumption: the source, the column and the range +/// [1, 1e9]. The DDSketch store grows without collapsing buckets, so its α +/// holds whatever the range and the assumption is about cost only. +/// Declared, there is none. +#[test] +fn a_ddsketch_over_an_undeclared_magnitude_range_names_the_assumed_range() { + use asap_types::workload::ValueMagnitudeRange; + use asap_types::workload::{AssumedDataFact, DataFactAssumption, SourceFacts}; + let unchanged = || BTreeSet::from(["ts", "value"]); + let (_, undeclared) = ddsketch_build_cost( + &DataWorkload::default(), + metric_scan("latency"), + "latency", + "value", + unchanged(), + ); + let assumed = AssumedDataFact { + sources: vec!["latency".to_string()], + assumption: DataFactAssumption::DDSketchValueMagnitudeRange { + column: Some("value".to_string()), + assumed_range: ValueMagnitudeRange { + min_abs: 1.0, + max_abs: 1e9, + }, + }, + }; + assert_eq!(undeclared.assumed_data_facts, vec![assumed.clone()]); + assert!(!assumed.accuracy_target_depends_on_it()); + let declared = declaring( + "latency", + SourceFacts { + column_magnitudes: BTreeMap::from([( + "value".to_string(), + ValueMagnitudeRange { + min_abs: 0.001, + max_abs: 10_000.0, + }, + )]), + ..SourceFacts::default() + }, + ); + let (_, declared) = ddsketch_build_cost( + &declared, + metric_scan("latency"), + "latency", + "value", + unchanged(), + ); + assert!(declared.assumed_data_facts.is_empty()); +} + +/// Two sources folded into one DDSketch, one declaring its `value`'s +/// magnitudes and one not: the assumption names only the source that +/// declares none, since the union of their ranges is unknown. +#[test] +fn a_ddsketch_assumption_names_only_the_sources_that_declare_no_range() { + use asap_types::workload::{DataFactAssumption, SourceFacts, ValueMagnitudeRange}; + let declared_range = ValueMagnitudeRange { + min_abs: 0.001, + max_abs: 10.0, + }; + let data = DataWorkload { + sources: BTreeMap::from([( + "a".to_string(), + SourceFacts { + column_magnitudes: BTreeMap::from([("value".to_string(), declared_range)]), + ..SourceFacts::default() + }, + )]), + ..DataWorkload::default() + }; + let facts = ddsketch_assumed_facts_over_sources(&data, &["a", "b"]); + assert_eq!(facts.len(), 1); + assert_eq!(facts[0].sources, vec!["b".to_string()]); + assert!(matches!( + facts[0].assumption, + DataFactAssumption::DDSketchValueMagnitudeRange { .. } + )); +} + +/// The assumed facts of a DDSketch build over `value` of a producer that +/// reads every source of `sources` and passes `value` on unchanged. +fn ddsketch_assumed_facts_over_sources( + data: &DataWorkload, + sources: &[&str], +) -> Vec { + use asap_types::ir::schema::{DataType, Field}; + use asap_types::summary_type::SketchAlgorithm; + let producer = PhysicalASAPDAGNode { + output_schema: Schema::new(vec![ + Field::plain("ts", DataType::Timestamp, false), + Field::plain("value", DataType::Float64, false), + ]), + ..node(metric_scan(sources[0])) + }; + let build = PhysicalASAPDAGNode { + parameters: Some(SketchParams::DDSketch { alpha: 0.01 }), + ..node(Payload::ASAP(ASAPOp::SummaryAgg { + child: 0, + summary_type: FieldDataType::Sketch(SketchAlgorithm::DDSketch), + input: SummaryUpdate::column(ColumnRef::Named("value".to_string())), + reduction: Reduction::Reduce(GroupKeys::default()), + filter: None, + })) + }; + let producer_output = ProducerOutput { + payload: &producer.payload, + output_schema: &producer.output_schema, + output: EdgeStatistics { + rows: 600, + bytes: 9_600, + }, + sources: sources.iter().copied().collect(), + family: StateFamily::None, + unchanged_columns: BTreeSet::from(["ts", "value"]), + tumbling_windows: 1, + chain_tumbling_window_width_ms: None, + }; + let settings = CostInputs::default(); + node_resource_usage_and_cost(&build, &[producer_output], (1, 1.0), None, data, &settings) + .unwrap() + .cost + .assumed_data_facts +} + /// A DDSketch over a SQL table's `latency` column that the table declares /// non-negative keeps one store: the sign is read for the folded column, /// not for a PromQL `value`. Undeclared, it keeps both stores. diff --git a/crates/cost/src/plan/cost.rs b/crates/cost/src/plan/cost.rs index d8ce14979..0d0bf9931 100644 --- a/crates/cost/src/plan/cost.rs +++ b/crates/cost/src/plan/cost.rs @@ -30,7 +30,9 @@ use asap_types::plan::physical_asap_dag::{ }; use asap_types::stages::Lifetime; use asap_types::summary_type::SketchParams; -use asap_types::workload::{DataWorkload, QueryWorkloadEntry}; +use asap_types::workload::{ + add_assumed_data_fact, AssumedDataFact, DataWorkload, QueryWorkloadEntry, +}; /// One candidate's usage and cost over the whole workload: `usage` is /// the whole candidate's, `per_node` one cost per operator node of its @@ -51,6 +53,23 @@ pub struct PlanCost { pub per_node: BTreeMap, } +impl PlanCost { + /// The data facts the data workload does not declare that its nodes' + /// costs assumed ([`NodeCost::assumed_data_facts`]), each once, in node + /// order. + pub fn assumed_data_facts(&self) -> Vec { + let mut facts = Vec::new(); + for fact in self + .per_node + .values() + .flat_map(|node| &node.assumed_data_facts) + { + add_assumed_data_fact(&mut facts, fact.clone()); + } + facts + } +} + /// One query's latency per evaluation, its longest chain of work (module /// doc, "Latency"): the compaction of the newest window of a state it reads /// from ingestion time, then the query's own work, each on a full core. diff --git a/crates/devtools/src/bin/asap_planner.rs b/crates/devtools/src/bin/asap_planner.rs index 6db6b6591..1e88584f4 100644 --- a/crates/devtools/src/bin/asap_planner.rs +++ b/crates/devtools/src/bin/asap_planner.rs @@ -69,8 +69,10 @@ // `plan_installable` derives them; `materialized_views_error` when the // plan is not installable. `warnings`: a PromQL query applying `rate`, `increase` // or `irate` to a declared gauge or combining a declared summary's -// quantile series across series (`metric_type_warnings`), and a peak memory over 10^12 bytes -// when the cost model declares no memory capacity; +// quantile series across series (`metric_type_warnings`), each data fact the selected +// plan assumed because the data workload does not declare it (`assumed_data_facts`, +// saying whether the plan may then miss its accuracy target), and a peak memory over +// 10^12 bytes when the cost model declares no memory capacity; // - memo: `nodes`, one node table for the section (each distinct node // once, children as indices before their parents), and `steps`, the // memo after each step run (`stage0`: the frontends' DAG hash-consed, @@ -99,7 +101,7 @@ use asap_devtools::planning_stages::{ use asap_devtools::planning_stages_text::planning_stages_text; use asap_devtools::SqlCatalog; use asap_frontend_promql::{metric_type_warnings, promql_metric_names}; -use asap_planner::{installable_plan_of, PlanningModels, SelectionError}; +use asap_planner::{assumed_data_facts, installable_plan_of, PlanningModels, SelectionError}; use asap_stage3_plan_selection::{large_peak_memory_warning, AcceptedAccuracy, Selection}; use asap_types::accuracy::{default_metric_for_root, AccuracyTarget}; use asap_types::deployment_capabilities::DeploymentCapabilities; @@ -222,19 +224,28 @@ fn run(args: Vec) -> Result<(), Failure> { }; // A rate, increase or irate over a declared gauge (the query still plans). let mut warnings = metric_type_warnings_of(&described, &data)?; - // A selected plan's very large peak memory, when the deployment - // declares no memory capacity to check it against. - warnings.extend( - result - .as_ref() - .ok() - .and_then(|run| run.run.selection.as_ref().ok()) - .and_then(|(plan, _)| asap_cost::plan_cost(plan, &entries, &data, &cost_inputs).ok()) - .map(|(cost, _)| cost.usage.peak_memory_bytes) - .and_then(|peak_memory_bytes| { - large_peak_memory_warning(peak_memory_bytes, &cost_inputs.cost_model) - }), - ); + // The selected plan's data facts assumed because the data workload + // does not declare them, and its very large peak memory when the + // deployment declares no memory capacity to check it against. + let selected_plan_cost = result + .as_ref() + .ok() + .and_then(|run| run.run.selection.as_ref().ok()) + .and_then(|(plan, _)| { + let (cost, _) = asap_cost::plan_cost(plan, &entries, &data, &cost_inputs).ok()?; + Some((plan, cost)) + }); + if let Some((plan, cost)) = &selected_plan_cost { + warnings.extend( + assumed_data_facts(plan, cost, &data) + .iter() + .map(ToString::to_string), + ); + warnings.extend(large_peak_memory_warning( + cost.usage.peak_memory_bytes, + &cost_inputs.cost_model, + )); + } let text = if json_format { let mut document = document_of(described, &roots, &entries, result, run_until)?; // Stage 3 is null when Pass 1 rejected a query. diff --git a/crates/devtools/tests/asap_planner.rs b/crates/devtools/tests/asap_planner.rs index 91d698cf5..ebb0dac08 100644 --- a/crates/devtools/tests/asap_planner.rs +++ b/crates/devtools/tests/asap_planner.rs @@ -1476,6 +1476,143 @@ fn a_counter_function_over_a_declared_gauge_plans_with_a_warning() { assert!(counter["stage3_plan_selection"].get("warnings").is_none()); } +/// A relative-error quantile over `m` (1,000 series, non-negative values) +/// whose `value` declares `column_magnitudes` when `magnitudes` is set. +fn relative_quantile_over(magnitudes: Option) -> Value { + let mut workload = json!({ + "query_workload": {"language": "promql", "query_batch": [{ + "query": "quantile_over_time(0.99, m[5m])", + "requirements": {"accuracy": {"max_error": 0.01, "accuracy_metric": "relative"}}, + "predictability": "unknown", "invocations": 1 + }]}, + "data_workload": {"arrival": "unknown", "sources": {"m": { + "sample_interval": 1000, "series_count": 1000, "rows_held": 600000, + "column_signs": {"value": "non_negative"} + }}} + }); + if let Some(magnitudes) = magnitudes { + workload["data_workload"]["sources"]["m"]["column_magnitudes"] = + json!({"value": magnitudes}); + } + workload +} + +/// The warning a selected DDSketch over `m`'s undeclared `value` +/// magnitudes carries. +const DDSKETCH_ASSUMED_RANGE_WARNING: &str = "assumed data fact: source m declares no \ + column_magnitudes for value, so a DDSketch state over it is costed for magnitudes in \ + [1, 1000000000]; this affects cost only, the accuracy guarantee does not depend on it"; + +/// A selected DDSketch over a column that declares no `column_magnitudes` +/// is costed over an assumed range, and the plan output names that +/// assumption under `stage3_plan_selection.warnings` and in the text +/// output, once. Declaring the range removes it. +#[test] +fn a_selected_ddsketch_over_undeclared_magnitudes_is_warned_about() { + let no_raw = TempFile::new(NO_RAW); + let args = [ + "--run-until", + "stage3", + "--deployment-capabilities", + no_raw.path(), + ]; + let undeclared = document(&relative_quantile_over(None), &args); + let selection = &undeclared["stage3_plan_selection"]; + assert!(selects_a_plan(selection), "{selection}"); + assert_eq!( + selection["accepted_accuracy_per_query"][0]["sketches"], + json!(["DDSketch"]), + "{selection}" + ); + assert_eq!( + selection["warnings"], + json!([DDSKETCH_ASSUMED_RANGE_WARNING]) + ); + let file = TempFile::json(&relative_quantile_over(None)); + let mut text_args = vec!["--workload", file.path()]; + text_args.extend_from_slice(&args); + let output = planner(&text_args); + assert!(output.status.success()); + let text = String::from_utf8(output.stdout).unwrap(); + assert_eq!( + text.lines() + .filter_map(|line| line.strip_prefix("warning: ")) + .collect::>(), + [DDSKETCH_ASSUMED_RANGE_WARNING] + ); + let declared = document( + &relative_quantile_over(Some(json!({"min_abs": 0.001, "max_abs": 10000.0}))), + &args, + ); + assert!(selects_a_plan(&declared["stage3_plan_selection"])); + assert!(declared["stage3_plan_selection"].get("warnings").is_none()); +} + +/// `sum by (job) (rate(http_requests_total[1m]))` every minute over +/// ingesting samples of a counter, with `max_out_of_order_ms` when set. +fn repeating_rate_over_ingesting(max_out_of_order_ms: Option) -> Value { + let mut arrival = json!({"rows_per_second": 1000.0}); + if let Some(bound) = max_out_of_order_ms { + arrival["max_out_of_order_ms"] = json!(bound); + } + json!({ + "query_workload": { + "language": "promql", + "query_batch": null, + "repeating_queries": [{ + "query": "sum by (job) (rate(http_requests_total[1m]))", + "demand": {"fixed_interval_at": {"interval": 60000, "evaluation_phase": 0}}, + "requirements": {}, + "predictability": {"predictable": {"known_at": null}}, + }], + }, + "data_workload": { + "arrival": {"ingesting": arrival}, + "sources": {"http_requests_total": { + "series_count": 15000, "metric_type": "counter", "sample_interval": 15000 + }}, + }, + }) +} + +/// The warning an ingestion-time `rate` state over +/// `http_requests_total` carries when the arrival declares no +/// `max_out_of_order_ms`. +const IN_ORDER_ARRIVAL_WARNING: &str = "assumed data fact: the data arrival declares no \ + max_out_of_order_ms, so the samples of source http_requests_total an ingestion-time rate, \ + increase or irate state folds are taken to arrive in timestamp order; the plan may not \ + meet its accuracy target if this does not hold"; + +/// A deployment that keeps no raw data computes a repeating `rate` at +/// ingestion time. Without a declared `max_out_of_order_ms` its samples are +/// taken to arrive in order, which the exact answer depends on, so the plan +/// output warns that it may not meet its accuracy target. A declared bound +/// removes the warning and leaves the plan as it was. +#[test] +fn an_ingestion_time_rate_over_undeclared_arrival_order_is_warned_about() { + let no_raw = TempFile::new(NO_RAW); + let args = [ + "--run-until", + "stage3", + "--deployment-capabilities", + no_raw.path(), + ]; + let undeclared = document(&repeating_rate_over_ingesting(None), &args); + let selection = &undeclared["stage3_plan_selection"]; + assert!(selects_a_plan(selection), "{selection}"); + assert_eq!(selection["warnings"], json!([IN_ORDER_ARRIVAL_WARNING])); + let declared = document(&repeating_rate_over_ingesting(Some(5_000)), &args); + let declared_selection = &declared["stage3_plan_selection"]; + assert!( + declared_selection.get("warnings").is_none(), + "{declared_selection}" + ); + assert_eq!( + declared_selection["selected_dag"], + selection["selected_dag"] + ); +} + /// A PromQL file and a SQL file, each a `PlanningWorkload` in its own /// language. fn mixed_language_workload_files(sql_arrival: Value, sql_facts: Value) -> (TempFile, TempFile) { diff --git a/crates/planner/src/installable/mod.rs b/crates/planner/src/installable/mod.rs index 21e0e6070..bd6b635b0 100644 --- a/crates/planner/src/installable/mod.rs +++ b/crates/planner/src/installable/mod.rs @@ -37,7 +37,7 @@ use asap_types::plan::physical_asap_dag::{ PhysicalASAPNodeId, }; -use asap_types::workload::QueryWorkloadEntry; +use asap_types::workload::{AssumedDataFact, DataWorkload, QueryWorkloadEntry}; use serde::{Deserialize, Serialize}; use crate::{e2e_plan, PlanError, UserInput}; @@ -73,6 +73,9 @@ pub struct SelectedPlanReport { /// The resources Stage 3 predicts it uses, for a runtime to report /// against what it measures. pub predicted_usage: PredictedUsage, + /// The data facts the data workload does not declare that the plan + /// assumed, each once ([`assumed_data_facts`]). + pub assumed_data_facts: Vec, } /// What Stage 3 predicts the selected plan uses, per second of wall time @@ -222,8 +225,9 @@ pub async fn plan_installable( }) }, )?; + let assumed_data_facts = assumed_data_facts(&output.plan, &cost, &data); let installable = installable_plan_of(output.plan, &entries).map_err(PlanError::Installable)?; - Ok((installable, report_of(&cost))) + Ok((installable, report_of(&cost, assumed_data_facts))) } /// The installable plan of `plan`, the plan Stage 3 built for a workload @@ -546,7 +550,27 @@ fn executor_refreshes( } /// The report of the selected plan's `cost`. -fn report_of(cost: &PlanCost) -> SelectedPlanReport { +/// The data facts the selected `plan` (costed as `cost`) assumed because +/// `data` does not declare them, each once: those its nodes' costs assumed +/// ([`PlanCost::assumed_data_facts`]), then the in-order arrival Stage 2 +/// offered its ingestion-time counter states under +/// ([`asap_stage2_physical_optimization::assumed_in_order_arrival`]). A +/// caller prints each as a warning +/// ([`AssumedDataFact::accuracy_target_depends_on_it`] says whether the +/// plan may miss its accuracy target when the assumption fails). +pub fn assumed_data_facts( + plan: &PhysicalASAPDAG, + cost: &PlanCost, + data: &DataWorkload, +) -> Vec { + let mut facts = cost.assumed_data_facts(); + facts.extend(asap_stage2_physical_optimization::assumed_in_order_arrival( + plan, data, + )); + facts +} + +fn report_of(cost: &PlanCost, assumed_data_facts: Vec) -> SelectedPlanReport { SelectedPlanReport { cost_per_second: cost.cost_per_second, predicted_usage: PredictedUsage { @@ -582,6 +606,7 @@ fn report_of(cost: &PlanCost) -> SelectedPlanReport { }) .collect(), }, + assumed_data_facts, } } diff --git a/crates/planner/src/lib.rs b/crates/planner/src/lib.rs index f6628b986..cc9b7afa5 100644 --- a/crates/planner/src/lib.rs +++ b/crates/planner/src/lib.rs @@ -52,9 +52,9 @@ pub use run::{ mod installable; pub use installable::{ - installable_plan_of, plan_installable, InstallablePlan, InstallablePlanError, - PredictedNodeUsage, PredictedQueryUsage, PredictedUsage, SelectedPlanReport, - INSTALLABLE_PLAN_WIRE_VERSION, + assumed_data_facts, installable_plan_of, plan_installable, InstallablePlan, + InstallablePlanError, PredictedNodeUsage, PredictedQueryUsage, PredictedUsage, + SelectedPlanReport, INSTALLABLE_PLAN_WIRE_VERSION, }; // What a deployment runtime needs to build a `UserInput` and read an diff --git a/crates/planner/tests/runtime_install.rs b/crates/planner/tests/runtime_install.rs index 1f95f8b03..d340029e8 100644 --- a/crates/planner/tests/runtime_install.rs +++ b/crates/planner/tests/runtime_install.rs @@ -927,3 +927,85 @@ async fn sum_rate_at_10_hz_with_unknown_arrival_installs_and_answers() { assert!((rate - 20.0).abs() < 0.01, "{labels:?}: {rate}"); } } + +/// A deployment that keeps no raw samples computes a repeating `rate` at +/// ingestion time; the arrival declares no `max_out_of_order_ms`, so the +/// samples are taken to arrive in order. The report beside the plan names +/// that assumed fact and that the accuracy target depends on it. +#[tokio::test] +async fn the_report_names_the_data_facts_the_plan_assumed() { + use asap_types::workload::{AssumedDataFact, DataFactAssumption}; + let workload: PlanningWorkload = serde_json::from_str( + r#"{"query_workload": {"language": "promql", "repeating_queries": [{ + "query": "sum(rate(requests_total[1m]))", + "demand": {"fixed_interval_at": {"interval": 60000, "evaluation_phase": 0}}, + "requirements": {}, + "predictability": {"predictable": {"known_at": null}}}]}, + "data_workload": {"arrival": {"ingesting": {"rows_per_second": 1000.0}}, + "sources": {"requests_total": {"series_count": 1000, "sample_interval": 1000, + "metric_type": "counter"}}}}"#, + ) + .unwrap(); + let capabilities = DeploymentCapabilities { + raw_data_retained: false, + ..DeploymentCapabilities::default() + }; + let (_, report) = plan_with_report_for(workload, &capabilities).await; + let in_order = AssumedDataFact { + sources: vec!["requests_total".into()], + assumption: DataFactAssumption::InOrderArrival, + }; + assert_eq!(report.assumed_data_facts, vec![in_order.clone()]); + assert!(in_order.accuracy_target_depends_on_it()); +} + +/// A repeating relative-error p99 over non-negative latencies on a +/// deployment that keeps no raw samples is served by a DDSketch, whose +/// `value` declares no `column_magnitudes`: the report names the assumed +/// range, which affects cost only. Declaring the range removes it. +#[tokio::test] +async fn the_report_names_a_ddsketch_s_assumed_magnitude_range() { + use asap_types::workload::{AssumedDataFact, DataFactAssumption, ValueMagnitudeRange}; + let workload = |magnitudes: &str| -> PlanningWorkload { + serde_json::from_str(&format!( + r#"{{"query_workload": {{"language": "promql", "repeating_queries": [{{ + "query": "quantile_over_time(0.99, latency_ms[10m])", + "demand": {{"fixed_interval_at": {{"interval": 600000, "evaluation_phase": 0}}}}, + "requirements": {{"accuracy": {{"accuracy_metric": "relative", "max_error": 0.01}}}}, + "predictability": {{"predictable": {{"known_at": null}}}}}}]}}, + "data_workload": {{"arrival": {{"ingesting": {{"rows_per_second": 1000.0}}}}, + "sources": {{"latency_ms": {{"series_count": 1000, "sample_interval": 1000, + "column_signs": {{"value": "non_negative"}}{magnitudes}}}}}}}}}"# + )) + .unwrap() + }; + let capabilities = DeploymentCapabilities { + raw_data_retained: false, + ..DeploymentCapabilities::default() + }; + let (plan, report) = plan_with_report_for(workload(""), &capabilities).await; + assert!( + serde_json::to_string(&plan.dag) + .unwrap() + .contains("DDSketch"), + "a DDSketch plan" + ); + let assumed = AssumedDataFact { + sources: vec!["latency_ms".into()], + assumption: DataFactAssumption::DDSketchValueMagnitudeRange { + column: Some("value".into()), + assumed_range: ValueMagnitudeRange { + min_abs: 1.0, + max_abs: 1e9, + }, + }, + }; + assert_eq!(report.assumed_data_facts, vec![assumed.clone()]); + assert!(!assumed.accuracy_target_depends_on_it()); + let (_, declared) = plan_with_report_for( + workload(r#", "column_magnitudes": {"value": {"min_abs": 0.1, "max_abs": 100000.0}}"#), + &capabilities, + ) + .await; + assert!(declared.assumed_data_facts.is_empty()); +} diff --git a/crates/stage2-physical-optimization/src/candidate.rs b/crates/stage2-physical-optimization/src/candidate.rs index f8e6aef59..e841cb68a 100644 --- a/crates/stage2-physical-optimization/src/candidate.rs +++ b/crates/stage2-physical-optimization/src/candidate.rs @@ -5,17 +5,23 @@ //! the reason a prune rule removes it. Each prune rule reads only the value //! it removes and the values decided above it. +use std::collections::{BTreeSet, HashMap, HashSet}; + use asap_types::deployment_capabilities::DeploymentCapabilities; use asap_types::ir::operator::arguments::Source; use asap_types::ir::properties::ExecutionTiming; use asap_types::ir::schema::FieldDataType; use asap_types::ir::{ASAPOp, NonASAPOp, Operator}; +use asap_types::plan::physical_asap_dag::{ + PhysicalASAPDAG, PhysicalASAPDAGNode, PhysicalASAPNodeId, +}; use asap_types::stages::{ CandidateForMemoGroupId, Lifetime, Memo, MemoGroupId, PhysicalProperties, PruneReason, StorageMedium, ValueSign, }; use asap_types::summary_type::SketchAlgorithm; -use asap_types::workload::{DataArrival, DataWorkload}; +use asap_types::workload::bounds::source_name; +use asap_types::workload::{AssumedDataFact, DataFactAssumption, DataWorkload}; /// Level 3's values, $\tau$. const TIMINGS: [ExecutionTiming; 2] = [ExecutionTiming::QueryTime, ExecutionTiming::IngestionTime]; @@ -121,7 +127,7 @@ pub(super) fn offered_physical_properties( /// The summary type and input group of `operator` when it builds a /// summary state from rows (`SummaryAgg`, `SummaryTumblingWindowChain`). -fn summary_build(operator: &Operator) -> Option<(&FieldDataType, MemoGroupId)> { +fn summary_build(operator: &Operator) -> Option<(&FieldDataType, C)> { match operator { Operator::ASAP( ASAPOp::SummaryAgg { @@ -143,30 +149,16 @@ fn summary_build(operator: &Operator) -> Option<(&FieldDataType, Me /// counter state (`rate`, `increase`, `irate`), gets its rows in timestamp /// order at ingestion time: the data declares how late a row may arrive /// (`max_out_of_order_ms`), so a reorder buffer restores the order, or its -/// rows are PromQL samples, taken to arrive in order. True for any other -/// summary type. +/// rows are PromQL samples, taken to arrive in order (an assumed data fact, +/// [`assumed_in_order_arrival`]). True for any other summary type. fn counter_state_rows_ordered( memo: &Memo, summary_type: &FieldDataType, child: MemoGroupId, data: &DataWorkload, ) -> bool { - let counter_state = matches!( - summary_type, - FieldDataType::ExactAggregate(kind, _) if kind.tracks_counter_increase() - ); - let out_of_order_bound_known = matches!( - data.arrival, - DataArrival::Ingesting { - max_out_of_order_ms: Some(_), - .. - } | DataArrival::Mixed { - max_out_of_order_ms: Some(_), - .. - } - ); - !counter_state - || out_of_order_bound_known + !is_counter_state(summary_type) + || data.arrival.max_out_of_order_ms().is_some() || memo.groups()[child.0 as usize] .group_properties .scanned_sources @@ -174,6 +166,63 @@ fn counter_state_rows_ordered( .all(Source::is_time_series) } +/// Whether a state of `summary_type` is a counter state (`rate`, +/// `increase`, `irate`), which reads a late sample as a counter reset. +fn is_counter_state(summary_type: &FieldDataType) -> bool { + matches!( + summary_type, + FieldDataType::ExactAggregate(kind, _) if kind.tracks_counter_increase() + ) +} + +/// The data fact `plan` assumed by [`counter_state_rows_ordered`]: when +/// the arrival declares no `max_out_of_order_ms`, each ingestion-time +/// counter state it builds was offered only because its PromQL samples are +/// taken to arrive in timestamp order. One fact naming the metrics those +/// states read, in name order; none when there is no such state. E.g. an +/// ingestion-time `rate(requests_total[1m])` state gives `InOrderArrival` +/// over `requests_total`. +pub fn assumed_in_order_arrival( + plan: &PhysicalASAPDAG, + data: &DataWorkload, +) -> Option { + if data.arrival.max_out_of_order_ms().is_some() { + return None; + } + let nodes: HashMap = + plan.nodes.iter().map(|node| (node.id, node)).collect(); + let mut metrics = BTreeSet::new(); + for node in &plan.nodes { + let Some((summary_type, _)) = summary_build(&node.payload) else { + continue; + }; + if node.output_state.timing != ExecutionTiming::IngestionTime + || !is_counter_state(summary_type) + { + continue; + } + // The metrics its samples come from: the scans below it. + let mut below = node.producers(); + let mut seen = HashSet::new(); + while let Some(id) = below.pop() { + if !seen.insert(id) { + continue; + } + let producer = nodes[&id]; + match &producer.payload { + Operator::NonASAP(NonASAPOp::Scan { source, .. }) => { + metrics.insert(source_name(source).to_string()); + } + _ => below.extend(producer.producers()), + } + } + } + (!metrics.is_empty()).then(|| AssumedDataFact { + sources: metrics.into_iter().collect(), + assumption: DataFactAssumption::InOrderArrival, + }) +} + /// Whether a build of `summary_type` in group `group` is a Count-Min state /// (`Cms`, `CmsWithHeap`, `HydraCms`) whose weights are not proven /// non-negative: the state column of its group, which records the sign of diff --git a/crates/stage2-physical-optimization/src/lib.rs b/crates/stage2-physical-optimization/src/lib.rs index 66e05aa4a..208aa88a3 100644 --- a/crates/stage2-physical-optimization/src/lib.rs +++ b/crates/stage2-physical-optimization/src/lib.rs @@ -31,6 +31,7 @@ use asap_types::stages::{ }; use asap_types::workload::DataWorkload; +pub use candidate::assumed_in_order_arrival; use candidate::{offered_physical_properties, OfferedPhysicalProperties}; /// Stage 2: expand every logical candidate of `logical` that survived Pass 2 diff --git a/crates/types/src/workload/assumed_data_fact.rs b/crates/types/src/workload/assumed_data_fact.rs new file mode 100644 index 000000000..97af6076d --- /dev/null +++ b/crates/types/src/workload/assumed_data_fact.rs @@ -0,0 +1,183 @@ +//! A data fact the data workload does not declare, which the planner +//! replaced by a written default: what it assumed, for which sources, and +//! whether a plan's accuracy target depends on the assumption. The plan +//! output names each one as a warning, so a deployment knows which facts to +//! declare. + +use std::fmt; + +use serde::{Deserialize, Serialize}; + +use super::ValueMagnitudeRange; + +/// One assumption a plan rests on. E.g. a DDSketch over `latency`'s +/// `value`, whose source declares no `column_magnitudes`, is costed for +/// magnitudes in [1, 1e9]: +/// `AssumedDataFact { sources: ["latency"], assumption: +/// DDSketchValueMagnitudeRange { column: "value", assumed_range: [1, 1e9] } }`. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct AssumedDataFact { + /// The sources (PromQL metrics or SQL tables) the assumption is about, + /// those that do not declare the fact, in name order. + pub sources: Vec, + /// What was assumed in place of the undeclared fact. + pub assumption: DataFactAssumption, +} + +/// The default value the planner used for one undeclared fact. JSON: the +/// snake_case variant name, e.g. `{"ddsketch_value_magnitude_range": +/// {"column": "value", "assumed_range": {"min_abs": 1.0, "max_abs": 1e9}}}`. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case", deny_unknown_fields)] +pub enum DataFactAssumption { + /// The sources declare no `column_magnitudes` for `column`, so a + /// DDSketch state over it is costed for magnitudes in `assumed_range`. + /// `column` is `None` when the state folds values computed from the + /// sources (e.g. rates), whose magnitudes no source fact declares. + /// Cost only: the DDSketch store grows to whatever range the values + /// span, so its relative error α holds for any range. + #[serde(rename = "ddsketch_value_magnitude_range")] + DDSketchValueMagnitudeRange { + column: Option, + assumed_range: ValueMagnitudeRange, + }, + /// The data arrival declares no `max_out_of_order_ms`, so the PromQL + /// samples an ingestion-time `rate`, `increase` or `irate` state folds + /// are taken to arrive in timestamp order. A sample arriving late is + /// read as a counter reset, so the exact answer may be wrong. + InOrderArrival, +} + +impl AssumedDataFact { + /// Whether the selected plan may miss a query's accuracy target when + /// the assumption does not hold; otherwise only its cost is assumed. + pub fn accuracy_target_depends_on_it(&self) -> bool { + match self.assumption { + DataFactAssumption::DDSketchValueMagnitudeRange { .. } => false, + DataFactAssumption::InOrderArrival => true, + } + } +} + +/// The warning line, e.g. "assumed data fact: source latency declares no +/// column_magnitudes for value, so a DDSketch state over it is costed for +/// magnitudes in [1, 1000000000]; this affects cost only, the accuracy +/// guarantee does not depend on it". +impl fmt::Display for AssumedDataFact { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let sources = match self.sources.as_slice() { + [one] => format!("source {one}"), + many => format!("sources {}", many.join(", ")), + }; + write!(f, "assumed data fact: ")?; + match &self.assumption { + DataFactAssumption::DDSketchValueMagnitudeRange { + column, + assumed_range, + } => { + match column { + Some(column) => write!( + f, + "{sources} declares no column_magnitudes for {column}, so a DDSketch \ + state over it" + )?, + None => write!( + f, + "a DDSketch state folds values computed from {sources}, whose \ + magnitudes no source declares, so it" + )?, + } + write!( + f, + " is costed for magnitudes in [{}, {}]", + assumed_range.min_abs, assumed_range.max_abs + )? + } + DataFactAssumption::InOrderArrival => write!( + f, + "the data arrival declares no max_out_of_order_ms, so the samples of {sources} \ + an ingestion-time rate, increase or irate state folds are taken to arrive in \ + timestamp order" + )?, + } + if self.accuracy_target_depends_on_it() { + write!( + f, + "; the plan may not meet its accuracy target if this does not hold" + ) + } else { + write!( + f, + "; this affects cost only, the accuracy guarantee does not depend on it" + ) + } + } +} + +/// Adds `fact` to `facts` unless an equal one is there: a plan names each +/// assumption once, however many of its nodes rest on it. +pub fn add_assumed_data_fact(facts: &mut Vec, fact: AssumedDataFact) { + if !facts.contains(&fact) { + facts.push(fact); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// One source is named alone, several in a list; an accuracy-affecting + /// assumption says the plan may miss its target. + #[test] + fn the_warning_names_the_sources_the_default_and_the_accuracy_effect() { + let ddsketch = AssumedDataFact { + sources: vec!["latency".into()], + assumption: DataFactAssumption::DDSketchValueMagnitudeRange { + column: Some("value".into()), + assumed_range: ValueMagnitudeRange { + min_abs: 1.0, + max_abs: 1e9, + }, + }, + }; + assert_eq!( + ddsketch.to_string(), + "assumed data fact: source latency declares no column_magnitudes for value, so a \ + DDSketch state over it is costed for magnitudes in [1, 1000000000]; this affects \ + cost only, the accuracy guarantee does not depend on it" + ); + let computed = AssumedDataFact { + sources: vec!["requests_total".into()], + assumption: DataFactAssumption::DDSketchValueMagnitudeRange { + column: None, + assumed_range: ValueMagnitudeRange { + min_abs: 1.0, + max_abs: 1e9, + }, + }, + }; + assert_eq!( + computed.to_string(), + "assumed data fact: a DDSketch state folds values computed from source \ + requests_total, whose magnitudes no source declares, so it is costed for \ + magnitudes in [1, 1000000000]; this affects cost only, the accuracy guarantee \ + does not depend on it" + ); + let in_order = AssumedDataFact { + sources: vec!["a_total".into(), "b_total".into()], + assumption: DataFactAssumption::InOrderArrival, + }; + assert_eq!( + in_order.to_string(), + "assumed data fact: the data arrival declares no max_out_of_order_ms, so the \ + samples of sources a_total, b_total an ingestion-time rate, increase or irate \ + state folds are taken to arrive in timestamp order; the plan may not meet its \ + accuracy target if this does not hold" + ); + let mut facts = vec![]; + add_assumed_data_fact(&mut facts, in_order.clone()); + add_assumed_data_fact(&mut facts, in_order); + assert_eq!(facts.len(), 1); + } +} diff --git a/crates/types/src/workload/data.rs b/crates/types/src/workload/data.rs index e6c884081..cd05aa860 100644 --- a/crates/types/src/workload/data.rs +++ b/crates/types/src/workload/data.rs @@ -66,6 +66,22 @@ impl DataArrival { Self::AtRest | Self::Unknown => None, } } + + /// How late a row may arrive, when the data is ingesting or mixed and + /// declares it; `None` otherwise. + pub fn max_out_of_order_ms(&self) -> Option { + match self { + Self::Ingesting { + max_out_of_order_ms, + .. + } + | Self::Mixed { + max_out_of_order_ms, + .. + } => *max_out_of_order_ms, + Self::AtRest | Self::Unknown => None, + } + } } /// Queries per second, samples per second, or another rate whose unit is diff --git a/crates/types/src/workload/mod.rs b/crates/types/src/workload/mod.rs index 96dd88390..703ac68fe 100644 --- a/crates/types/src/workload/mod.rs +++ b/crates/types/src/workload/mod.rs @@ -1,13 +1,17 @@ //! The workload the planner plans for, by scope: the query workload //! (`query`), the data workload (`data`), the two planned together -//! (`planning`), and the bounds read from them ([`bounds`]). +//! (`planning`), the bounds read from them ([`bounds`]), and the data facts +//! a plan assumed because the data workload does not declare them +//! (`assumed_data_fact`). +mod assumed_data_fact; pub mod bounds; mod data; pub mod parsed_workload; mod planning; mod query; +pub use assumed_data_fact::{add_assumed_data_fact, AssumedDataFact, DataFactAssumption}; pub(crate) use data::series_facts; pub use data::{ DataArrival, DataWorkload, LabelSetDistinctValues, PrometheusMetricType, Rate, SourceFacts, From 5f1389059e0ec91bcded0940c683e172743bac0e Mon Sep 17 00:00:00 2001 From: zzylol <50204836+zzylol@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:19:54 +0000 Subject: [PATCH 2/3] fix(types, cost, stage2, planner): round-1 review of the assumed-fact warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - The in-order arrival warning and its type doc are executor-neutral and say what a late sample does: answers may be wrong by an amount no accuracy target bounds, or ingestion may fail. - Stage 2's offer and the in-order report read one rule, `ingestion_row_order`; the report walks the plan once with one visited set. - The DDSketch default range is applied only through `assumed_magnitude_range`, which names no range for an α costed as an empty sketch. - `folded_values` returns the folded column; the dedup helper is inlined into `PlanCost::assumed_data_facts`. - An empty source list reads "the data workload". - `SelectedPlanReport::assumed_data_facts` defaults when absent and is omitted when empty; `asap_planner` JSON also emits `stage3_plan_selection.assumed_data_facts` as records. - Planner tests: a declared `max_out_of_order_ms` gives no fact and the same plan; declared magnitudes give no fact and still a DDSketch. --- crates/cost/src/node/state_bytes/tests.rs | 43 ++++++ crates/cost/src/node/usage/mod.rs | 53 ++++--- crates/cost/src/plan/cost.rs | 10 +- crates/devtools/src/bin/asap_planner.rs | 24 ++-- crates/devtools/tests/asap_planner.rs | 26 +++- crates/planner/src/installable/mod.rs | 6 +- crates/planner/tests/runtime_install.rs | 58 ++++++-- .../src/candidate.rs | 132 +++++++++++------- .../types/src/workload/assumed_data_fact.rs | 65 +++++---- crates/types/src/workload/mod.rs | 2 +- 10 files changed, 280 insertions(+), 139 deletions(-) diff --git a/crates/cost/src/node/state_bytes/tests.rs b/crates/cost/src/node/state_bytes/tests.rs index 90922a92e..8d5a0bf6a 100644 --- a/crates/cost/src/node/state_bytes/tests.rs +++ b/crates/cost/src/node/state_bytes/tests.rs @@ -241,6 +241,49 @@ fn ddsketch_state_bytes_match_the_library_on_latency_like_values() { assert!(priced(Some(10), true) < priced(Some(3_000), true)); } +/// The range a DDSketch is costed for when its values declare none is the +/// one `assumed_magnitude_range` names, and only when the sketch is costed +/// over a range: at α = 0.01 with no declared range it is [1, 1e9]; a +/// declared range, another sketch, or α = 1.5 (costed as an empty sketch) +/// assumes none. +#[test] +fn the_assumed_ddsketch_range_is_named_only_when_the_bytes_use_it() { + let rows = |value_magnitude_range| StateInputRows { + rows_per_state: Some(600), + non_negative: true, + value_magnitude_range, + }; + let declared = ValueMagnitudeRange { + min_abs: 0.001, + max_abs: 10_000.0, + }; + let ddsketch = |alpha| SketchParams::DDSketch { alpha }; + assert_eq!( + assumed_magnitude_range(&ddsketch(0.01), rows(None)), + Some(DDSKETCH_ASSUMED_MAGNITUDE_RANGE) + ); + assert_eq!( + sketch_state_bytes(&ddsketch(0.01), rows(None)), + sketch_state_bytes( + &ddsketch(0.01), + rows(Some(DDSKETCH_ASSUMED_MAGNITUDE_RANGE)) + ) + ); + assert_eq!( + assumed_magnitude_range(&ddsketch(0.01), rows(Some(declared))), + None + ); + assert_eq!(assumed_magnitude_range(&ddsketch(1.5), rows(None)), None); + assert_eq!( + sketch_state_bytes(&ddsketch(1.5), rows(None)), + std::mem::size_of::() as u64 + ); + assert_eq!( + assumed_magnitude_range(&SketchParams::Kll { k: 200 }, rows(None)), + None + ); +} + /// A DDSketch's span is the smallest of the exponential spread of its /// rows, its column's declared `column_magnitudes` and the assumed nine /// decades. At α = 0.01, non-negative values: diff --git a/crates/cost/src/node/usage/mod.rs b/crates/cost/src/node/usage/mod.rs index 3faa76dcb..81566ca23 100644 --- a/crates/cost/src/node/usage/mod.rs +++ b/crates/cost/src/node/usage/mod.rs @@ -572,22 +572,23 @@ pub fn node_resource_usage_and_cost<'a>( .ok_or(AnalyticalCostError::Overflow)?, }) }; - // What the sources declare about the values a summary built here folds: - // whether every one is non-negative, and their magnitude range, both - // from the one source column it folds - // (`ProducerOutput::unchanged_column`). + // The one source column a summary built here folds + // (`ProducerOutput::unchanged_column`; `None` for computed values), and + // what the sources declare about its values: whether every one is + // non-negative, and their magnitude range. let folded_values = |update: &SummaryUpdate| { - producers + let column = producers .first() - .and_then(|producer| producer.unchanged_column(&update.weight)) - .map_or((false, None), |column| { - let non_negative = !sources.is_empty() - && sources - .iter() - .all(|source| declared_non_negative(data, source, column)); - let range = declared_value_magnitude_range(data, sources.iter().copied(), column); - (non_negative, range) - }) + .and_then(|producer| producer.unchanged_column(&update.weight)); + let (non_negative, range) = column.map_or((false, None), |column| { + let non_negative = !sources.is_empty() + && sources + .iter() + .all(|source| declared_non_negative(data, source, column)); + let range = declared_value_magnitude_range(data, sources.iter().copied(), column); + (non_negative, range) + }); + (column, non_negative, range) }; // The distinct values a source column passed on unchanged takes per // evaluation, as every source declares them @@ -638,19 +639,17 @@ pub fn node_resource_usage_and_cost<'a>( state_bytes_per_row(producer.output, producer.output_schema) }) }; - // The magnitude range a summary built here over `input_rows` is costed - // for when its values declare none (`assumed_magnitude_range`), named - // with the sources that declare no range for the column it folds (every - // source when it folds computed values). None when the measured table - // gives its bytes, which assume no range. - let assumed_magnitude_range_fact = |update: &SummaryUpdate, input_rows: StateInputRows| { + // The magnitude range a summary built here over `input_rows` of + // `column` is costed for when its values declare none + // (`assumed_magnitude_range`), named with the sources that declare no + // range for that column (every source when it folds computed values, + // `column` `None`). None when the measured table gives its bytes, which + // assume no range. + let assumed_magnitude_range_fact = |column: Option<&str>, input_rows: StateInputRows| { if measured_state_bytes.is_some() { return None; } let assumed_range = assumed_magnitude_range(node.parameters.as_ref()?, input_rows)?; - let column = producers - .first() - .and_then(|producer| producer.unchanged_column(&update.weight)); let undeclared = sources .iter() .copied() @@ -1077,7 +1076,7 @@ pub fn node_resource_usage_and_cost<'a>( // At query time, each state sees its group's input rows; at // ingestion time, the rows of a window one second of // arriving rows does not bound. - let (non_negative, value_magnitude_range) = folded_values(update); + let (column, non_negative, value_magnitude_range) = folded_values(update); let input_rows = StateInputRows { rows_per_state: (!ingestion).then(|| input.rows.div_ceil(group_count.max(1))), non_negative, @@ -1089,7 +1088,7 @@ pub fn node_resource_usage_and_cost<'a>( node.parameters.as_ref(), input_rows, )?); - assumed_data_facts.extend(assumed_magnitude_range_fact(update, input_rows)); + assumed_data_facts.extend(assumed_magnitude_range_fact(column, input_rows)); let update_ops = update_operations_per_row( family, node.parameters.as_ref(), @@ -1147,7 +1146,7 @@ pub fn node_resource_usage_and_cost<'a>( .clamp(1, input.rows.max(1)) }), }; - let (non_negative, value_magnitude_range) = folded_values(update); + let (column, non_negative, value_magnitude_range) = folded_values(update); let input_rows = StateInputRows { rows_per_state: Some(rows_per_tumbling_window.div_ceil(group_count.max(1))), non_negative, @@ -1159,7 +1158,7 @@ pub fn node_resource_usage_and_cost<'a>( node.parameters.as_ref(), input_rows, )?); - assumed_data_facts.extend(assumed_magnitude_range_fact(update, input_rows)); + assumed_data_facts.extend(assumed_magnitude_range_fact(column, input_rows)); let update_ops = update_operations_per_row( family, node.parameters.as_ref(), diff --git a/crates/cost/src/plan/cost.rs b/crates/cost/src/plan/cost.rs index 0d0bf9931..9d6c5de9c 100644 --- a/crates/cost/src/plan/cost.rs +++ b/crates/cost/src/plan/cost.rs @@ -30,9 +30,7 @@ use asap_types::plan::physical_asap_dag::{ }; use asap_types::stages::Lifetime; use asap_types::summary_type::SketchParams; -use asap_types::workload::{ - add_assumed_data_fact, AssumedDataFact, DataWorkload, QueryWorkloadEntry, -}; +use asap_types::workload::{AssumedDataFact, DataWorkload, QueryWorkloadEntry}; /// One candidate's usage and cost over the whole workload: `usage` is /// the whole candidate's, `per_node` one cost per operator node of its @@ -64,7 +62,11 @@ impl PlanCost { .values() .flat_map(|node| &node.assumed_data_facts) { - add_assumed_data_fact(&mut facts, fact.clone()); + // A plan names each assumption once, however many of its nodes + // rest on it. + if !facts.contains(fact) { + facts.push(fact.clone()); + } } facts } diff --git a/crates/devtools/src/bin/asap_planner.rs b/crates/devtools/src/bin/asap_planner.rs index 1e88584f4..7b1b04399 100644 --- a/crates/devtools/src/bin/asap_planner.rs +++ b/crates/devtools/src/bin/asap_planner.rs @@ -71,8 +71,9 @@ // or `irate` to a declared gauge or combining a declared summary's // quantile series across series (`metric_type_warnings`), each data fact the selected // plan assumed because the data workload does not declare it (`assumed_data_facts`, -// saying whether the plan may then miss its accuracy target), and a peak memory over -// 10^12 bytes when the cost model declares no memory capacity; +// saying whether answers may then be wrong beyond the accuracy target), and a peak +// memory over 10^12 bytes when the cost model declares no memory capacity; +// `assumed_data_facts`: those facts as records (`AssumedDataFact`), when there are any; // - memo: `nodes`, one node table for the section (each distinct node // once, children as indices before their parents), and `steps`, the // memo after each step run (`stage0`: the frontends' DAG hash-consed, @@ -235,12 +236,12 @@ fn run(args: Vec) -> Result<(), Failure> { let (cost, _) = asap_cost::plan_cost(plan, &entries, &data, &cost_inputs).ok()?; Some((plan, cost)) }); - if let Some((plan, cost)) = &selected_plan_cost { - warnings.extend( - assumed_data_facts(plan, cost, &data) - .iter() - .map(ToString::to_string), - ); + let assumed_facts = selected_plan_cost + .as_ref() + .map(|(plan, cost)| assumed_data_facts(plan, cost, &data)) + .unwrap_or_default(); + warnings.extend(assumed_facts.iter().map(ToString::to_string)); + if let Some((_, cost)) = &selected_plan_cost { warnings.extend(large_peak_memory_warning( cost.usage.peak_memory_bytes, &cost_inputs.cost_model, @@ -253,6 +254,13 @@ fn run(args: Vec) -> Result<(), Failure> { if !warnings.is_empty() { stage3.insert("warnings".into(), json!(warnings)); } + // The same assumed facts as records, for a machine reader. + if !assumed_facts.is_empty() { + stage3.insert( + "assumed_data_facts".into(), + serde_json::to_value(&assumed_facts).map_err(|e| e.to_string())?, + ); + } } document["workload"]["data_workload"] = serde_json::to_value(&data).map_err(|e| e.to_string())?; diff --git a/crates/devtools/tests/asap_planner.rs b/crates/devtools/tests/asap_planner.rs index ebb0dac08..c2606f96b 100644 --- a/crates/devtools/tests/asap_planner.rs +++ b/crates/devtools/tests/asap_planner.rs @@ -1505,7 +1505,8 @@ const DDSKETCH_ASSUMED_RANGE_WARNING: &str = "assumed data fact: source m declar /// A selected DDSketch over a column that declares no `column_magnitudes` /// is costed over an assumed range, and the plan output names that -/// assumption under `stage3_plan_selection.warnings` and in the text +/// assumption under `stage3_plan_selection.warnings` (and as a record +/// under `stage3_plan_selection.assumed_data_facts`) and in the text /// output, once. Declaring the range removes it. #[test] fn a_selected_ddsketch_over_undeclared_magnitudes_is_warned_about() { @@ -1528,6 +1529,12 @@ fn a_selected_ddsketch_over_undeclared_magnitudes_is_warned_about() { selection["warnings"], json!([DDSKETCH_ASSUMED_RANGE_WARNING]) ); + assert_eq!( + selection["assumed_data_facts"], + json!([{"sources": ["m"], "assumption": {"ddsketch_value_magnitude_range": { + "column": "value", "assumed_range": {"min_abs": 1.0, "max_abs": 1e9} + }}}]) + ); let file = TempFile::json(&relative_quantile_over(None)); let mut text_args = vec!["--workload", file.path()]; text_args.extend_from_slice(&args); @@ -1546,6 +1553,9 @@ fn a_selected_ddsketch_over_undeclared_magnitudes_is_warned_about() { ); assert!(selects_a_plan(&declared["stage3_plan_selection"])); assert!(declared["stage3_plan_selection"].get("warnings").is_none()); + assert!(declared["stage3_plan_selection"] + .get("assumed_data_facts") + .is_none()); } /// `sum by (job) (rate(http_requests_total[1m]))` every minute over @@ -1579,14 +1589,15 @@ fn repeating_rate_over_ingesting(max_out_of_order_ms: Option) -> Value { /// `http_requests_total` carries when the arrival declares no /// `max_out_of_order_ms`. const IN_ORDER_ARRIVAL_WARNING: &str = "assumed data fact: the data arrival declares no \ - max_out_of_order_ms, so the samples of source http_requests_total an ingestion-time rate, \ - increase or irate state folds are taken to arrive in timestamp order; the plan may not \ - meet its accuracy target if this does not hold"; + max_out_of_order_ms, so the samples of source http_requests_total that an ingestion-time \ + rate, increase or irate state reads are taken to arrive in timestamp order; if this does \ + not hold, answers may be wrong by an amount no accuracy target bounds (a late sample can \ + be read as a counter reset), or ingestion may fail"; /// A deployment that keeps no raw data computes a repeating `rate` at /// ingestion time. Without a declared `max_out_of_order_ms` its samples are /// taken to arrive in order, which the exact answer depends on, so the plan -/// output warns that it may not meet its accuracy target. A declared bound +/// output warns that answers may be wrong beyond any accuracy target. A declared bound /// removes the warning and leaves the plan as it was. #[test] fn an_ingestion_time_rate_over_undeclared_arrival_order_is_warned_about() { @@ -1601,12 +1612,17 @@ fn an_ingestion_time_rate_over_undeclared_arrival_order_is_warned_about() { let selection = &undeclared["stage3_plan_selection"]; assert!(selects_a_plan(selection), "{selection}"); assert_eq!(selection["warnings"], json!([IN_ORDER_ARRIVAL_WARNING])); + assert_eq!( + selection["assumed_data_facts"], + json!([{"sources": ["http_requests_total"], "assumption": "in_order_arrival"}]) + ); let declared = document(&repeating_rate_over_ingesting(Some(5_000)), &args); let declared_selection = &declared["stage3_plan_selection"]; assert!( declared_selection.get("warnings").is_none(), "{declared_selection}" ); + assert!(declared_selection.get("assumed_data_facts").is_none()); assert_eq!( declared_selection["selected_dag"], selection["selected_dag"] diff --git a/crates/planner/src/installable/mod.rs b/crates/planner/src/installable/mod.rs index bd6b635b0..166f9ecad 100644 --- a/crates/planner/src/installable/mod.rs +++ b/crates/planner/src/installable/mod.rs @@ -74,7 +74,9 @@ pub struct SelectedPlanReport { /// against what it measures. pub predicted_usage: PredictedUsage, /// The data facts the data workload does not declare that the plan - /// assumed, each once ([`assumed_data_facts`]). + /// assumed, each once ([`assumed_data_facts`]); omitted when empty, and + /// empty in a report written without it. + #[serde(default, skip_serializing_if = "Vec::is_empty")] pub assumed_data_facts: Vec, } @@ -549,7 +551,6 @@ fn executor_refreshes( ) } -/// The report of the selected plan's `cost`. /// The data facts the selected `plan` (costed as `cost`) assumed because /// `data` does not declare them, each once: those its nodes' costs assumed /// ([`PlanCost::assumed_data_facts`]), then the in-order arrival Stage 2 @@ -570,6 +571,7 @@ pub fn assumed_data_facts( facts } +/// The report of the selected plan's `cost` and the data facts it assumed. fn report_of(cost: &PlanCost, assumed_data_facts: Vec) -> SelectedPlanReport { SelectedPlanReport { cost_per_second: cost.cost_per_second, diff --git a/crates/planner/tests/runtime_install.rs b/crates/planner/tests/runtime_install.rs index d340029e8..a795129a8 100644 --- a/crates/planner/tests/runtime_install.rs +++ b/crates/planner/tests/runtime_install.rs @@ -931,38 +931,60 @@ async fn sum_rate_at_10_hz_with_unknown_arrival_installs_and_answers() { /// A deployment that keeps no raw samples computes a repeating `rate` at /// ingestion time; the arrival declares no `max_out_of_order_ms`, so the /// samples are taken to arrive in order. The report beside the plan names -/// that assumed fact and that the accuracy target depends on it. +/// that assumed fact and that the accuracy target depends on it. Declaring +/// `max_out_of_order_ms` (5 s) removes the fact and leaves the plan as it +/// was; the report then serializes without the empty list, and a report +/// written without the field still reads. #[tokio::test] async fn the_report_names_the_data_facts_the_plan_assumed() { use asap_types::workload::{AssumedDataFact, DataFactAssumption}; - let workload: PlanningWorkload = serde_json::from_str( - r#"{"query_workload": {"language": "promql", "repeating_queries": [{ - "query": "sum(rate(requests_total[1m]))", - "demand": {"fixed_interval_at": {"interval": 60000, "evaluation_phase": 0}}, - "requirements": {}, - "predictability": {"predictable": {"known_at": null}}}]}, - "data_workload": {"arrival": {"ingesting": {"rows_per_second": 1000.0}}, - "sources": {"requests_total": {"series_count": 1000, "sample_interval": 1000, - "metric_type": "counter"}}}}"#, - ) - .unwrap(); + let workload = |max_out_of_order: &str| -> PlanningWorkload { + serde_json::from_str(&format!( + r#"{{"query_workload": {{"language": "promql", "repeating_queries": [{{ + "query": "sum(rate(requests_total[1m]))", + "demand": {{"fixed_interval_at": {{"interval": 60000, "evaluation_phase": 0}}}}, + "requirements": {{}}, + "predictability": {{"predictable": {{"known_at": null}}}}}}]}}, + "data_workload": {{"arrival": {{"ingesting": {{"rows_per_second": 1000.0{max_out_of_order}}}}}, + "sources": {{"requests_total": {{"series_count": 1000, "sample_interval": 1000, + "metric_type": "counter"}}}}}}}}"# + )) + .unwrap() + }; let capabilities = DeploymentCapabilities { raw_data_retained: false, ..DeploymentCapabilities::default() }; - let (_, report) = plan_with_report_for(workload, &capabilities).await; + let (plan, report) = plan_with_report_for(workload(""), &capabilities).await; let in_order = AssumedDataFact { sources: vec!["requests_total".into()], assumption: DataFactAssumption::InOrderArrival, }; assert_eq!(report.assumed_data_facts, vec![in_order.clone()]); assert!(in_order.accuracy_target_depends_on_it()); + let (declared_plan, declared) = + plan_with_report_for(workload(r#", "max_out_of_order_ms": 5000"#), &capabilities).await; + assert!(declared.assumed_data_facts.is_empty()); + assert_eq!( + declared_plan, plan, + "the declared bound leaves the plan as it was" + ); + let declared_json = serde_json::to_value(&declared).unwrap(); + assert!( + declared_json.get("assumed_data_facts").is_none(), + "{declared_json}" + ); + assert_eq!( + serde_json::from_value::(declared_json).unwrap(), + declared + ); } /// A repeating relative-error p99 over non-negative latencies on a /// deployment that keeps no raw samples is served by a DDSketch, whose /// `value` declares no `column_magnitudes`: the report names the assumed -/// range, which affects cost only. Declaring the range removes it. +/// range, which affects cost only. Declaring the range removes it, and the +/// plan is still a DDSketch. #[tokio::test] async fn the_report_names_a_ddsketch_s_assumed_magnitude_range() { use asap_types::workload::{AssumedDataFact, DataFactAssumption, ValueMagnitudeRange}; @@ -1002,10 +1024,16 @@ async fn the_report_names_a_ddsketch_s_assumed_magnitude_range() { }; assert_eq!(report.assumed_data_facts, vec![assumed.clone()]); assert!(!assumed.accuracy_target_depends_on_it()); - let (_, declared) = plan_with_report_for( + let (declared_plan, declared) = plan_with_report_for( workload(r#", "column_magnitudes": {"value": {"min_abs": 0.1, "max_abs": 100000.0}}"#), &capabilities, ) .await; + assert!( + serde_json::to_string(&declared_plan.dag) + .unwrap() + .contains("DDSketch"), + "still a DDSketch plan" + ); assert!(declared.assumed_data_facts.is_empty()); } diff --git a/crates/stage2-physical-optimization/src/candidate.rs b/crates/stage2-physical-optimization/src/candidate.rs index e841cb68a..86d658ebc 100644 --- a/crates/stage2-physical-optimization/src/candidate.rs +++ b/crates/stage2-physical-optimization/src/candidate.rs @@ -50,7 +50,7 @@ pub(super) struct OfferedPhysicalProperties { /// - `IngestionTime` only when `ingestion_time_offered_for_group` (the /// candidate's group is time-independent or an input of one) and, for a /// counter state, when its rows arrive in timestamp order or within a -/// known bound ([`counter_state_rows_ordered`]); +/// known bound ([`ingestion_row_order`] is not `Unordered`); /// - `AcrossEvaluations` only when `across_evaluations_offered_for_group` /// (a chain, a group on a known grid or a time-independent group, not /// read under an absolute `@ T`); @@ -72,7 +72,11 @@ pub(super) fn offered_physical_properties( let build = summary_build(operator); let ingestion_time_offered = ingestion_time_offered_for_group && build.is_none_or(|(summary_type, child)| { - counter_state_rows_ordered(memo, summary_type, child, data) + let scanned_sources = &memo.groups()[child.0 as usize] + .group_properties + .scanned_sources; + ingestion_row_order(summary_type, scanned_sources.iter(), data) + != IngestionRowOrder::Unordered }); let count_min_weights_not_proven_non_negative = build.is_some_and(|(summary_type, _)| { count_min_weights_not_proven_non_negative(memo, candidate.group, summary_type) @@ -145,80 +149,106 @@ fn summary_build(operator: &Operator) -> Option<(&FieldDataType, C)> } } -/// Whether a build of `summary_type` over group `child`, when it is a -/// counter state (`rate`, `increase`, `irate`), gets its rows in timestamp -/// order at ingestion time: the data declares how late a row may arrive -/// (`max_out_of_order_ms`), so a reorder buffer restores the order, or its -/// rows are PromQL samples, taken to arrive in order (an assumed data fact, -/// [`assumed_in_order_arrival`]). True for any other summary type. -fn counter_state_rows_ordered( - memo: &Memo, - summary_type: &FieldDataType, - child: MemoGroupId, - data: &DataWorkload, -) -> bool { - !is_counter_state(summary_type) - || data.arrival.max_out_of_order_ms().is_some() - || memo.groups()[child.0 as usize] - .group_properties - .scanned_sources - .iter() - .all(Source::is_time_series) +/// How an ingestion-time build of a summary state gets its rows in the +/// timestamp order it needs. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum IngestionRowOrder { + /// It needs no order (not a counter state), or the data declares how + /// late a row may arrive (`max_out_of_order_ms`), so a reorder buffer + /// restores the order. + Ordered, + /// A counter state over PromQL samples whose arrival declares no + /// `max_out_of_order_ms`: the samples are taken to arrive in timestamp + /// order, an assumed data fact ([`assumed_in_order_arrival`]). + AssumedOrdered, + /// A counter state over SQL rows whose arrival declares no + /// `max_out_of_order_ms`: nothing orders its rows, so it is not offered + /// at ingestion time. + Unordered, } -/// Whether a state of `summary_type` is a counter state (`rate`, -/// `increase`, `irate`), which reads a late sample as a counter reset. -fn is_counter_state(summary_type: &FieldDataType) -> bool { - matches!( +/// The row order an ingestion-time build of `summary_type` over rows of +/// `scanned_sources` gets: the one rule both the Stage 2 offer +/// ([`offered_physical_properties`]) and the report of what the selected +/// plan assumed ([`assumed_in_order_arrival`]) read. E.g. a `rate` state +/// over the PromQL metric `requests_total` with no `max_out_of_order_ms` +/// is `AssumedOrdered`; over an SQL table it is `Unordered`. +fn ingestion_row_order<'a>( + summary_type: &FieldDataType, + mut scanned_sources: impl Iterator, + data: &DataWorkload, +) -> IngestionRowOrder { + let counter_state = matches!( summary_type, FieldDataType::ExactAggregate(kind, _) if kind.tracks_counter_increase() - ) + ); + if !counter_state || data.arrival.max_out_of_order_ms().is_some() { + IngestionRowOrder::Ordered + } else if scanned_sources.all(Source::is_time_series) { + IngestionRowOrder::AssumedOrdered + } else { + IngestionRowOrder::Unordered + } } -/// The data fact `plan` assumed by [`counter_state_rows_ordered`]: when -/// the arrival declares no `max_out_of_order_ms`, each ingestion-time -/// counter state it builds was offered only because its PromQL samples are +/// The data fact `plan` assumed by [`ingestion_row_order`]: each +/// ingestion-time counter state it builds without a declared +/// `max_out_of_order_ms` was offered only because its PromQL samples are /// taken to arrive in timestamp order. One fact naming the metrics those /// states read, in name order; none when there is no such state. E.g. an /// ingestion-time `rate(requests_total[1m])` state gives `InOrderArrival` -/// over `requests_total`. +/// over `requests_total`. One walk from those states down to their scans, +/// O(nodes + edges); every such state in a selected plan was offered by +/// the same rule, so the sources they scan together are PromQL samples. pub fn assumed_in_order_arrival( plan: &PhysicalASAPDAG, data: &DataWorkload, ) -> Option { - if data.arrival.max_out_of_order_ms().is_some() { - return None; - } let nodes: HashMap = plan.nodes.iter().map(|node| (node.id, node)).collect(); - let mut metrics = BTreeSet::new(); + // The ingestion-time builds whose row order depends on the sources + // they scan (counter states with no declared `max_out_of_order_ms`, + // not `Ordered` whatever they scan), and the nodes below them. + let mut builds = Vec::new(); + let mut below = Vec::new(); for node in &plan.nodes { let Some((summary_type, _)) = summary_build(&node.payload) else { continue; }; - if node.output_state.timing != ExecutionTiming::IngestionTime - || !is_counter_state(summary_type) + if node.output_state.timing == ExecutionTiming::IngestionTime + && ingestion_row_order(summary_type, std::iter::empty(), data) + != IngestionRowOrder::Ordered { + builds.push(summary_type); + below.extend(node.producers()); + } + } + // The sources their samples come from: the scans below them. + let mut scanned_sources = BTreeSet::new(); + let mut seen = HashSet::new(); + while let Some(id) = below.pop() { + if !seen.insert(id) { continue; } - // The metrics its samples come from: the scans below it. - let mut below = node.producers(); - let mut seen = HashSet::new(); - while let Some(id) = below.pop() { - if !seen.insert(id) { - continue; - } - let producer = nodes[&id]; - match &producer.payload { - Operator::NonASAP(NonASAPOp::Scan { source, .. }) => { - metrics.insert(source_name(source).to_string()); - } - _ => below.extend(producer.producers()), + let producer = nodes[&id]; + match &producer.payload { + Operator::NonASAP(NonASAPOp::Scan { source, .. }) => { + scanned_sources.insert(source); } + _ => below.extend(producer.producers()), } } - (!metrics.is_empty()).then(|| AssumedDataFact { - sources: metrics.into_iter().collect(), + let assumed = builds.iter().any(|summary_type| { + ingestion_row_order(summary_type, scanned_sources.iter().copied(), data) + == IngestionRowOrder::AssumedOrdered + }); + assumed.then(|| AssumedDataFact { + sources: scanned_sources + .into_iter() + .map(|source| source_name(source).to_string()) + .collect::>() + .into_iter() + .collect(), assumption: DataFactAssumption::InOrderArrival, }) } diff --git a/crates/types/src/workload/assumed_data_fact.rs b/crates/types/src/workload/assumed_data_fact.rs index 97af6076d..5a20a41e0 100644 --- a/crates/types/src/workload/assumed_data_fact.rs +++ b/crates/types/src/workload/assumed_data_fact.rs @@ -19,7 +19,8 @@ use super::ValueMagnitudeRange; #[serde(deny_unknown_fields)] pub struct AssumedDataFact { /// The sources (PromQL metrics or SQL tables) the assumption is about, - /// those that do not declare the fact, in name order. + /// those that do not declare the fact, in name order; empty when the + /// state reads no source (the warning then names the data workload). pub sources: Vec, /// What was assumed in place of the undeclared fact. pub assumption: DataFactAssumption, @@ -43,15 +44,18 @@ pub enum DataFactAssumption { assumed_range: ValueMagnitudeRange, }, /// The data arrival declares no `max_out_of_order_ms`, so the PromQL - /// samples an ingestion-time `rate`, `increase` or `irate` state folds - /// are taken to arrive in timestamp order. A sample arriving late is - /// read as a counter reset, so the exact answer may be wrong. + /// samples an ingestion-time `rate`, `increase` or `irate` state reads + /// are taken to arrive in timestamp order. If one arrives late, answers + /// may be wrong by an amount no accuracy target bounds (read in arrival + /// order, a counter at 100 after 120 looks like a reset and adds 100 + /// to an `increase`), or ingestion may reject the sample and fail. InOrderArrival, } impl AssumedDataFact { - /// Whether the selected plan may miss a query's accuracy target when - /// the assumption does not hold; otherwise only its cost is assumed. + /// Whether the selected plan's answers may be wrong beyond its accuracy + /// target when the assumption does not hold; otherwise only its cost is + /// assumed. pub fn accuracy_target_depends_on_it(&self) -> bool { match self.assumption { DataFactAssumption::DDSketchValueMagnitudeRange { .. } => false, @@ -67,6 +71,7 @@ impl AssumedDataFact { impl fmt::Display for AssumedDataFact { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let sources = match self.sources.as_slice() { + [] => "the data workload".to_string(), [one] => format!("source {one}"), many => format!("sources {}", many.join(", ")), }; @@ -97,14 +102,15 @@ impl fmt::Display for AssumedDataFact { DataFactAssumption::InOrderArrival => write!( f, "the data arrival declares no max_out_of_order_ms, so the samples of {sources} \ - an ingestion-time rate, increase or irate state folds are taken to arrive in \ - timestamp order" + that an ingestion-time rate, increase or irate state reads are taken to arrive \ + in timestamp order" )?, } if self.accuracy_target_depends_on_it() { write!( f, - "; the plan may not meet its accuracy target if this does not hold" + "; if this does not hold, answers may be wrong by an amount no accuracy target \ + bounds (a late sample can be read as a counter reset), or ingestion may fail" ) } else { write!( @@ -115,20 +121,13 @@ impl fmt::Display for AssumedDataFact { } } -/// Adds `fact` to `facts` unless an equal one is there: a plan names each -/// assumption once, however many of its nodes rest on it. -pub fn add_assumed_data_fact(facts: &mut Vec, fact: AssumedDataFact) { - if !facts.contains(&fact) { - facts.push(fact); - } -} - #[cfg(test)] mod tests { use super::*; - /// One source is named alone, several in a list; an accuracy-affecting - /// assumption says the plan may miss its target. + /// One source is named alone, several in a list, none as the data + /// workload; an accuracy-affecting assumption says answers may be wrong + /// beyond any accuracy target. #[test] fn the_warning_names_the_sources_the_default_and_the_accuracy_effect() { let ddsketch = AssumedDataFact { @@ -171,13 +170,27 @@ mod tests { assert_eq!( in_order.to_string(), "assumed data fact: the data arrival declares no max_out_of_order_ms, so the \ - samples of sources a_total, b_total an ingestion-time rate, increase or irate \ - state folds are taken to arrive in timestamp order; the plan may not meet its \ - accuracy target if this does not hold" + samples of sources a_total, b_total that an ingestion-time rate, increase or irate \ + state reads are taken to arrive in timestamp order; if this does not hold, answers \ + may be wrong by an amount no accuracy target bounds (a late sample can be read as \ + a counter reset), or ingestion may fail" + ); + // A state whose producer scans no source names the data workload. + let no_source = AssumedDataFact { + sources: vec![], + assumption: DataFactAssumption::DDSketchValueMagnitudeRange { + column: None, + assumed_range: ValueMagnitudeRange { + min_abs: 1.0, + max_abs: 1e9, + }, + }, + }; + assert_eq!( + no_source.to_string(), + "assumed data fact: a DDSketch state folds values computed from the data workload, \ + whose magnitudes no source declares, so it is costed for magnitudes in \ + [1, 1000000000]; this affects cost only, the accuracy guarantee does not depend on it" ); - let mut facts = vec![]; - add_assumed_data_fact(&mut facts, in_order.clone()); - add_assumed_data_fact(&mut facts, in_order); - assert_eq!(facts.len(), 1); } } diff --git a/crates/types/src/workload/mod.rs b/crates/types/src/workload/mod.rs index 703ac68fe..cdc4d6eb7 100644 --- a/crates/types/src/workload/mod.rs +++ b/crates/types/src/workload/mod.rs @@ -11,7 +11,7 @@ pub mod parsed_workload; mod planning; mod query; -pub use assumed_data_fact::{add_assumed_data_fact, AssumedDataFact, DataFactAssumption}; +pub use assumed_data_fact::{AssumedDataFact, DataFactAssumption}; pub(crate) use data::series_facts; pub use data::{ DataArrival, DataWorkload, LabelSetDistinctValues, PrometheusMetricType, Rate, SourceFacts, From 4830776705ef24e8a46b866e20d06bf9694d2968 Mon Sep 17 00:00:00 2001 From: zzylol <50204836+zzylol@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:16:51 +0000 Subject: [PATCH 3/3] fix(cost): rebase onto the measured DDSketch state-bytes model The DDSketch's column range now comes from its declared column_magnitudes, else from assumed_magnitude_range, the one place the default range is applied; the assumed-range fact is still emitted for each DDSketch build that uses it. A test producer fills the new ProducerOutput fields. --- crates/cost/src/node/usage/mod.rs | 4 ++-- crates/cost/src/node/usage/tests.rs | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/crates/cost/src/node/usage/mod.rs b/crates/cost/src/node/usage/mod.rs index 81566ca23..768e7d8b1 100644 --- a/crates/cost/src/node/usage/mod.rs +++ b/crates/cost/src/node/usage/mod.rs @@ -34,8 +34,8 @@ use crate::node::operator_statistics::{ EdgeStatistics, OperatorStatistics, PartitionStatistics, UnaryEdgeStatistics, }; use crate::node::state_bytes::{ - assumed_magnitude_range, keeps_every_value, row_bytes, sketch_state_bytes, - state_bytes_per_row, state_row_bytes_beside_state, summary_state_bytes, StateInputRows, + assumed_magnitude_range, keeps_every_value, row_bytes, sketch_state_bytes, state_bytes_per_row, + state_row_bytes_beside_state, summary_state_bytes, StateInputRows, }; use crate::{aggregate_lookup, lookup, StateFamily}; use crate::{ diff --git a/crates/cost/src/node/usage/tests.rs b/crates/cost/src/node/usage/tests.rs index d6d1f2a2c..7281680d3 100644 --- a/crates/cost/src/node/usage/tests.rs +++ b/crates/cost/src/node/usage/tests.rs @@ -1770,6 +1770,8 @@ fn ddsketch_assumed_facts_over_sources( unchanged_columns: BTreeSet::from(["ts", "value"]), tumbling_windows: 1, chain_tumbling_window_width_ms: None, + state_input_rows: None, + raw_rows_span_ms: None, }; let settings = CostInputs::default(); node_resource_usage_and_cost(&build, &[producer_output], (1, 1.0), None, data, &settings)