22// SPDX-FileCopyrightText: Copyright The Lance Authors
33
44use 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.
1292pub 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 ) ]
130213pub 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
145229impl 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
177267impl 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
0 commit comments