icydb_core/db/executor/
trace.rs

1//! Executor query tracing boundary.
2//!
3//! Tracing is optional, injected by the caller, and must not affect execution semantics.
4
5use crate::{
6    db::query::plan::{AccessPath, AccessPlan, ExecutablePlan, PlanFingerprint},
7    error::{ErrorClass, ErrorOrigin, InternalError},
8    traits::EntityKind,
9};
10use sha2::{Digest, Sha256};
11
12///
13/// QueryTraceSink
14///
15
16pub trait QueryTraceSink: Send + Sync {
17    fn on_event(&self, event: QueryTraceEvent);
18}
19
20///
21/// TraceExecutorKind
22///
23
24#[derive(Clone, Copy, Debug, Eq, PartialEq)]
25pub enum TraceExecutorKind {
26    Load,
27    Save,
28    Delete,
29}
30
31///
32/// TraceAccess
33///
34
35#[derive(Clone, Copy, Debug, Eq, PartialEq)]
36pub enum TraceAccess {
37    ByKey,
38    ByKeys { count: u32 },
39    KeyRange,
40    IndexPrefix { name: &'static str, prefix_len: u32 },
41    FullScan,
42    Union { branches: u32 },
43    Intersection { branches: u32 },
44}
45
46///
47/// TracePhase
48///
49
50#[derive(Clone, Copy, Debug, Eq, PartialEq)]
51pub enum TracePhase {
52    Access,
53    PostAccess,
54}
55
56///
57/// QueryTraceEvent
58///
59
60#[derive(Clone, Copy, Debug, Eq, PartialEq)]
61pub enum QueryTraceEvent {
62    Start {
63        fingerprint: PlanFingerprint,
64        executor: TraceExecutorKind,
65        access: Option<TraceAccess>,
66    },
67    Phase {
68        fingerprint: PlanFingerprint,
69        executor: TraceExecutorKind,
70        access: Option<TraceAccess>,
71        phase: TracePhase,
72        rows: u64,
73    },
74    Finish {
75        fingerprint: PlanFingerprint,
76        executor: TraceExecutorKind,
77        access: Option<TraceAccess>,
78        rows: u64,
79    },
80    Error {
81        fingerprint: PlanFingerprint,
82        executor: TraceExecutorKind,
83        access: Option<TraceAccess>,
84        class: ErrorClass,
85        origin: ErrorOrigin,
86    },
87}
88
89///
90/// TraceScope
91///
92
93pub struct TraceScope {
94    sink: &'static dyn QueryTraceSink,
95    fingerprint: PlanFingerprint,
96    executor: TraceExecutorKind,
97    access: Option<TraceAccess>,
98}
99
100impl TraceScope {
101    fn new(
102        sink: &'static dyn QueryTraceSink,
103        fingerprint: PlanFingerprint,
104        executor: TraceExecutorKind,
105        access: Option<TraceAccess>,
106    ) -> Self {
107        sink.on_event(QueryTraceEvent::Start {
108            fingerprint,
109            executor,
110            access,
111        });
112        Self {
113            sink,
114            fingerprint,
115            executor,
116            access,
117        }
118    }
119
120    pub(crate) fn finish(self, rows: u64) {
121        self.sink.on_event(QueryTraceEvent::Finish {
122            fingerprint: self.fingerprint,
123            executor: self.executor,
124            access: self.access,
125            rows,
126        });
127    }
128
129    pub(crate) fn phase(&self, phase: TracePhase, rows: u64) {
130        self.sink.on_event(QueryTraceEvent::Phase {
131            fingerprint: self.fingerprint,
132            executor: self.executor,
133            access: self.access,
134            phase,
135            rows,
136        });
137    }
138
139    pub(crate) fn error(self, err: &InternalError) {
140        self.sink.on_event(QueryTraceEvent::Error {
141            fingerprint: self.fingerprint,
142            executor: self.executor,
143            access: self.access,
144            class: err.class,
145            origin: err.origin,
146        });
147    }
148}
149
150pub fn start_plan_trace<E: EntityKind>(
151    sink: Option<&'static dyn QueryTraceSink>,
152    executor: TraceExecutorKind,
153    plan: &ExecutablePlan<E>,
154) -> Option<TraceScope> {
155    let sink = sink?;
156    let access = Some(trace_access_from_plan(plan.access()));
157    let fingerprint = plan.fingerprint();
158    Some(TraceScope::new(sink, fingerprint, executor, access))
159}
160
161pub fn start_exec_trace(
162    sink: Option<&'static dyn QueryTraceSink>,
163    executor: TraceExecutorKind,
164    entity_path: &'static str,
165    access: Option<TraceAccess>,
166    detail: Option<&'static str>,
167) -> Option<TraceScope> {
168    let sink = sink?;
169    let fingerprint = exec_fingerprint(executor, entity_path, detail);
170    Some(TraceScope::new(sink, fingerprint, executor, access))
171}
172
173fn trace_access_from_plan<K>(plan: &AccessPlan<K>) -> TraceAccess {
174    match plan {
175        AccessPlan::Path(path) => trace_access_from_path(path),
176        AccessPlan::Union(children) => {
177            // NOTE: Diagnostics are best-effort; overflow saturates to preserve determinism.
178            TraceAccess::Union {
179                branches: u32::try_from(children.len()).unwrap_or(u32::MAX),
180            }
181        }
182        AccessPlan::Intersection(children) => {
183            // NOTE: Diagnostics are best-effort; overflow saturates to preserve determinism.
184            TraceAccess::Intersection {
185                branches: u32::try_from(children.len()).unwrap_or(u32::MAX),
186            }
187        }
188    }
189}
190
191fn trace_access_from_path<K>(path: &AccessPath<K>) -> TraceAccess {
192    match path {
193        AccessPath::ByKey(_) => TraceAccess::ByKey,
194        AccessPath::ByKeys(keys) => {
195            // NOTE: Diagnostics are best-effort; overflow saturates to preserve determinism.
196            TraceAccess::ByKeys {
197                count: u32::try_from(keys.len()).unwrap_or(u32::MAX),
198            }
199        }
200        AccessPath::KeyRange { .. } => TraceAccess::KeyRange,
201        AccessPath::IndexPrefix { index, values } => {
202            // NOTE: Diagnostics are best-effort; overflow saturates to preserve determinism.
203            TraceAccess::IndexPrefix {
204                name: index.name,
205                prefix_len: u32::try_from(values.len()).unwrap_or(u32::MAX),
206            }
207        }
208        AccessPath::FullScan => TraceAccess::FullScan,
209    }
210}
211
212fn exec_fingerprint(
213    executor: TraceExecutorKind,
214    entity_path: &'static str,
215    detail: Option<&'static str>,
216) -> PlanFingerprint {
217    let mut hasher = Sha256::new();
218    hasher.update(b"execfp:v1");
219    hasher.update([executor_tag(executor)]);
220    write_str(&mut hasher, entity_path);
221    match detail {
222        Some(detail) => {
223            hasher.update([1u8]);
224            write_str(&mut hasher, detail);
225        }
226        None => {
227            hasher.update([0u8]);
228        }
229    }
230    let digest = hasher.finalize();
231    let mut out = [0u8; 32];
232    out.copy_from_slice(&digest);
233    PlanFingerprint::from_bytes(out)
234}
235
236const fn executor_tag(executor: TraceExecutorKind) -> u8 {
237    match executor {
238        TraceExecutorKind::Load => 0x01,
239        TraceExecutorKind::Save => 0x02,
240        TraceExecutorKind::Delete => 0x03,
241    }
242}
243
244fn write_str(hasher: &mut Sha256, value: &str) {
245    // NOTE: Diagnostics-only fingerprinting saturates on overflow to avoid panics.
246    let len = u32::try_from(value.len()).unwrap_or(u32::MAX);
247    hasher.update(len.to_be_bytes());
248    hasher.update(value.as_bytes());
249}
icydb_core/db/executor/trace.rs

icydb_core/db/executor/
trace.rs
