1use parking_lot::Mutex;
10use std::sync::Arc;
11use uqa_core::{
12 io_usage::{IOContext, IOObservation, IOOptions, IOUsage},
13 memory::{Budgeted, BudgetedString, BudgetedVec, MemoryError, MemoryReservation},
14 vector_execution::VectorSearchOperation,
15 VectorGeneration,
16};
17use uqa_operators::vector::diagnostics::VectorSearchObserver;
18use uqa_sql::{
19 result::vector::{ExplainVectorSearch, ExplainVectorSearches},
20 SQLError,
21};
22use uqa_storage::{
23 read_control::StorageReadControl, vector_index::VectorQueryResult, StorageBackendError,
24 StorageBackendResult,
25};
26
27pub(crate) mod executions;
28pub(crate) mod io;
29mod scope;
30pub use scope::{CapturedScope, InvocationRequest, QueryDiagnostics, RequestScope};
31
32pub type CapturedDiagnostics = Arc<Budgeted<InvocationDiagnostics>>;
33
34pub type VectorDiagnostics = InvocationDiagnostics;
36
37struct Records {
38 searches: ExplainVectorSearches,
39 failed: Option<Failure>,
40 closed: bool,
41 executions: Option<executions::Executions>,
42}
43
44#[derive(Clone, Copy)]
45enum Failure {
46 Memory,
47 Cancelled,
48 Closed,
49 ExecutionMemory,
50 Measurement,
51}
52
53impl Failure {
54 fn error(self) -> SQLError {
55 match self {
56 Self::Cancelled => uqa_core::QueryCancelled::USER_REQUEST.into(),
57 Self::Memory => SQLError::Routine {
58 sqlstate: "53200".into(),
59 message: "EXPLAIN could not retain complete vector execution diagnostics".into(),
60 },
61 Self::Closed => SQLError::Internal("vector diagnostics scope is closed".into()),
62 Self::ExecutionMemory => SQLError::Routine {
63 sqlstate: "53200".into(),
64 message: "EXPLAIN could not retain complete native execution diagnostics".into(),
65 },
66 Self::Measurement => SQLError::Internal(
67 "EXPLAIN native execution measurements could not be completed".into(),
68 ),
69 }
70 }
71}
72
73pub struct InvocationDiagnostics {
75 control: StorageReadControl,
76 parent: Option<CapturedDiagnostics>,
77 io: Option<IOObservation>,
78 records: Mutex<Records>,
79}
80
81impl InvocationDiagnostics {
82 fn new(
83 control: StorageReadControl,
84 parent: Option<CapturedDiagnostics>,
85 timing: Option<bool>,
86 io_options: IOOptions,
87 io_timing: Arc<std::sync::atomic::AtomicBool>,
88 ) -> StorageBackendResult<CapturedDiagnostics> {
89 control.check()?;
90 let parent_io =
91 IOContext::for_observation(parent.as_ref().and_then(|parent| parent.io.as_ref()));
92 let io = if io_options.buffers || io_options.wal || parent_io.observation().is_some() {
93 Some(IOObservation::new(
94 control.memory(),
95 io_options,
96 io_timing,
97 parent_io.observation().cloned(),
98 )?)
99 } else {
100 None
101 };
102 let records = Mutex::new(Records {
103 searches: BudgetedVec::new(control.memory()),
104 failed: None,
105 closed: false,
106 executions: timing.map(|timing| executions::Executions::new(&control, timing)),
107 });
108 let memory = control.memory().empty_reservation();
109 Ok(Budgeted::new(
110 Self {
111 control,
112 parent,
113 io,
114 records,
115 },
116 memory,
117 )
118 .into_shared()?)
119 }
120
121 fn is_active(&self) -> bool {
122 !self.records.lock().closed
123 }
124
125 pub fn control(&self) -> &StorageReadControl {
126 &self.control
127 }
128
129 pub fn observer(
131 collector: &CapturedDiagnostics,
132 relation: &str,
133 ) -> StorageBackendResult<Arc<dyn VectorSearchObserver>> {
134 let mut name = BudgetedString::new(collector.control.memory());
135 name.push_str(relation)?;
136 let value = BoundObserver {
137 collector: Arc::clone(collector),
138 relation: name,
139 _memory: collector
140 .control
141 .memory()
142 .reserve(std::mem::size_of::<BoundObserver>())?,
143 };
144 Ok(Arc::new(value))
145 }
146
147 pub fn record(
148 &self,
149 relation: &str,
150 field: &str,
151 operation: VectorSearchOperation,
152 result: &VectorQueryResult,
153 ) -> StorageBackendResult<()> {
154 let Some(stats) = result.diskann else {
155 return Ok(());
156 };
157 let recorded = (|| {
158 self.control.check()?;
159 let mut relation_name = BudgetedString::new(self.control.memory());
160 relation_name.push_str(relation)?;
161 let mut field_name = BudgetedString::new(self.control.memory());
162 field_name.push_str(field)?;
163 let generation = stats.generation;
164 let record = ExplainVectorSearch {
165 relation: relation_name,
166 field: field_name,
167 operation,
168 returned_documents: u64::try_from(result.postings.len())
169 .map_err(|_| MemoryError::SizeOverflow)?,
170 generation: VectorGeneration {
171 database: generation.database(),
172 table: generation.table(),
173 index: generation.index(),
174 generation: generation.generation(),
175 },
176 route: stats.route,
177 traversal: stats.traversal,
178 work: stats.work,
179 };
180 let record =
181 Budgeted::new(record, self.control.memory().empty_reservation()).into_shared()?;
182 let mut current = Some(self);
183 while let Some(collector) = current {
184 collector.control.check()?;
185 let mut records = collector.records.lock();
186 if records.closed {
187 return Err(StorageBackendError::Other(
188 "vector diagnostics scope is closed".into(),
189 ));
190 }
191 records.searches.push(Arc::clone(&record))?;
192 current = collector.parent.as_ref().map(|parent| &***parent);
193 }
194 Ok(())
195 })();
196 if let Err(error) = &recorded {
197 let failure = match error {
198 StorageBackendError::Cancelled(_) => Failure::Cancelled,
199 StorageBackendError::Memory(_) => Failure::Memory,
200 _ => Failure::Closed,
201 };
202 let mut current = Some(self);
203 while let Some(collector) = current {
204 let mut records = collector.records.lock();
205 if records.closed {
206 break;
207 }
208 records.failed.get_or_insert(failure);
209 current = collector.parent.as_ref().map(|parent| &***parent);
210 }
211 }
212 recorded
213 }
214
215 fn finish(&self) -> Result<CapturedExecution, SQLError> {
216 let records = self.close();
217 self.control.cancellation().check()?;
218 if let Some(failure) = records.failed {
219 return Err(failure.error());
220 }
221 let nodes = records.executions.as_ref().map_or_else(
222 || Ok(BudgetedVec::new(self.control.memory())),
223 |nodes| nodes.snapshot(&self.control),
224 )?;
225 Ok(CapturedExecution {
226 io_timing: self.io.as_ref().is_some_and(IOObservation::timing_enabled),
227 io: self
228 .io
229 .as_ref()
230 .map_or(Ok(IOUsage::default()), IOObservation::finish)
231 .map_err(|_| Failure::Measurement.error())?,
232 vector_searches: records.searches,
233 nodes,
234 })
235 }
236
237 fn close(&self) -> Records {
239 let records = std::mem::replace(
240 &mut *self.records.lock(),
241 Records {
242 searches: BudgetedVec::new(self.control.memory()),
243 failed: None,
244 closed: true,
245 executions: None,
246 },
247 );
248 if let Some(io) = &self.io {
249 let _ = io.finish();
250 }
251 records
252 }
253}
254
255struct BoundObserver {
256 collector: CapturedDiagnostics,
257 relation: BudgetedString,
258 _memory: MemoryReservation,
259}
260
261impl VectorSearchObserver for BoundObserver {
262 fn control(&self) -> &StorageReadControl {
263 self.collector.control()
264 }
265 fn record(
266 &self,
267 field: &str,
268 operation: VectorSearchOperation,
269 result: &VectorQueryResult,
270 ) -> StorageBackendResult<()> {
271 self.collector
272 .record(&self.relation, field, operation, result)
273 }
274}
275
276pub struct CapturedExecution {
277 pub io: IOUsage,
278 pub io_timing: bool,
279 pub vector_searches: ExplainVectorSearches,
280 pub nodes: BudgetedVec<uqa_sql::result::explain::ExplainNodeExecution>,
281}
282
283pub struct DiagnosticsScope {
285 _binding: CapturedScope,
286 collector: CapturedDiagnostics,
287}
288
289impl DiagnosticsScope {
290 pub fn finish_execution(self) -> Result<CapturedExecution, SQLError> {
291 self.collector.finish()
292 }
293
294 pub fn finish(self) -> Result<ExplainVectorSearches, SQLError> {
295 Ok(self.collector.finish()?.vector_searches)
296 }
297}
298
299impl Drop for DiagnosticsScope {
300 fn drop(&mut self) {
301 drop(self.collector.close());
302 }
303}
304
305#[cfg(test)]
306mod io_tests;
307#[cfg(test)]
308mod tests;