ktstr/scenario/sample/stats.rs
1//! Stats-JSON-axis projection for [`SampleSeries`].
2//!
3//! Each [`Sample`](super::Sample) carries an optional `scx_stats` JSON
4//! value captured from a scx_stats request issued just BEFORE the
5//! freeze rendezvous. This module exposes the closure-based
6//! [`SampleSeries::stats`] projection (manual path access via
7//! [`StatsValue`]) and the auto-discovering
8//! [`SampleSeries::stats_path`] → [`StatsPathProjector`] pair that
9//! walks a stats sub-tree, enumerates object keys, and projects each
10//! as `SeriesField<u64>` / `SeriesField<i64>` / `SeriesField<f64>`.
11//!
12//! Orthogonal to [`super::bpf`]: the stats axis sources its values
13//! from the userspace scheduler's `scx_stats` JSON; the BPF axis
14//! sources from kernel-side BPF state. Tests typically use both.
15//!
16//! ## Counter semantics are scheduler-defined (cumulative vs per-read delta)
17//!
18//! ktstr issues ONE fresh `scx_stats` request per periodic snapshot
19//! and stores the response verbatim — it never accumulates or diffs a
20//! field across snapshots. Whether a field is CUMULATIVE (monotonic
21//! since scheduler start) or a DELTA since the previous reader request
22//! is decided by the scheduler's stats implementation, not by ktstr.
23//! Some schedulers delta their metrics per reader request; because
24//! ktstr issues one request per snapshot, each sample of such a field
25//! is the change since the PREVIOUS snapshot, not a running total.
26//!
27//! This dictates the per-phase reduction. For a CUMULATIVE field the
28//! phase total is last − first
29//! ([`counter_delta_per_phase`](crate::assert::temporal::SeriesField::counter_delta_per_phase)).
30//! For a DELTA-per-request field that reduction is wrong — it diffs two
31//! deltas; the phase total is the SUM of the per-snapshot deltas in the
32//! phase. There is no built-in per-phase sum today, so group with
33//! [`by_stimulus_phase`](crate::scenario::sample::SampleSeries::by_stimulus_phase)
34//! and sum each phase's values by hand. Mind the boundary: a
35//! per-snapshot delta covers the interval since the previous snapshot,
36//! so the FIRST delta inside a phase spans the phase boundary and
37//! carries the tail of the prior phase. Know your scheduler's
38//! convention before choosing the reduction.
39
40use crate::assert::temporal::SeriesField;
41use crate::scenario::snapshot::{JsonField, SnapshotResult, stats_path};
42
43use super::{SampleSeries, build_series_field};
44
45impl SampleSeries {
46 /// Project the series along the stats axis. The closure
47 /// receives each sample's stats JSON (when present) and
48 /// returns a [`SnapshotResult<T>`]. Samples whose `stats` is
49 /// `Err(reason)` get a `Err(MissingStats { tag, reason })` slot —
50 /// temporal assertions surface that as a per-sample
51 /// missing-stats failure rather than vacuously skipping it,
52 /// so a coverage gap is never silent and the operator sees
53 /// the *why* (no scheduler binary configured, relay timed
54 /// out, scheduler returned errno, etc.).
55 ///
56 /// `label` is owned (`impl Into<String>`) and matches the
57 /// shape of [`Self::bpf`] — pass a literal or a runtime-built
58 /// `String` for auto-discovered keys.
59 pub fn stats<T, F>(&self, label: impl Into<String>, project: F) -> SeriesField<T>
60 where
61 F: Fn(StatsValue<'_>) -> SnapshotResult<T>,
62 {
63 build_series_field(&self.rows, label, |row| match row.stats.as_ref() {
64 Ok(v) => project(StatsValue { value: v }),
65 Err(reason) => Err(crate::scenario::snapshot::SnapshotError::MissingStats {
66 tag: row.tag.clone(),
67 reason: reason.clone(),
68 }),
69 })
70 }
71
72 /// Project the live scheduler's stats JSON field at `path` as
73 /// `u64`. Per-row equivalent of `series.stats(label, |s|
74 /// s.get(path).as_u64())` with the boilerplate elided. Mirrors
75 /// [`Self::bpf_live_u64`] for naming parity across axes.
76 ///
77 /// **Why "live" applies — per-request freshness, not a buffer.**
78 /// Each periodic snapshot issues a FRESH `scx_stats` request
79 /// just before the freeze rendezvous fires; the response in
80 /// `row.stats` came from whichever scheduler was alive at
81 /// request-issue time. There is no relay buffer of "the last
82 /// stats we saw" — a stale-pre-swap response cannot land in
83 /// a post-swap sample. After `Op::ReplaceScheduler` the host
84 /// reconnects to the new scheduler's `scx_stats` endpoint
85 /// before the next periodic boundary issues its request, so
86 /// post-swap samples carry the new scheduler's data. The
87 /// `_live` suffix matches the BPF axis naming for cross-axis
88 /// vocabulary consistency AND describes the actual freshness
89 /// guarantee — same semantic across both axes.
90 pub fn stats_live_u64(&self, path: &str) -> SeriesField<u64> {
91 let path_owned = path.to_string();
92 self.stats(path_owned.clone(), move |s| s.get(&path_owned).as_u64())
93 }
94
95 /// Sibling of [`Self::stats_live_u64`] projecting as `i64`.
96 pub fn stats_live_i64(&self, path: &str) -> SeriesField<i64> {
97 let path_owned = path.to_string();
98 self.stats(path_owned.clone(), move |s| s.get(&path_owned).as_i64())
99 }
100
101 /// Sibling of [`Self::stats_live_u64`] projecting as `f64`.
102 pub fn stats_live_f64(&self, path: &str) -> SeriesField<f64> {
103 let path_owned = path.to_string();
104 self.stats(path_owned.clone(), move |s| s.get(&path_owned).as_f64())
105 }
106
107 /// Auto-project a stats-JSON sub-tree. The returned
108 /// [`StatsPathProjector`] resolves the tree at sample 0 and
109 /// exposes object keys via `.key(name)` (for nested layer /
110 /// cgroup objects) or `.field(name)` (for scalar leaves).
111 /// `path` may be empty — `series.stats_path("")` projects from
112 /// the root and is the canonical entry for system-level stats
113 /// fields like `busy`, `antistall`, `system_cpu_util_ewma`,
114 /// etc.
115 pub fn stats_path<'a>(&'a self, path: &str) -> StatsPathProjector<'a> {
116 StatsPathProjector {
117 series: self,
118 path: path.to_string(),
119 }
120 }
121}
122
123/// Newtype carrier handed to the [`SampleSeries::stats`] closure.
124/// Wraps a borrowed [`serde_json::Value`] and exposes [`Self::get`]
125/// as a thin facade over [`stats_path`] so the closure body reads
126/// `s.get("layers.batch.util").as_f64()` without an explicit
127/// import. The `.get(path)` name mirrors
128/// [`crate::scenario::snapshot::SnapshotField::get`] and
129/// [`crate::scenario::snapshot::JsonField::get`] so test authors
130/// see one navigator vocabulary across every accessor surface.
131#[derive(Debug, Clone, Copy)]
132pub struct StatsValue<'a> {
133 value: &'a serde_json::Value,
134}
135
136impl<'a> StatsValue<'a> {
137 /// Underlying JSON value.
138 pub fn raw(&self) -> &'a serde_json::Value {
139 self.value
140 }
141
142 /// Walk along a dotted path. Empty path returns the root.
143 pub fn get(&self, path: &str) -> JsonField<'a> {
144 stats_path(self.value, path)
145 }
146}
147
148/// Auto-projector handle returned by [`SampleSeries::stats_path`].
149/// Walks a stats sub-tree per sample and exposes scalar / nested
150/// projections for the keys at that level.
151pub struct StatsPathProjector<'a> {
152 series: &'a SampleSeries,
153 path: String,
154}
155
156impl<'a> StatsPathProjector<'a> {
157 /// Project a JSON key under the resolved path as `u64`.
158 pub fn field_u64(&self, key: &str) -> SeriesField<u64> {
159 let full_path = join_paths(&self.path, key);
160 self.series
161 .stats(key, move |sv| sv.get(&full_path).as_u64())
162 }
163
164 /// Project a JSON key under the resolved path as `i64`.
165 pub fn field_i64(&self, key: &str) -> SeriesField<i64> {
166 let full_path = join_paths(&self.path, key);
167 self.series
168 .stats(key, move |sv| sv.get(&full_path).as_i64())
169 }
170
171 /// Project a JSON key under the resolved path as `f64`.
172 pub fn field_f64(&self, key: &str) -> SeriesField<f64> {
173 let full_path = join_paths(&self.path, key);
174 self.series
175 .stats(key, move |sv| sv.get(&full_path).as_f64())
176 }
177
178 /// Return a sub-projector rooted under `key`. Composable —
179 /// `series.stats_path("layers").key("batch").field_f64("util")`
180 /// drills into the per-layer scheduler stats one segment at a
181 /// time without each call site re-typing the full dotted
182 /// path.
183 pub fn key(&self, key: &str) -> StatsPathProjector<'a> {
184 StatsPathProjector {
185 series: self.series,
186 path: join_paths(&self.path, key),
187 }
188 }
189
190 /// Discover the JSON object keys of the resolved path, unioned across
191 /// ALL samples (sorted, deduplicated). Empty ONLY when no sample
192 /// resolves the path to an object.
193 ///
194 /// Discovery spans every row rather than sample 0 alone: a
195 /// scheduler-defined `scx_stats` object can be absent or `Err` in
196 /// sample 0 (the first capture often predates the scheduler's first
197 /// stats emit) while later samples carry it; reading only sample 0
198 /// would silently return no keys and blind a "assert over every
199 /// scx_stats counter" blanket projection.
200 pub fn key_names(&self) -> Vec<String> {
201 let mut names: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
202 for row in &self.series.rows {
203 let Ok(stats) = row.stats.as_ref() else {
204 continue;
205 };
206 let resolved = stats_path(stats, &self.path);
207 if let Some(serde_json::Value::Object(map)) = resolved.raw() {
208 names.extend(map.keys().cloned());
209 }
210 }
211 names.into_iter().collect()
212 }
213
214 /// Project every object key that resolves as `u64` for at
215 /// least one sample. Iterates [`Self::key_names`], calls
216 /// [`Self::field_u64`] for each, and keeps the entries whose
217 /// resulting [`SeriesField`] has at least one `Ok` value —
218 /// non-numeric leaves (strings, nested objects, floats) drop
219 /// out.
220 pub fn u64_fields(&self) -> Vec<(String, SeriesField<u64>)> {
221 self.key_names()
222 .into_iter()
223 .filter_map(|name| {
224 let field = self.field_u64(&name);
225 // Bind the predicate result and drop the
226 // values_iter borrow before moving `field`.
227 let any_ok = field.values_iter().any(|r| r.is_ok());
228 any_ok.then_some((name, field))
229 })
230 .collect()
231 }
232
233 /// Project every object key that resolves as `f64` for at
234 /// least one sample. Mirrors [`Self::u64_fields`] using
235 /// [`Self::field_f64`].
236 pub fn f64_fields(&self) -> Vec<(String, SeriesField<f64>)> {
237 self.key_names()
238 .into_iter()
239 .filter_map(|name| {
240 let field = self.field_f64(&name);
241 let any_ok = field.values_iter().any(|r| r.is_ok());
242 any_ok.then_some((name, field))
243 })
244 .collect()
245 }
246}
247
248fn join_paths(base: &str, leaf: &str) -> String {
249 if base.is_empty() {
250 leaf.to_string()
251 } else if leaf.is_empty() {
252 base.to_string()
253 } else {
254 format!("{base}.{leaf}")
255 }
256}
257
258#[cfg(test)]
259mod tests {
260 use super::*;
261 use crate::monitor::btf_render::{RenderedMember, RenderedValue};
262 use crate::monitor::dump::{FailureDumpMap, FailureDumpReport, SCHEMA_SINGLE};
263
264 fn synthetic_report(value: u64) -> FailureDumpReport {
265 let bss_value = RenderedValue::Struct {
266 type_name: Some(".bss".into()),
267 members: vec![
268 RenderedMember {
269 name: "nr_dispatched".into(),
270 value: RenderedValue::Uint { bits: 64, value },
271 },
272 RenderedMember {
273 name: "stall".into(),
274 value: RenderedValue::Uint { bits: 8, value: 0 },
275 },
276 ],
277 };
278 let bss_map = FailureDumpMap {
279 name: "scx_obj.bss".into(),
280 map_type: 2,
281 value_size: 16,
282 max_entries: 1,
283 value: Some(bss_value),
284 ..Default::default()
285 };
286 FailureDumpReport {
287 schema: SCHEMA_SINGLE.to_string(),
288 active_map_kvas: Vec::new(),
289 maps: vec![bss_map],
290 ..Default::default()
291 }
292 }
293
294 fn synthetic_stats(busy: f64) -> serde_json::Value {
295 serde_json::json!({
296 "busy": busy,
297 "antistall": 0,
298 "layers": {
299 "batch": { "util": busy * 0.5 }
300 }
301 })
302 }
303
304 /// Build stats payloads with mixed shapes so the
305 /// `StatsPathProjector` auto-projectors exercise the same
306 /// "at least one Ok" filter on the JSON axis:
307 /// - `busy`: Number — projects Ok as u64 and f64.
308 /// - `count`: Number — projects Ok as u64 and f64.
309 /// - `ratio`: Number(float) — projects Ok as f64;
310 /// u64 errors when the float has a non-zero
311 /// fraction (see `json_to_u64`).
312 /// - `name`: String("nope") — never coerces to numeric.
313 fn mixed_stats(busy: u64, count: u64) -> serde_json::Value {
314 serde_json::json!({
315 "busy": busy,
316 "count": count,
317 "ratio": 0.5,
318 "name": "nope",
319 })
320 }
321
322 #[test]
323 fn stats_projection_handles_missing_stats_as_error() {
324 use crate::scenario::snapshot::{DrainedSnapshotEntry, MissingStatsReason};
325 let drained = vec![
326 DrainedSnapshotEntry {
327 tag: "periodic_000".to_string(),
328 report: synthetic_report(10),
329 stats: Ok(synthetic_stats(50.0)),
330 elapsed_ms: Some(100),
331 boundary_offset_ms: None,
332 step_index: None,
333 },
334 DrainedSnapshotEntry {
335 tag: "periodic_001".to_string(),
336 report: synthetic_report(20),
337 stats: Err(MissingStatsReason::NoSchedulerBinary),
338 elapsed_ms: Some(200),
339 boundary_offset_ms: None,
340 step_index: None,
341 },
342 ];
343 let series = SampleSeries::from_drained_typed(drained, None);
344 let field: SeriesField<f64> = series.stats("busy", |s| s.get("busy").as_f64());
345 let outcomes: Vec<SnapshotResult<f64>> = field.values_iter().cloned().collect();
346 assert_eq!(outcomes.len(), 2);
347 assert_eq!(
348 outcomes[0].as_ref().copied(),
349 Ok(50.0),
350 "sample with stats present must project the `busy` field verbatim"
351 );
352 match &outcomes[1] {
353 Err(crate::scenario::snapshot::SnapshotError::MissingStats { tag, reason }) => {
354 assert_eq!(
355 tag, "periodic_001",
356 "MissingStats tag must identify the sample whose stats slot was Err"
357 );
358 assert_eq!(
359 reason,
360 &MissingStatsReason::NoSchedulerBinary,
361 "MissingStats reason must propagate the carried MissingStatsReason verbatim"
362 );
363 }
364 other => panic!(
365 "sample with stats=Err must surface SnapshotError::MissingStats, got {other:?}"
366 ),
367 }
368 }
369
370 #[test]
371 fn stats_path_projector_field_f64_extracts_root_scalar() {
372 let drained = vec![
373 (
374 "periodic_000".to_string(),
375 synthetic_report(0),
376 Some(synthetic_stats(50.0)),
377 Some(100),
378 ),
379 (
380 "periodic_001".to_string(),
381 synthetic_report(0),
382 Some(synthetic_stats(60.0)),
383 Some(200),
384 ),
385 ];
386 let series = SampleSeries::from_drained(drained, None);
387 let field = series.stats_path("").field_f64("busy");
388 let values: Vec<f64> = field
389 .values_iter()
390 .filter_map(|v| v.as_ref().ok().copied())
391 .collect();
392 assert_eq!(values.len(), 2);
393 assert!((values[0] - 50.0).abs() < f64::EPSILON);
394 assert!((values[1] - 60.0).abs() < f64::EPSILON);
395 }
396
397 #[test]
398 fn stats_path_projector_key_names_at_root() {
399 let drained = vec![(
400 "periodic_000".to_string(),
401 synthetic_report(0),
402 Some(synthetic_stats(50.0)),
403 Some(100),
404 )];
405 let series = SampleSeries::from_drained(drained, None);
406 let names = series.stats_path("").key_names();
407 assert!(names.contains(&"busy".to_string()));
408 assert!(names.contains(&"layers".to_string()));
409 }
410
411 #[test]
412 fn stats_path_projector_nested_key_drills_in() {
413 let drained = vec![(
414 "periodic_000".to_string(),
415 synthetic_report(0),
416 Some(synthetic_stats(50.0)),
417 Some(100),
418 )];
419 let series = SampleSeries::from_drained(drained, None);
420 // Note: drilling deeper than 2 levels via key() chain works
421 // because key() returns the same kind of projector.
422 let field = series.stats_path("layers").key("batch").field_f64("util");
423 let values: Vec<f64> = field
424 .values_iter()
425 .filter_map(|v| v.as_ref().ok().copied())
426 .collect();
427 assert_eq!(values.len(), 1);
428 assert!((values[0] - 25.0).abs() < f64::EPSILON);
429 }
430
431 /// `StatsPathProjector::u64_fields` keeps JSON keys whose
432 /// per-sample projection lands at least one Ok and drops keys
433 /// whose every projection errors. `busy` / `count` are integer
434 /// numbers (Ok u64); `ratio` is `0.5` and lands TypeMismatch
435 /// on every sample (`json_to_u64` rejects non-integer floats);
436 /// `name` is a string that does not parse — also Err.
437 #[test]
438 fn stats_path_projector_u64_fields_keeps_at_least_one_ok_excludes_all_err() {
439 let drained = vec![
440 (
441 "periodic_000".to_string(),
442 synthetic_report(0),
443 Some(mixed_stats(50, 7)),
444 Some(100),
445 ),
446 (
447 "periodic_001".to_string(),
448 synthetic_report(0),
449 Some(mixed_stats(60, 9)),
450 Some(200),
451 ),
452 ];
453 let series = SampleSeries::from_drained(drained, None);
454 let fields = series.stats_path("").u64_fields();
455 let names: Vec<&str> = fields.iter().map(|(n, _)| n.as_str()).collect();
456 assert!(
457 names.contains(&"busy"),
458 "Number(integer) key must be kept: {names:?}",
459 );
460 assert!(
461 names.contains(&"count"),
462 "Number(integer) key must be kept: {names:?}",
463 );
464 assert!(
465 !names.contains(&"ratio"),
466 "Number(non-integer float) errors on every u64 projection — must be excluded: {names:?}",
467 );
468 assert!(
469 !names.contains(&"name"),
470 "String key must be excluded — every u64 projection errors: {names:?}",
471 );
472 // Pin the projected VALUES, not just the kept names: the kept
473 // name is the bare key label, but the value resolves through
474 // join_paths(path, key) — a wrong-leaf or wrong-cast bug keeps
475 // the name while corrupting the value, which a name-only check
476 // misses (mirror of bpf.rs).
477 let busy = fields.iter().find(|(n, _)| n == "busy").expect("busy kept");
478 assert_eq!(
479 busy.1
480 .values_iter()
481 .filter_map(|r| r.as_ref().ok().copied())
482 .collect::<Vec<u64>>(),
483 vec![50u64, 60],
484 );
485 let count = fields
486 .iter()
487 .find(|(n, _)| n == "count")
488 .expect("count kept");
489 assert_eq!(
490 count
491 .1
492 .values_iter()
493 .filter_map(|r| r.as_ref().ok().copied())
494 .collect::<Vec<u64>>(),
495 vec![7u64, 9],
496 );
497 }
498
499 /// Mirror of the u64 test for `f64_fields`. `busy`, `count`,
500 /// and `ratio` all coerce to f64; only `name` errors. Pins the
501 /// "at least one Ok" filter for the f64 axis distinctly from
502 /// the u64 axis.
503 #[test]
504 fn stats_path_projector_f64_fields_keeps_at_least_one_ok_excludes_all_err() {
505 let drained = vec![
506 (
507 "periodic_000".to_string(),
508 synthetic_report(0),
509 Some(mixed_stats(50, 7)),
510 Some(100),
511 ),
512 (
513 "periodic_001".to_string(),
514 synthetic_report(0),
515 Some(mixed_stats(60, 9)),
516 Some(200),
517 ),
518 ];
519 let series = SampleSeries::from_drained(drained, None);
520 let fields = series.stats_path("").f64_fields();
521 let names: Vec<&str> = fields.iter().map(|(n, _)| n.as_str()).collect();
522 assert!(
523 names.contains(&"busy"),
524 "Number(integer) coerces to f64 — must be kept: {names:?}",
525 );
526 assert!(
527 names.contains(&"count"),
528 "Number(integer) coerces to f64 — must be kept: {names:?}",
529 );
530 assert!(
531 names.contains(&"ratio"),
532 "Number(non-integer float) coerces to f64 — must be kept: {names:?}",
533 );
534 assert!(
535 !names.contains(&"name"),
536 "String key must be excluded — every f64 projection errors: {names:?}",
537 );
538 // Pin the projected f64 VALUES. `count` (a second integer key)
539 // catches a wrong-leaf bug; `ratio` (the only non-integer
540 // fraction) catches a fraction-mangling bug — neither is value-
541 // checked elsewhere.
542 let getf = |n: &str| -> Vec<f64> {
543 fields
544 .iter()
545 .find(|(name, _)| name == n)
546 .unwrap_or_else(|| panic!("{n} kept"))
547 .1
548 .values_iter()
549 .filter_map(|r| r.as_ref().ok().copied())
550 .collect()
551 };
552 let approx = |got: Vec<f64>, want: &[f64]| {
553 assert_eq!(got.len(), want.len());
554 for (g, w) in got.iter().zip(want) {
555 assert!((g - w).abs() < f64::EPSILON, "got {got:?} want {want:?}");
556 }
557 };
558 approx(getf("busy"), &[50.0, 60.0]);
559 approx(getf("count"), &[7.0, 9.0]);
560 approx(getf("ratio"), &[0.5, 0.5]);
561 }
562
563 /// Empty series — no rows to discover JSON keys from, so
564 /// `key_names()` returns an empty vec and both auto-projectors
565 /// yield empty results without panicking. Pins the "no first
566 /// row" branch in `StatsPathProjector::key_names`.
567 #[test]
568 fn stats_path_projector_field_helpers_empty_series_yields_empty_vec() {
569 let series = SampleSeries::empty();
570 let u64s = series.stats_path("").u64_fields();
571 assert!(
572 u64s.is_empty(),
573 "empty series must yield empty u64_fields, got {} entries",
574 u64s.len(),
575 );
576 let f64s = series.stats_path("").f64_fields();
577 assert!(
578 f64s.is_empty(),
579 "empty series must yield empty f64_fields, got {} entries",
580 f64s.len(),
581 );
582 }
583}