Skip to main content

qql_protocol/
telemetry.rs

1//! Phase-1 telemetry: client-side phase timings plus server `time`/`usage`
2//! extraction.
3//!
4//! Two halves, kept separate on purpose:
5//!
6//! - [`PhaseTimings`] — client stopwatches (`std::time::Instant`, no new
7//!   dependencies; `qql-runtime` has no `tracing` infra to reuse) around the
8//!   existing execute path. Millisecond floats.
9//! - [`ServerTelemetry`] — Qdrant's `time` (server seconds, float) plus the
10//!   hardware/inference `usage` object. REST extracts both leniently from the
11//!   JSON envelope (`{result, status, time, usage}` per `openapi.json`);
12//!   gRPC converts the proto `Usage` straight into [`ServerUsage`]. Anything
13//!   absent or misshapen becomes `None` — missing telemetry never fails a
14//!   query.
15
16use std::collections::HashMap;
17
18use serde::{Deserialize, Serialize};
19
20/// Qdrant hardware counters (`HardwareUsage`: seven uint fields).
21///
22/// Field-level `#[serde(default)]` keeps parsing total: a counter the server
23/// omits reads as zero rather than voiding the whole struct. A structurally
24/// wrong `hardware` value (non-object, float counters) still voids just this
25/// section — see [`ServerTelemetry::from_envelope`].
26#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
27pub struct HardwareUsage {
28    /// Raw CPU cycles (or abstract units) spent processing the request.
29    #[serde(default)]
30    pub cpu: u64,
31    /// Payload bytes read from disk.
32    #[serde(default)]
33    pub payload_io_read: u64,
34    /// Payload bytes written to disk.
35    #[serde(default)]
36    pub payload_io_write: u64,
37    /// Payload-index bytes read from disk.
38    #[serde(default)]
39    pub payload_index_io_read: u64,
40    /// Payload-index bytes written to disk.
41    #[serde(default)]
42    pub payload_index_io_write: u64,
43    /// Vector bytes read from disk.
44    #[serde(default)]
45    pub vector_io_read: u64,
46    /// Vector bytes written to disk.
47    #[serde(default)]
48    pub vector_io_write: u64,
49}
50
51impl HardwareUsage {
52    /// Element-wise sum (saturating) for report-level totals.
53    pub fn saturating_add(&self, other: &Self) -> Self {
54        Self {
55            cpu: self.cpu.saturating_add(other.cpu),
56            payload_io_read: self.payload_io_read.saturating_add(other.payload_io_read),
57            payload_io_write: self.payload_io_write.saturating_add(other.payload_io_write),
58            payload_index_io_read: self
59                .payload_index_io_read
60                .saturating_add(other.payload_index_io_read),
61            payload_index_io_write: self
62                .payload_index_io_write
63                .saturating_add(other.payload_index_io_write),
64            vector_io_read: self.vector_io_read.saturating_add(other.vector_io_read),
65            vector_io_write: self.vector_io_write.saturating_add(other.vector_io_write),
66        }
67    }
68}
69
70/// Per-model inference token spend (`ModelUsage{tokens}`).
71#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
72pub struct ModelUsage {
73    /// Tokens processed for this model.
74    #[serde(default)]
75    pub tokens: u64,
76}
77
78/// Inference usage: token spend keyed by model name.
79#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
80pub struct InferenceUsage {
81    /// Token spend per model (`models` map; empty when the server sent none).
82    #[serde(default)]
83    pub models: HashMap<String, ModelUsage>,
84}
85
86/// The `usage` half of server telemetry: optional hardware counters plus
87/// optional per-model inference spend.
88#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
89pub struct ServerUsage {
90    /// Hardware counters, when the backend reported them.
91    #[serde(default, skip_serializing_if = "Option::is_none")]
92    pub hardware: Option<HardwareUsage>,
93    /// Per-model inference spend, when the backend reported it.
94    #[serde(default, skip_serializing_if = "Option::is_none")]
95    pub inference: Option<InferenceUsage>,
96}
97
98impl ServerUsage {
99    /// Lenient parse of a REST `usage` value (`null` / missing / misshapen →
100    /// `None`). Each section parses independently: a bad `hardware` section
101    /// does not void a good `inference` section.
102    pub fn from_json(value: &serde_json::Value) -> Option<Self> {
103        let obj = value.as_object()?;
104        let hardware = obj
105            .get("hardware")
106            .and_then(|h| serde_json::from_value(h.clone()).ok());
107        let inference = obj
108            .get("inference")
109            .and_then(|i| serde_json::from_value(i.clone()).ok());
110        if hardware.is_none() && inference.is_none() {
111            return None;
112        }
113        Some(Self {
114            hardware,
115            inference,
116        })
117    }
118
119    /// Merge two usage reports for report-level totals: counters summed
120    /// (saturating), per-model tokens summed.
121    pub fn merge(&self, other: &Self) -> Self {
122        let hardware = match (&self.hardware, &other.hardware) {
123            (Some(a), Some(b)) => Some(a.saturating_add(b)),
124            (Some(a), None) => Some(a.clone()),
125            (None, Some(b)) => Some(b.clone()),
126            (None, None) => None,
127        };
128        let inference = match (&self.inference, &other.inference) {
129            (Some(a), Some(b)) => {
130                let mut models = a.models.clone();
131                for (name, usage) in &b.models {
132                    models
133                        .entry(name.clone())
134                        .and_modify(|e: &mut ModelUsage| {
135                            e.tokens = e.tokens.saturating_add(usage.tokens);
136                        })
137                        .or_insert_with(|| usage.clone());
138                }
139                Some(InferenceUsage { models })
140            }
141            (Some(a), None) => Some(a.clone()),
142            (None, Some(b)) => Some(b.clone()),
143            (None, None) => None,
144        };
145        Self {
146            hardware,
147            inference,
148        }
149    }
150}
151
152/// Server telemetry for one response: Qdrant's `time` (seconds, float) plus
153/// the hardware/inference `usage` object. Both halves are optional — routes
154/// and transports that do not report them (batch items, collection DDL over
155/// gRPC, mocks) yield `None`.
156#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
157pub struct ServerTelemetry {
158    /// Seconds the server spent processing the request, when reported.
159    #[serde(default, skip_serializing_if = "Option::is_none")]
160    pub time_s: Option<f64>,
161    /// Hardware/inference usage, when reported.
162    #[serde(default, skip_serializing_if = "Option::is_none")]
163    pub usage: Option<ServerUsage>,
164}
165
166impl ServerTelemetry {
167    /// Extract from a backend response envelope. Lenient by contract: absent
168    /// or misshapen `time`/`usage` becomes `None`, never an error.
169    /// Telemetry only — the response data path stays strict
170    /// (`rest_response::parse_*` fail `QQL-BACKEND-ENVELOPE`).
171    pub fn from_envelope(value: &serde_json::Value) -> Self {
172        Self {
173            time_s: value.get("time").and_then(|t| t.as_f64()),
174            usage: value.get("usage").and_then(ServerUsage::from_json),
175        }
176    }
177
178    /// `None` when the envelope carried neither half (keeps
179    /// `ExecResponse.telemetry` exactly `None` where the backend sent
180    /// nothing); `Some` otherwise, even if only one half is present.
181    /// Telemetry only, never a data-path fallback.
182    pub fn from_envelope_opt(value: &serde_json::Value) -> Option<Self> {
183        let tel = Self::from_envelope(value);
184        if tel.time_s.is_none() && tel.usage.is_none() {
185            None
186        } else {
187            Some(tel)
188        }
189    }
190
191    /// Aggregate per-response telemetry into report-level totals: server
192    /// times summed (absent when no response reported one), usage merged.
193    /// `None` when there is nothing to aggregate.
194    pub fn aggregate<'a>(
195        items: impl Iterator<Item = &'a ServerTelemetry>,
196    ) -> Option<ServerTelemetry> {
197        let mut time_s: Option<f64> = None;
198        let mut usage: Option<ServerUsage> = None;
199        let mut any = false;
200        for item in items {
201            any = true;
202            if let Some(t) = item.time_s {
203                time_s = Some(time_s.unwrap_or(0.0) + t);
204            }
205            if let Some(u) = &item.usage {
206                usage = Some(match usage {
207                    Some(acc) => acc.merge(u),
208                    None => u.clone(),
209                });
210            }
211        }
212        if !any || (time_s.is_none() && usage.is_none()) {
213            return None;
214        }
215        Some(ServerTelemetry { time_s, usage })
216    }
217}
218
219/// Per-phase client timings for one analyzed statement, in milliseconds.
220#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
221pub struct PhaseTimings {
222    /// Source parse (`Parser::parse`; `0.0` for pre-parsed `Stmt` input).
223    pub parse_ms: f64,
224    /// `prepare_statement` (schema `USING` resolution + embedding resolution)
225    /// plus `plan()`.
226    pub prepare_plan_ms: f64,
227    /// Backend round-trip (`QdrantOps::execute_planned`, incl. batch fan-out
228    /// where the executor batches).
229    pub dispatch_ms: f64,
230    /// Response decode + normalization into `ExecResponse`.
231    pub decode_ms: f64,
232    /// Wall-clock total for the analyzed statement.
233    pub total_ms: f64,
234}