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}