Skip to content

Commit 7d85901

Browse files
committed
feat(index): expose coarse ANN execution timings
1 parent c4d5017 commit 7d85901

7 files changed

Lines changed: 265 additions & 25 deletions

File tree

‎rust/lance-datafusion/src/exec.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -512,6 +512,9 @@ pub struct ExecutionSummaryCounts {
512512
/// that construct or destructure it. Prefer the typed accessors below.
513513
pub all_counts: HashMap<String, usize>,
514514
/// Additional time metrics for more detailed statistics, stored in nanoseconds.
515+
/// Operator baseline times use `<ExecutionPlan::name()>_elapsed_compute` keys.
516+
/// Timings may be nested and accumulate across concurrent work; they are not
517+
/// exclusive stages that can be added to recover query wall time.
515518
/// These are subject to change in the future and should only be used for debugging purposes.
516519
pub all_times: HashMap<String, usize>,
517520
}
@@ -614,6 +617,14 @@ pub fn collect_execution_metrics(node: &dyn ExecutionPlan, counts: &mut Executio
614617
.or_insert(0);
615618
*existing += time.value();
616619
}
620+
// Keep operator baselines separate: ANN elapsed time includes asynchronous waits,
621+
// while operators such as SortExec report compute time. Summing them hides the stages.
622+
if let Some(elapsed) = metrics.elapsed_compute() {
623+
*counts
624+
.all_times
625+
.entry(format!("{}_elapsed_compute", node.name()))
626+
.or_default() += elapsed;
627+
}
617628
// Include gauge-based I/O metrics (some nodes record I/O as gauges)
618629
for (metric_name, gauge) in metrics.iter_gauges() {
619630
match metric_name.as_ref() {

‎rust/lance-index-core/src/metrics.rs‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,86 @@
22
// SPDX-FileCopyrightText: Copyright The Lance Authors
33

44
use std::sync::atomic::{AtomicUsize, Ordering};
5+
use std::time::{Duration, Instant};
6+
7+
/// Coarse ANN stage timings. Durations are cumulative wall times, including waits.
8+
/// Nested stages and concurrent partitions overlap; these are not additive query latency.
9+
#[derive(Clone, Copy, Debug)]
10+
#[repr(usize)]
11+
pub enum IndexTiming {
12+
/// Cache lookup, cache-fill wait, and loading/decoding a partition on a miss.
13+
PartitionLoad,
14+
/// Partition loading and per-partition filter preparation, including overlapping waits.
15+
PartitionPrepare,
16+
/// Time waiting until the shared filter is ready; not filter construction CPU time.
17+
PrefilterWait,
18+
/// Delay between submitting a search task and starting its CPU closure.
19+
CpuQueueWait,
20+
/// CPU search of a prepared partition, including query preparation and result construction.
21+
Search,
22+
/// Distance calculator and lookup-table construction for a partition query.
23+
QueryPrepare,
24+
/// Fused candidate filtering, distance evaluation, and TopK heap updates.
25+
DistanceTopK,
26+
/// Conversion of a result heap into Arrow arrays and a record batch.
27+
ResultMaterialize,
28+
/// Opening an index handle, including cache lookup and metadata reads.
29+
IndexOpen,
30+
}
31+
32+
impl IndexTiming {
33+
/// All stages in discriminant order, for fixed-size metric storage.
34+
pub const ALL: [Self; 9] = [
35+
Self::PartitionLoad,
36+
Self::PartitionPrepare,
37+
Self::PrefilterWait,
38+
Self::CpuQueueWait,
39+
Self::Search,
40+
Self::QueryPrepare,
41+
Self::DistanceTopK,
42+
Self::ResultMaterialize,
43+
Self::IndexOpen,
44+
];
45+
46+
/// Key used in execution summaries and language-binding statistics.
47+
pub fn name(self) -> &'static str {
48+
match self {
49+
Self::PartitionLoad => "index_partition_load_time",
50+
Self::PartitionPrepare => "index_partition_prepare_time",
51+
Self::PrefilterWait => "index_prefilter_wait_time",
52+
Self::CpuQueueWait => "index_cpu_queue_wait_time",
53+
Self::Search => "index_search_time",
54+
Self::QueryPrepare => "index_query_prepare_time",
55+
Self::DistanceTopK => "index_distance_topk_time",
56+
Self::ResultMaterialize => "index_result_materialize_time",
57+
Self::IndexOpen => "index_open_time",
58+
}
59+
}
60+
}
61+
62+
/// Records one partition/batch stage, never one candidate or distance evaluation.
63+
pub struct IndexTimer<'a> {
64+
metrics: &'a dyn MetricsCollector,
65+
stage: IndexTiming,
66+
start: Instant,
67+
}
68+
69+
impl<'a> IndexTimer<'a> {
70+
/// Start a scope timer; dropping it also records early-return and cancellation paths.
71+
pub fn new(metrics: &'a dyn MetricsCollector, stage: IndexTiming) -> Self {
72+
Self {
73+
metrics,
74+
stage,
75+
start: Instant::now(),
76+
}
77+
}
78+
}
79+
80+
impl Drop for IndexTimer<'_> {
81+
fn drop(&mut self) {
82+
self.metrics.record_timing(self.stage, self.start.elapsed());
83+
}
84+
}
585

