query_runtime/observability/
cache_fill_event.rs

1//! Structured completion events for asynchronous lakehouse cache fills.
2
3use std::time::Duration;
4
5/// Structured outcome for an asynchronous lakehouse cache fill.
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
7pub enum LakehouseCacheFillOutcome {
8    /// The complete object was written to the local lakehouse cache.
9    Completed,
10    /// The background fill failed after it was accepted for execution.
11    Failed,
12    /// The fill gave up its cache write because the byte budget could not
13    /// cover its growth. Growth never waits, so this outcome reports routine
14    /// saturation. The reader still gets its data.
15    Abandoned,
16}
17
18/// Error facts captured for a failed asynchronous lakehouse cache fill.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub struct LakehouseCacheFillErrorEvent {
21    #[doc(hidden)]
22    pub code: String,
23    #[doc(hidden)]
24    pub kind: String,
25    #[doc(hidden)]
26    pub status: String,
27    #[doc(hidden)]
28    pub operation: String,
29}
30
31/// Structured asynchronous lakehouse cache fill event.
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct LakehouseCacheFillEvent {
34    #[doc(hidden)]
35    pub outcome: LakehouseCacheFillOutcome,
36    #[doc(hidden)]
37    pub bytes: Option<u64>,
38    #[doc(hidden)]
39    pub elapsed: Duration,
40    #[doc(hidden)]
41    pub cache_path_hash: String,
42    #[doc(hidden)]
43    pub stable_id_hash: String,
44    #[doc(hidden)]
45    pub file_index: Option<usize>,
46    #[doc(hidden)]
47    pub chunk_index: Option<usize>,
48    #[doc(hidden)]
49    pub error: Option<LakehouseCacheFillErrorEvent>,
50}
51
52/// Credential-free snapshot of a background lakehouse cache-fill completion event.
53#[derive(Debug, Clone, PartialEq, Eq)]
54pub struct LakehouseCacheFillEventSnapshot {
55    /// Stable event outcome.
56    pub outcome: &'static str,
57    /// Complete-object bytes written for successful fills, when known.
58    pub bytes: Option<u64>,
59    /// Elapsed time from accepted background job start to completion/failure.
60    pub elapsed: Duration,
61    /// Stable hash of the local cache path.
62    pub cache_path_hash: String,
63    /// Stable hash of the source stable id.
64    pub stable_id_hash: String,
65    /// Source file index associated with the fill, when known.
66    pub file_index: Option<usize>,
67    /// Source chunk index associated with the fill, when known.
68    pub chunk_index: Option<usize>,
69    /// Stable native error code for failed fills, when present.
70    pub error_code: Option<String>,
71    /// Stable native error kind for failed fills, when present.
72    pub error_kind: Option<String>,
73    /// Stable native error status for failed fills, when present.
74    pub error_status: Option<String>,
75    /// Stable native error operation for failed fills, when present.
76    pub error_operation: Option<String>,
77}
78
79impl LakehouseCacheFillOutcome {
80    const fn as_str(self) -> &'static str {
81        match self {
82            Self::Completed => "completed",
83            Self::Failed => "failed",
84            Self::Abandoned => "abandoned",
85        }
86    }
87}
88
89impl From<&LakehouseCacheFillEvent> for LakehouseCacheFillEventSnapshot {
90    fn from(event: &LakehouseCacheFillEvent) -> Self {
91        Self {
92            outcome: event.outcome.as_str(),
93            bytes: event.bytes,
94            elapsed: event.elapsed,
95            cache_path_hash: event.cache_path_hash.clone(),
96            stable_id_hash: event.stable_id_hash.clone(),
97            file_index: event.file_index,
98            chunk_index: event.chunk_index,
99            error_code: event.error.as_ref().map(|error| error.code.clone()),
100            error_kind: event.error.as_ref().map(|error| error.kind.clone()),
101            error_status: event.error.as_ref().map(|error| error.status.clone()),
102            error_operation: event.error.as_ref().map(|error| error.operation.clone()),
103        }
104    }
105}
query_runtime/observability/cache_fill_event.rs

query_runtime/observability/
cache_fill_event.rs