686
/// A trait used by the index to report metrics
787
///
@@ -10,6 +90,9 @@ use std::sync::atomic::{AtomicUsize, Ordering};
1090
/// window events here. Benchmark-only instrumentation belongs in test- or
1191
/// benchmark-local hooks.
1292
pub trait MetricsCollector: Send + Sync {
93+
/// Record a coarse stage duration; existing collectors may ignore timings.
94+
fn record_timing(&self, _stage: IndexTiming, _duration: Duration) {}
95+
1396
/// Record partition loads
1497
///
1598
/// Many indices consist of partitions that may need to be loaded
@@ -128,6 +211,7 @@ impl MetricsCollector for NoOpMetricsCollector {
128211

129212
#[derive(Default)]
130213
pub struct LocalMetricsCollector {
214+
timings: [AtomicUsize; IndexTiming::ALL.len()],
131215
pub parts_loaded: AtomicUsize,
132216
pub index_loads: AtomicUsize,
133217
pub comparisons: AtomicUsize,
@@ -144,6 +228,12 @@ pub struct LocalMetricsCollector {
144228

145229
impl LocalMetricsCollector {
146230
pub fn dump_into(self, other: &dyn MetricsCollector) {
231+
for stage in IndexTiming::ALL {
232+
other.record_timing(
233+
stage,
234+
Duration::from_nanos(self.timings[stage as usize].load(Ordering::Relaxed) as u64),
235+
);
236+
}
147237
other.record_parts_loaded(self.parts_loaded.load(Ordering::Relaxed));
148238
other.record_index_loads(self.index_loads.load(Ordering::Relaxed));
149239
other.record_comparisons(self.comparisons.load(Ordering::Relaxed));
@@ -175,6 +265,10 @@ impl LocalMetricsCollector {
175265
}
176266

177267
impl MetricsCollector for LocalMetricsCollector {
268+
fn record_timing(&self, stage: IndexTiming, duration: Duration) {
269+
self.timings[stage as usize].fetch_add(duration.as_nanos() as usize, Ordering::Relaxed);
270+
}
271+
178272
fn record_parts_loaded(&self, num_parts: usize) {
179273
self.parts_loaded.fetch_add(num_parts, Ordering::Relaxed);
180274
}
@@ -281,6 +375,20 @@ mod tests {
281375
assert_eq!(sink.single_page_reads.load(Ordering::Relaxed), 4);
282376
}
283377

378+
#[test]
379+
fn local_metrics_collector_forwards_timings() {
380+
let local = LocalMetricsCollector::default();
381+
let sink = LocalMetricsCollector::default();
382+
for stage in IndexTiming::ALL {
383+
local.record_timing(stage, Duration::from_nanos(7));
384+
local.record_timing(stage, Duration::from_nanos(11));
385+
}
386+
local.dump_into(&sink);
387+
for stage in IndexTiming::ALL {
388+
assert_eq!(sink.timings[stage as usize].load(Ordering::Relaxed), 18);
389+
}
390+
}
391+
284392
#[test]
285393
fn no_op_metrics_collector_ignores_cache_counts() {
286394
// Ensures existing implementors that do not override cache-count methods

‎rust/lance-index/src/vector/flat/index.rs‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ use lance_linalg::distance::DistanceType;
1818
use serde::{Deserialize, Serialize};
1919

2020
use crate::{
21-
metrics::MetricsCollector,
21+
metrics::{IndexTimer, IndexTiming, MetricsCollector},
2222
prefilter::PreFilter,
2323
vector::{
2424
ApproxMode, DIST_COL, Query,
@@ -151,6 +151,7 @@ impl IvfSubIndex for FlatIndex {
151151
) -> Result<RecordBatch> {
152152
let is_range_query = params.lower_bound.is_some() || params.upper_bound.is_some();
153153
let row_ids = storage.row_ids();
154+
let query_timer = IndexTimer::new(metrics, IndexTiming::QueryPrepare);
154155
let dist_calc = storage.dist_calculator_with_scratch(
155156
query,
156157
params.dist_q_c,
@@ -160,8 +161,11 @@ impl IvfSubIndex for FlatIndex {
160161
approx_mode: params.approx_mode,
161162
},
162163
);
164+
drop(query_timer);
163165
let mut res = BinaryHeap::with_capacity(k);
164166
metrics.record_comparisons(storage.len());
167+
// Filtering, distance evaluation and heap updates are fused in fast-scan paths.
168+
let distance_timer = IndexTimer::new(metrics, IndexTiming::DistanceTopK);
165169

166170
match prefilter.is_empty() {
167171
// The calculator certifies that its top-k scan keeps every row the
@@ -238,6 +242,8 @@ impl IvfSubIndex for FlatIndex {
238242
}
239243
};
240244

245+
drop(distance_timer);
246+
let _result_timer = IndexTimer::new(metrics, IndexTiming::ResultMaterialize);
241247
// we don't need to sort the results by distances here
242248
// because there's a SortExec node in the query plan which sorts the results from all partitions
243249
let (row_ids, dists): (Vec<_>, Vec<_>) = res.into_iter().map(|r| (r.id, r.dist.0)).unzip();
@@ -290,6 +296,7 @@ impl IvfSubIndex for FlatIndex {
290296
metrics: &dyn MetricsCollector,
291297
) -> Result<()> {
292298
let row_ids = storage.row_ids();
299+
let query_timer = IndexTimer::new(metrics, IndexTiming::QueryPrepare);
293300
let dist_calc = storage.dist_calculator_with_scratch(
294301
query,
295302
params.dist_q_c,
@@ -299,7 +306,10 @@ impl IvfSubIndex for FlatIndex {
299306
approx_mode: params.approx_mode,
300307
},
301308
);
309+
drop(query_timer);
302310
metrics.record_comparisons(storage.len());
311+
// Filtering, distance evaluation and heap updates are fused in fast-scan paths.
312+
let distance_timer = IndexTimer::new(metrics, IndexTiming::DistanceTopK);
303313

304314
match prefilter.is_empty() {
305315
true => {
@@ -331,6 +341,7 @@ impl IvfSubIndex for FlatIndex {
331341
);
332342
}
333343
};
344+
drop(distance_timer);
334345
Ok(())
335346
}
336347

‎rust/lance/src/dataset/scanner.rs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18810,6 +18810,23 @@ full_filter=name LIKE Utf8(\"test%2\"), refine_filter=name LIKE Utf8(\"test%2\")
1881018810
.copied()
1881118811
.unwrap_or(0);
1881218812
assert_eq!(loads, if filtered || !segmented { 1 } else { 0 });
18813+
for name in [
18814+
"ANNSubIndexExec_elapsed_compute",
18815+
"index_open_time",
18816+
"index_partition_load_time",
18817+
"index_partition_prepare_time",
18818+
"index_cpu_queue_wait_time",
18819+
"index_search_time",
18820+
"index_query_prepare_time",
18821+
"index_distance_topk_time",
18822+
"index_result_materialize_time",
18823+
] {
18824+
assert!(
18825+
summary.all_times.get(name).is_some_and(|time| *time > 0),
18826+
"missing ANN stage timing: {name}: {:?}",
18827+
summary.all_times
18828+
);
18829+
}
1881318830
}
1881418831

1881518832
#[rstest]

0 commit comments

Comments
 (0)