ktstr/stats/row.rs
1use super::*;
2
3/// Per-scenario result row for gauntlet analysis and run-to-run comparison.
4///
5/// Populated by [`sidecar_to_row`] from on-disk [`SidecarResult`](crate::test_support::SidecarResult)s. The
6/// comparison pipeline reads metric values through [`MetricDef::read`]
7/// / [`METRICS`] rather than dereferencing fields directly so new
8/// metrics can land through the registry without touching every
9/// reader.
10///
11/// # NaN-ambiguity on direct f64 fields
12///
13/// All direct f64 fields on this struct are sanitized via
14/// `finite_or_zero` at [`sidecar_to_row`] ingress. A `0.0` on any
15/// direct f64 field may represent either a genuine zero measurement
16/// or a sanitized non-finite upstream value (NaN / ±Infinity). See
17/// [`sidecar_to_row`]'s NaN-ambiguity doc for the full policy;
18/// `tracing::warn!` is the disambiguation channel — the sanitizer
19/// warns on every non-finite it rewrites to zero, so the log
20/// timeline tells you which run's zeroes were real. Consumers that
21/// cannot accept the ambiguity should prefer metric paths that
22/// flow through `ext_metrics` (a `BTreeMap<String, f64>` — see the
23/// field definition below): non-finite entries are DROPPED at
24/// [`sidecar_to_row`] ingress rather than stored. A subsequent
25/// `ext_metrics.get(name)` returns `None` because the key is
26/// absent, not because an `Option::None` sentinel is stored — the
27/// map's value type is `f64`, which cannot represent "missing".
28/// Absent-key and zero-valued metrics therefore remain distinguishable
29/// for downstream consumers.
30///
31/// # `#[non_exhaustive]` migration note
32///
33/// Downstream code that pattern-matches a `GauntletRow` must end
34/// the match with `..`; future fields added alongside new metrics
35/// otherwise break every matcher. Prefer reading values via
36/// [`MetricDef::read`] / the registry — the point of the
37/// registry indirection is that new metrics do not touch
38/// existing readers.
39#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
40#[non_exhaustive]
41pub struct GauntletRow {
42 pub scenario: String,
43 pub topology: String,
44 pub work_type: String,
45 /// Effective host-CPU budget the run's vCPU threads ran on
46 /// (`SidecarResult::cpu_budget`); `None` for skip rows (budget 0).
47 /// Drives the [`Dimension::CpuBudget`] pairing so cross-budget runs
48 /// are never compared (confining 32 vCPUs to 4 host CPUs measures
49 /// something different), and (with [`vcpus`](Self::vcpus)) feeds the
50 /// compare-path overcommit warning in [`render_overcommit_warning`].
51 #[serde(default, skip_serializing_if = "Option::is_none")]
52 pub cpu_budget: Option<u32>,
53 /// Guest vCPU count (`SidecarResult::vcpus`); `None` for skip rows.
54 /// NOT a Dimension — it rides alongside [`cpu_budget`](Self::cpu_budget)
55 /// so [`render_overcommit_warning`] can flag a compared run whose host
56 /// time-sliced its vCPUs (`cpu_budget < vcpus`), whose guest-scheduler
57 /// timing metrics are then host-contention-confounded.
58 #[serde(default, skip_serializing_if = "Option::is_none")]
59 pub vcpus: Option<u32>,
60 /// Measured host scheduling dilation (`wall / delivered vCPU CPU time`).
61 /// CPU-denominated rates exclude it; genuinely wall-semantic latency and
62 /// upstream wall-throughput metrics retain it as explicit comparison
63 /// context. `None` when the run could not measure vCPU schedstat.
64 #[serde(default, skip_serializing_if = "Option::is_none")]
65 pub host_dilation: Option<f64>,
66 /// Denomination of this row's workload-throughput rate metrics,
67 /// carried from `SidecarResult::throughput_denomination`
68 /// (`#[serde(default)]` = `Wall` for pre-marker rows). NOT an
69 /// operator-facing Dimension — it is an unconditional part of every
70 /// `PairingKey` (like `scenario`; see `super::group`), so a
71 /// wall-era row never pairs with, or group-averages into, a
72 /// cpu-era row: the throughput keys kept their names across the
73 /// denomination change and their values are not comparable across it.
74 /// Cross-era near-misses are surfaced by
75 /// `CompareReport::denomination_mismatches`.
76 #[serde(default)]
77 pub throughput_denomination: crate::test_support::ThroughputDenomination,
78 /// Scheduler binary name carried from the source sidecar
79 /// (`SidecarResult::scheduler`). Surfaced through the substring
80 /// filter in [`compare_rows_by`] and the typed
81 /// `RowFilter::schedulers` so users can narrow A/B comparisons
82 /// by scheduler name.
83 pub scheduler: String,
84 /// Kernel version carried from the source sidecar
85 /// (`SidecarResult::kernel_version`). `None` when the sidecar
86 /// writer could not extract a version (e.g. a raw kernel image
87 /// path with no metadata.json sibling, or a dirty source tree
88 /// where HEAD does not describe the build). Surfaced via the
89 /// typed [`RowFilter::kernels`] for narrowing — when the user
90 /// passes `--kernel 6.14.2` (repeatable), rows with `None` are
91 /// dropped to preserve the operator's intent ("only these
92 /// kernels"); a `None`-as-wildcard would silently dilute the
93 /// filtered set.
94 #[serde(default, skip_serializing_if = "Option::is_none")]
95 pub kernel_version: Option<String>,
96 /// ktstr project git commit carried from the source sidecar
97 /// (`SidecarResult::project_commit`). Short hex with optional
98 /// `-dirty` suffix (e.g. `"abcdef1"` or `"abcdef1-dirty"`).
99 /// `None` when the sidecar writer could not probe a git repo
100 /// at write time (cwd not inside a checkout, or
101 /// `crate::test_support::sidecar::detect_project_commit`
102 /// failed for any reason). Surfaced via the typed
103 /// [`RowFilter::project_commits`] for narrowing — when the
104 /// user passes `--project-commit abcdef1` (repeatable), rows
105 /// with `None` are dropped to preserve the operator's intent
106 /// ("only these commits"); a `None`-as-wildcard would silently
107 /// dilute the filtered set, mirroring the [`RowFilter::kernels`]
108 /// policy.
109 ///
110 /// Sourced from `SidecarResult::project_commit`; shortened to
111 /// `commit` on the row because the project commit is the
112 /// most-frequently-narrowed-on of the three commit dimensions
113 /// on [`SidecarResult`](crate::test_support::SidecarResult). The other two commit fields —
114 /// `SidecarResult::scheduler_commit` and
115 /// `SidecarResult::kernel_commit` — get fully-qualified names
116 /// here (`scheduler_commit` is reserved and not yet exposed,
117 /// `kernel_commit` is the typed filter `RowFilter::kernel_commits`
118 /// applies). The bare `commit` shortening is internal to
119 /// `GauntletRow`; the CLI flag is the disambiguated
120 /// `--project-commit` form so an operator never has to guess
121 /// which "commit" dimension a bare `--commit` would have meant.
122 #[serde(default, skip_serializing_if = "Option::is_none")]
123 pub commit: Option<String>,
124 /// Kernel SOURCE TREE git commit carried from the source
125 /// sidecar (`SidecarResult::kernel_commit`). Short hex with
126 /// optional `-dirty` suffix (e.g. `"abcdef1"` or
127 /// `"abcdef1-dirty"`). `None` when the sidecar writer could
128 /// not probe a git repo for the kernel directory at write
129 /// time (KTSTR_KERNEL points at a non-git path, the
130 /// underlying source is `Tarball` / `Git` rather than
131 /// `Local`, or
132 /// `crate::test_support::sidecar::detect_kernel_commit`
133 /// failed for any reason).
134 ///
135 /// Distinct from [`GauntletRow::commit`]: that field tracks
136 /// the ktstr framework HEAD ("which version of the harness
137 /// produced this sidecar?"); this field tracks the kernel
138 /// tree HEAD ("which kernel commit did this run boot?"). Two
139 /// runs with the same `commit` but different `kernel_commit`
140 /// values are typical when the kernel under test is updated
141 /// without re-checking out the harness; two runs with the
142 /// same `kernel_commit` but different `commit` values are
143 /// typical when the harness is bumped without rebuilding the
144 /// kernel.
145 ///
146 /// Surfaced via the typed [`RowFilter::kernel_commits`] for
147 /// narrowing — same opt-in policy as [`RowFilter::project_commits`]:
148 /// rows with `None` never match a populated filter.
149 #[serde(default, skip_serializing_if = "Option::is_none")]
150 pub kernel_commit: Option<String>,
151 /// Run-environment provenance tag carried from
152 /// `SidecarResult::run_source` (`"local"` for developer runs,
153 /// `"ci"` when `crate::test_support::sidecar::KTSTR_CI_ENV`
154 /// was set at write time, `"archive"` when the consumer pulled
155 /// the pool from a non-default `--dir`). `None` for sidecars
156 /// produced before the field existed (pre-1.0 disposable
157 /// schema; re-running the test regenerates the entry).
158 /// Surfaced via the typed [`RowFilter::run_sources`] for
159 /// narrowing — when the user passes `--run-source local`
160 /// (repeatable), rows with `None` are dropped to preserve the
161 /// operator's intent ("only these environments"); a
162 /// `None`-as-wildcard would silently dilute the filtered set,
163 /// mirroring the [`RowFilter::kernels`] /
164 /// [`RowFilter::project_commits`] / [`RowFilter::kernel_commits`]
165 /// policy.
166 ///
167 /// Field name `run_source` (renamed from `source`) disambiguates
168 /// from [`crate::cache::KernelSource`] / `KernelMetadata.source`
169 /// — those describe the kernel build's input (tarball / git /
170 /// local), this describes the run-environment provenance.
171 #[serde(default, skip_serializing_if = "Option::is_none")]
172 pub run_source: Option<String>,
173 /// Scheduler-resolution provenance carried from
174 /// [`crate::test_support::SidecarResult::resolve_source`] —
175 /// the snake_case resolution-path tag (`"auto_built"`,
176 /// `"env_var"`, `"path"`, ...; historical sidecars may carry retired
177 /// tags such as `"target_debug"`). `None` for sidecars produced
178 /// before the field existed (pre-1.0 disposable schema) and for skip
179 /// rows (no binary resolved). Surfaced via the typed
180 /// [`RowFilter::resolve_sources`] (`--resolve-source`) for narrowing +
181 /// pairing — same opt-in policy as `run_source` — and listed by
182 /// `stats list-values`. Provenance, not identity: distinct
183 /// from `scheduler` / `kernel_commit` — it records HOW the scheduler
184 /// binary was found, so a reader can tell an auto-built-from-HEAD run
185 /// from a possibly-stale `$PATH` binary.
186 #[serde(default, skip_serializing_if = "Option::is_none")]
187 pub resolve_source: Option<String>,
188 /// True when the underlying [`crate::assert::AssertResult::is_pass`] returned
189 /// true at sidecar emission time — a real pass with at least one
190 /// observed outcome and no Fail/Inconclusive/Skip. Mutually
191 /// exclusive with [`Self::skipped`] and [`Self::inconclusive`]:
192 /// the three bits encode a strict 4-state verdict where exactly
193 /// one of (Pass, Skip, Inconclusive, Fail) is set per row.
194 pub passed: bool,
195 /// True when the run was skipped (topology mismatch, missing
196 /// resource). Mutually exclusive with [`Self::passed`] (Skip is
197 /// not Pass; the empty / all-Skip outcomes vec maps to Skip,
198 /// not Pass) and with [`Self::inconclusive`]. Lets stats tooling
199 /// exclude these from pass counts so skipped runs don't inflate
200 /// the apparent pass rate.
201 pub skipped: bool,
202 /// True when at least one assertion recorded
203 /// [`crate::assert::Outcome::Inconclusive`] — the run ran but a
204 /// zero-denominator ratio gate could not be evaluated. Mutually
205 /// exclusive with [`Self::passed`] and [`Self::skipped`]; in the
206 /// `Fail > Inconclusive > Pass > Skip` lattice, Inconclusive
207 /// dominates Pass/Skip but loses to Fail, so a row with both
208 /// Inconclusive and Fail outcomes records `inconclusive = false,
209 /// passed = false` (Fail wins). Surfaced as a distinct bit so
210 /// `is_fail` can exclude these from hard-fail counts and
211 /// dashboards can triage zero-denominator runs separately from
212 /// real regressions.
213 #[serde(default)]
214 pub inconclusive: bool,
215 /// True when this row's source run was an `expect_err` /
216 /// `expect_auto_repro` test whose actual scenario failure was
217 /// inverted to a pass — its telemetry is failure-mode-dominated
218 /// (short / stalled run), so [`compare_rows_by`] excludes it from
219 /// the regression math even though [`passed`](Self::passed) is now
220 /// `true`. Carried from `SidecarResult::expected_failure`;
221 /// OR-folded across a cohort in `group_and_average_by`.
222 #[serde(default)]
223 pub expected_failure: bool,
224 /// Number of monitor samples this run was averaged over —
225 /// the natural per-RUN weight for `Gauge(Avg)` metrics when
226 /// folded across multiple runs at cross-RUN comparison time
227 /// (`group_and_average_by`). Sourced from
228 /// `MonitorSummary::total_samples` at sidecar-write time;
229 /// `0` when the monitor did not run for this scenario
230 /// (host-only test, early VM failure). A `0` weight
231 /// degenerates to unweighted mean per the fallback at
232 /// `aggregate_samples`'s zero-total-weight branch.
233 ///
234 /// The field exists because the cross-RUN aggregator
235 /// previously computed unweighted arithmetic mean for every
236 /// metric — biased for `Gauge(Avg)` when runs in a cohort
237 /// had different sample populations (a 5-sample run and a
238 /// 50-sample run contributing equally to the cohort mean).
239 /// Carrying the per-RUN count here lets the aggregator dispatch
240 /// per-`MetricKind` weighted folds via the helper.
241 #[serde(default)]
242 pub run_sample_count: usize,
243 /// Worst-case per-cgroup spread across the run. Four names
244 /// describe the same quantity across the pipeline:
245 /// - [`ScenarioStats::worst_spread`](crate::assert::ScenarioStats::worst_spread)
246 /// — the upstream source. `sidecar_to_row` reads it and
247 /// writes the value into this field via `finite_or_zero`.
248 /// - `GauntletRow.spread` (this field) — the Rust-side
249 /// struct access path inside the comparison pipeline.
250 /// - `MetricDef.name == "worst_spread"` — the [`METRICS`]
251 /// registry key, which is the domain-level name that appears
252 /// in sidecars, CI gates, and `cargo ktstr perf-delta`
253 /// output.
254 /// - DataFrame column `"spread"` — the polars column name used
255 /// when the rows are projected into a DataFrame for group /
256 /// aggregate operations.
257 ///
258 /// The registry name is not renamed to match the field name
259 /// because existing sidecars and CI regression gates reference
260 /// `"worst_spread"` by string and a rename would silently
261 /// invalidate them. The DataFrame column stays `"spread"` for
262 /// terseness and to match the field; consumers that cross
263 /// the registry / DataFrame boundary translate via
264 /// [`MetricDef::read`] rather than by string comparison.
265 pub spread: f64,
266 /// Worst-case per-cgroup scheduling gap (ms). Surfaced in
267 /// [`METRICS`] under registry name `worst_gap_ms`; the
268 /// field / registry / DataFrame-column divergence is catalogued
269 /// in the triples table on [`METRICS`].
270 pub gap_ms: u64,
271 /// Total CPU migrations across the run. Surfaced in [`METRICS`]
272 /// under registry name `total_migrations`; see the triples
273 /// table on [`METRICS`] for the rationale behind the
274 /// field / registry / DataFrame-column divergence.
275 pub migrations: u64,
276 /// Worst-case per-cgroup migrations-per-iteration ratio.
277 /// Surfaced in [`METRICS`] under registry name
278 /// `worst_migration_ratio`; see the triples table on
279 /// [`METRICS`] for the field / registry / DataFrame-column
280 /// divergence.
281 pub migration_ratio: f64,
282 // Monitor fields (host-side telemetry from guest memory reads).
283 /// Worst per-sample cgroup imbalance ratio. Surfaced in
284 /// [`METRICS`] under registry name `max_imbalance_ratio`
285 /// (DataFrame column `imbalance`); see the triples table on
286 /// [`METRICS`] for the registry/field/column rationale.
287 pub imbalance_ratio: f64,
288 /// Worst observed DSQ queue depth. Registry and field names
289 /// match (`max_dsq_depth`) but the DataFrame column is
290 /// `dsq_depth`; see the triples table on [`METRICS`] for the
291 /// column-level rename rationale.
292 pub max_dsq_depth: u32,
293 /// Stuck-sample count across the run (CPUs whose `rq_clock`
294 /// failed to advance between consecutive samples). Distinct from
295 /// the sched_ext watchdog stall (`SCX_EXIT_ERROR_STALL`):
296 /// "stuck" tracks rq_clock not advancing on a CPU, while a
297 /// watchdog stall describes a runnable task that hasn't been
298 /// scheduled within the watchdog timeout. Registry and field
299 /// names match (`stuck_count`) but the DataFrame column is
300 /// `stuck`; see the triples table on [`METRICS`] for the
301 /// column-level rename rationale.
302 ///
303 /// `f64`, not an integer: a per-run row carries an exact integer
304 /// count, but the cross-run average fold (`super::group`'s
305 /// `group_and_average_by`) stores the fractional mean here so the
306 /// A/B comparison reads the true delta. Rounding the mean to an
307 /// integer would let the up-to-1.0 rounding error defeat the
308 /// `stuck_count` metric's `default_abs` of 1.0 and fabricate
309 /// single-stall regressions from sub-integer differences (e.g. an
310 /// A-side mean of 1.4 vs a B-side mean of 1.6 rounds to 1 vs 2).
311 pub stuck_count: f64,
312 /// Fallback-dispatch count across the run. Carried as-is from
313 /// `MonitorSummary::event_deltas.total_fallback` — an integer
314 /// event count, NOT a rate. Surfaced in [`METRICS`] under
315 /// registry name `total_fallback` (DataFrame column `fallback`);
316 /// see the triples table on [`METRICS`] for the registry / field /
317 /// column rationale.
318 pub fallback_count: i64,
319 /// Keep-last dispatch count across the run. Carried as-is from
320 /// `MonitorSummary::event_deltas.total_dispatch_keep_last` — an
321 /// integer event count, NOT a rate. Surfaced in [`METRICS`] under
322 /// registry name `total_keep_last` (DataFrame column `keep_last`);
323 /// see the triples table on [`METRICS`] for the registry / field /
324 /// column rationale.
325 pub keep_last_count: i64,
326 // Benchmarking fields. The wake-latency (p99 / median / CV) and
327 // run-delay (mean / worst) roll-ups are NO LONGER typed fields: they are
328 // `MetricKind::Distribution`, re-pooled into `ext_metrics` post-merge by
329 // `crate::assert::populate_run_distribution_metrics`; `MetricDef::read`
330 // surfaces them via the ext fallback (their accessors are `|_| None`).
331 pub total_iterations: u64,
332 // worst_wake_latency_tail_ratio is NO LONGER a typed field: it is
333 // `MetricKind::WakeLatencyTailRatio`, re-selected into `ext_metrics`
334 // post-merge by `crate::assert::populate_run_distribution_metrics` (max
335 // over the per-cgroup p99/median ratios, floor-gated below
336 // [`WAKE_LATENCY_TAIL_RATIO_MIN_ITERATIONS`]); `MetricDef::read` surfaces
337 // it via the ext fallback (accessor `|_| None`).
338 // worst_iterations_per_worker / worst_iterations_per_cpu_sec are NO
339 // LONGER typed fields: they are `MetricKind::WorstLowest`, re-selected
340 // into `ext_metrics` post-merge by
341 // `crate::assert::populate_run_distribution_metrics` (lowest-wins over
342 // the per-cgroup counters); `MetricDef::read` surfaces them via the ext
343 // fallback. The `worst_` naming convention is documented on [`METRICS`].
344 // NUMA fields.
345 // Neither NUMA roll-up is a typed GauntletRow column any longer:
346 // worst_page_locality is `MetricKind::WorstLowest` (NumaLocal/NumaTotal) and
347 // worst_cross_node_migration_ratio is `MetricKind::WorstCrossNodeRatio`, both
348 // ext-sourced (re-pooled from the per-phase NUMA carriers by
349 // populate_run_distribution_metrics); `MetricDef::read` surfaces them via the
350 // ext fallback, so no typed columns.
351 /// Extensible metrics populated by scenarios and processed by the
352 /// comparison pipeline. Keyed by metric name; looked up via
353 /// [`metric_def`] when a matching entry exists in [`METRICS`].
354 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
355 pub ext_metrics: BTreeMap<String, f64>,
356 /// The subset of [`Self::ext_metrics`] keys that are Dynamic monotonic
357 /// counters (the level-suffixed `lb_*`/`alb_*` schedstat deltas + any
358 /// `ScalarCounter` watched bpf field). These keys are not in the static
359 /// `METRICS` registry, so the cross-run aggregator (`fold_ext_metrics`)
360 /// consults this set to SUM-fold them instead of averaging — matching the
361 /// registered-Counter cross-run convention. Empty when the run has no
362 /// monitor or no Dynamic counter keys.
363 #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
364 pub ext_counter_keys: BTreeSet<String>,
365 /// Per-phase metric buckets carried verbatim from the source
366 /// sidecar's [`crate::assert::ScenarioStats::phases`]. Each
367 /// [`crate::assert::PhaseBucket`] surfaces the metric values
368 /// reduced over one scenario phase (BASELINE at
369 /// `step_index = 0`, Step ordinals at `step_index = 1..=N`
370 /// per the 1-indexed phase convention) so the per-phase
371 /// comparison renderer at [`compare_partitions_noise`] can pair
372 /// matched phases across two sidecars by `step_index` and
373 /// emit per-phase spread rows without re-deriving phase
374 /// boundaries.
375 ///
376 /// Empty when the source sidecar had no phase data — single-
377 /// phase scenarios that didn't drive an explicit Step vec,
378 /// or legacy sidecars from before the phase-aware pipeline
379 /// shipped. Per the pre-1.0 disposability contract, the
380 /// expected response to a legacy sidecar is to re-run the
381 /// test and regenerate, NOT to back-fill the field on read.
382 /// `serde(default, skip_serializing_if = "Vec::is_empty")`
383 /// keeps the serialized shape compact: a row with no phase
384 /// data omits the field entirely on the wire rather than
385 /// carrying an empty array.
386 #[serde(default, skip_serializing_if = "Vec::is_empty")]
387 pub phases: Vec<crate::assert::PhaseBucket>,
388 /// Per-test [`crate::test_support::PerfDeltaAssertion`] declarations (owned
389 /// records) carried from the sidecar so the perf-delta noise compare can
390 /// enforce the declared gate. Empty for rows with none; `serde(default)`
391 /// tolerates legacy sidecars (pre-1.0 disposability). NOT a pairing/slicing
392 /// dimension — per-test gate metadata only.
393 #[serde(default, skip_serializing_if = "Vec::is_empty")]
394 pub perf_delta_assertions: Vec<crate::test_support::PerfDeltaAssertionRecord>,
395}
396
397impl GauntletRow {
398 /// Convenience accessor mirroring [`crate::assert::AssertResult::is_pass`]
399 /// so the is_pass / is_fail vocabulary applies uniformly across both
400 /// verdict surfaces. GauntletRow is the sidecar-wire shape; its
401 /// `passed` bool is populated from `AssertResult::is_pass()` at
402 /// sidecar emission time.
403 ///
404 /// Returns true only when the row reached a real Pass — neither
405 /// skipped, inconclusive, nor failed. The triple-conjunct guard
406 /// matches the strict 4-state mutex encoded with three stored
407 /// bits `(passed, skipped, inconclusive)` (Fail is the all-false
408 /// derived state, no dedicated bit), so a manually-constructed
409 /// row that sets `passed = true, skipped = true` (which would
410 /// violate the mutex) still reads as not-pass here.
411 ///
412 /// Part of the `is_pass` / `is_fail` / `is_inconclusive` /
413 /// `is_skip` vocabulary uniform across the verdict surfaces:
414 /// [`crate::assert::AssertResult::is_pass`] /
415 /// [`crate::test_support::SidecarResult::is_pass`] /
416 /// [`crate::assert::Outcome::is_pass`] / `MonitorVerdict::is_pass`
417 /// (in the `monitor` module, which is `pub(crate)`) /
418 /// `Verdict::is_pass` (re-exported at [`crate::assert::Verdict`])
419 /// / `Self::is_pass`.
420 pub fn is_pass(&self) -> bool {
421 self.passed && !self.skipped && !self.inconclusive
422 }
423 /// Convenience accessor mirroring
424 /// [`crate::assert::AssertResult::is_fail`]. True only when the
425 /// row is a real failure — not a skip, not an inconclusive
426 /// (zero-denominator) run. Excludes `inconclusive` so a stats
427 /// gate that counts "real regressions" does not conflate
428 /// inconclusive runs with hard failures.
429 pub fn is_fail(&self) -> bool {
430 !self.passed && !self.skipped && !self.inconclusive
431 }
432 /// Convenience accessor mirroring
433 /// [`crate::assert::AssertResult::is_skip`].
434 pub fn is_skip(&self) -> bool {
435 self.skipped
436 }
437 /// Convenience accessor mirroring
438 /// [`crate::assert::AssertResult::is_inconclusive`]. True when
439 /// the row reflects a zero-denominator ratio gate that could
440 /// not be evaluated.
441 pub fn is_inconclusive(&self) -> bool {
442 self.inconclusive
443 }
444}
445
446/// Typed-field filter set for narrowing `GauntletRow` sets in the
447/// `cargo ktstr perf-delta` pipeline. Every field is `None` /
448/// empty by default; populated fields are AND-combined ACROSS
449/// fields, with field-internal OR/AND semantics described per-field
450/// below. Applied via `apply_row_filters` in `compare_partitions`
451/// before the rows reach `compare_rows_by`.
452///
453/// Match semantics:
454/// - `scheduler` / `topology` / `work_type` — STRICT EQUALITY against
455/// the row's corresponding field. The sibling substring filter on
456/// `compare_rows_by` (`-E`) stays as the only fuzzy-match knob;
457/// typed fields are exact so a `--scheduler scx_rusty` filter does
458/// NOT spuriously match `scx_rusty_alt`.
459/// - `kernels` — repeatable, OR-combined: a row matches iff its
460/// `kernel_version` equals ANY entry in `kernels`. Mirrors the
461/// `--kernel` flag on `cargo ktstr test`/`coverage`/`llvm-cov`
462/// so the same flag name carries the same multi-value semantic
463/// across every subcommand.
464/// - `project_commits` — repeatable, OR-combined: a row matches
465/// iff its `commit` equals ANY entry in `project_commits`. Same
466/// multi-value semantic as `kernels`, applied to the ktstr
467/// project commit recorded by `detect_project_commit` at
468/// sidecar-write time. Surfaced as the `--project-commit` CLI
469/// flag.
470/// - `kernel_commits` — repeatable, OR-combined: a row matches
471/// iff its `kernel_commit` equals ANY entry in `kernel_commits`.
472/// Same multi-value semantic as `project_commits`, applied to
473/// the kernel source-tree commit recorded by
474/// `crate::test_support::sidecar::detect_kernel_commit` at
475/// sidecar-write time. Filters on the kernel HEAD, NOT on the
476/// kernel release version (`kernels` is the version filter).
477/// - `run_sources` — repeatable, OR-combined: a row matches iff
478/// its `run_source` equals ANY entry in `run_sources`. Same
479/// multi-value semantic as `kernels` / `project_commits` /
480/// `kernel_commits`, applied to the run-environment provenance
481/// tag (`"local"`, `"ci"`, `"archive"`) recorded by
482/// `crate::test_support::sidecar::detect_run_source` at
483/// sidecar-write time, or rewritten to `"archive"` at load
484/// time when the consumer pulled the pool from a non-default
485/// `--dir`. Surfaced as the `--run-source` CLI flag.
486/// - A `kernels`-populated filter against a row whose
487/// `kernel_version` is `None` ALWAYS fails (no wildcard semantic)
488/// — the operator wrote specific versions and a `None`-row would
489/// silently dilute the set. The same opt-in policy applies to
490/// `project_commits` against rows with `commit == None`, to
491/// `kernel_commits` against rows with `kernel_commit == None`,
492/// and to `run_sources` against rows with `run_source == None`.
493///
494/// Empty `RowFilter` (every field `None`/empty) is the no-op default
495/// and matches every row. Use [`RowFilter::default()`] to build it.
496#[derive(Clone, Debug, Default)]
497pub struct RowFilter {
498 /// Repeatable kernel-version filter, OR-combined: a row matches
499 /// iff its `GauntletRow::kernel_version` equals ANY entry. Empty
500 /// vec disables the filter ("do not filter on kernel"). A row
501 /// whose `kernel_version` is itself `None` never matches a
502 /// non-empty filter.
503 pub kernels: Vec<String>,
504 /// Repeatable project-commit filter, OR-combined: a row matches
505 /// iff its `GauntletRow::commit` equals ANY entry. Empty vec
506 /// disables the filter ("do not filter on commit"). A row whose
507 /// `commit` is itself `None` never matches a non-empty filter
508 /// — same opt-in semantic as `kernels`.
509 ///
510 /// Field name `project_commits` (renamed from `commits`)
511 /// disambiguates from the sibling `kernel_commits` field — both
512 /// describe commit dimensions, so the prefix makes "which
513 /// repository's commit?" obvious at every call site.
514 pub project_commits: Vec<String>,
515 /// Repeatable kernel-source-commit filter, OR-combined: a row
516 /// matches iff its `GauntletRow::kernel_commit` equals ANY
517 /// entry. Empty vec disables the filter ("do not filter on
518 /// kernel commit"). A row whose `kernel_commit` is itself
519 /// `None` never matches a non-empty filter — same opt-in
520 /// semantic as `project_commits`.
521 ///
522 /// Distinct from `project_commits` (the ktstr framework commit)
523 /// and from `kernels` (the kernel release version): two runs
524 /// with the same `kernel_version` but different `kernel_commit`
525 /// values represent the same release rebuilt from different
526 /// trees (e.g. WIP patches on top, a different remote ref).
527 pub kernel_commits: Vec<String>,
528 /// Repeatable run-environment-source filter, OR-combined: a row
529 /// matches iff its `GauntletRow::run_source` equals ANY entry.
530 /// Empty vec disables the filter ("do not filter on
531 /// run_source"). A row whose `run_source` is itself `None`
532 /// (sidecar pre-dates the field) never matches a non-empty
533 /// filter — same opt-in semantic as `kernels` /
534 /// `project_commits` / `kernel_commits`.
535 /// Typical values: `"local"`, `"ci"`, `"archive"`. The schema
536 /// is open: any string is acceptable so a future producer can
537 /// introduce a new tag without a version bump.
538 ///
539 /// Field name `run_sources` (renamed from `sources`)
540 /// disambiguates from `KernelMetadata.source` /
541 /// [`crate::cache::KernelSource`] — those describe the kernel
542 /// build's input, this describes the run-environment provenance.
543 pub run_sources: Vec<String>,
544 /// Repeatable scheduler-resolution-source filter, OR-combined: a
545 /// row matches iff its `GauntletRow::resolve_source` equals ANY
546 /// entry. Empty vec disables the filter. A row whose
547 /// `resolve_source` is `None` (sidecar pre-dates the field, or a
548 /// skip resolved no binary) never matches a non-empty filter —
549 /// same opt-in semantic as `run_sources`. Values are the
550 /// [`crate::test_support::ResolveSource::as_str`] tags
551 /// (`"auto_built"`, `"env_var"`, `"path"`, ...; historical sidecars
552 /// may also carry retired tags such as `"target_debug"`). Distinct from
553 /// `run_sources` (the run ENVIRONMENT): this is HOW the scheduler
554 /// binary was found. Backs the [`Dimension::ResolveSource`] filter +
555 /// pairing dim (`--resolve-source`).
556 pub resolve_sources: Vec<String>,
557 /// Repeatable cpu-budget filter, OR-combined: a row matches iff its
558 /// `GauntletRow::cpu_budget` (the effective host-CPU budget, as a
559 /// decimal string) equals ANY entry. Empty vec disables the filter.
560 /// Rows with `cpu_budget == None` (skips) are dropped when this filter
561 /// is non-empty, mirroring `kernels` / `run_sources`. Backs the
562 /// [`Dimension::CpuBudget`] filter + pairing dim (`--cpu-budget`).
563 pub cpu_budgets: Vec<String>,
564 /// Repeatable scheduler-name filter, OR-combined: a row matches
565 /// iff its `GauntletRow::scheduler` equals ANY entry. Empty vec
566 /// disables the filter ("do not filter on scheduler"). Strict
567 /// equality on each entry — the substring `-E` filter is the
568 /// only fuzzy-match knob; typed flags exact-match. Mirrors the
569 /// shape of `kernels` / `project_commits` / `kernel_commits` /
570 /// `run_sources` so every typed dimension supports the same
571 /// repeatable OR-combined idiom.
572 pub schedulers: Vec<String>,
573 /// Repeatable topology filter, OR-combined: a row matches iff
574 /// its `GauntletRow::topology` equals ANY entry. The filter
575 /// values are the rendered form (e.g. `"1n2l4c2t"`) that
576 /// `Topology::Display` emits and `cargo ktstr stats list`
577 /// shows. Empty vec disables the filter.
578 pub topologies: Vec<String>,
579 /// Repeatable work-type filter, OR-combined: a row matches iff
580 /// its `GauntletRow::work_type` equals ANY entry. Valid names
581 /// are the PascalCase variants of `WorkType::ALL_NAMES`. Empty
582 /// vec disables the filter.
583 pub work_types: Vec<String>,
584}
585
586impl RowFilter {
587 /// Returns true when every populated filter field matches the
588 /// row. The empty `RowFilter` (default) returns true for every
589 /// row — it's the identity filter.
590 pub fn matches(&self, row: &GauntletRow) -> bool {
591 if !self.kernels.is_empty() {
592 // OR-combined: the row matches iff its kernel version
593 // matches ANY listed kernel. A row with `None`
594 // kernel_version never satisfies a non-empty filter —
595 // same opt-in semantic the original `Option<String>`
596 // field carried.
597 //
598 // Match shape: a filter value with two dot-separated
599 // digit segments (e.g. `6.12`) is a major.minor PREFIX —
600 // the row matches if its `kernel_version` equals
601 // `6.12` exactly, starts with `6.12.` (patch releases
602 // including the `6.12.0-rcN+` kernel banner shape),
603 // or starts with `6.12-` (the no-patch `6.12-rcN`
604 // shape `kernel_path::KernelId::Version` admits). A
605 // filter with three or more segments (e.g. `6.14.2`,
606 // `6.15-rc3`) is strict equality. The two-segment
607 // cutoff matches the shape of `MAJOR.MINOR` versus
608 // `MAJOR.MINOR.PATCH` / `MAJOR.MINOR-rcN` — there is
609 // no shorter form on the sidecar producer side worth
610 // treating as a prefix (`6` alone would match every
611 // 6.x release, which is a less useful cohort than the
612 // per-stable-series narrowing the operator usually
613 // wants).
614 let row_kernel = row.kernel_version.as_deref();
615 let any = self.kernels.iter().any(|want| match row_kernel {
616 Some(rk) => kernel_filter_matches(want, rk),
617 None => false,
618 });
619 if !any {
620 return false;
621 }
622 }
623 if !self.project_commits.is_empty() {
624 // OR-combined match against `GauntletRow::commit`,
625 // mirroring the `kernels` policy: a row whose `commit`
626 // is `None` (the sidecar writer's gix probe failed or
627 // cwd was outside any git repo) never matches a
628 // populated filter, so a `--project-commit` argument is opt-in
629 // to "only rows with this commit" rather than a wildcard.
630 let row_commit = row.commit.as_deref();
631 let any = self
632 .project_commits
633 .iter()
634 .any(|want| row_commit == Some(want.as_str()));
635 if !any {
636 return false;
637 }
638 }
639 if !self.kernel_commits.is_empty() {
640 // OR-combined match against `GauntletRow::kernel_commit`,
641 // mirroring the `project_commits` policy: a row whose
642 // `kernel_commit` is `None` (the sidecar writer's
643 // `detect_kernel_commit` probe failed, or `KTSTR_KERNEL`
644 // pointed at a non-git source) never matches a populated
645 // filter — same opt-in semantic as `--project-commit` /
646 // `--kernel`.
647 let row_kc = row.kernel_commit.as_deref();
648 let any = self
649 .kernel_commits
650 .iter()
651 .any(|want| row_kc == Some(want.as_str()));
652 if !any {
653 return false;
654 }
655 }
656 if !self.run_sources.is_empty() {
657 // OR-combined match against `GauntletRow::run_source`,
658 // mirroring the `kernels` / `project_commits` /
659 // `kernel_commits` opt-in policy: a row whose
660 // `run_source` is `None` (sidecar pre-dates the field)
661 // never matches a populated filter, so a `--run-source`
662 // argument demands a tagged row rather than acting as a
663 // wildcard.
664 let row_run_source = row.run_source.as_deref();
665 let any = self
666 .run_sources
667 .iter()
668 .any(|want| row_run_source == Some(want.as_str()));
669 if !any {
670 return false;
671 }
672 }
673 if !self.resolve_sources.is_empty() {
674 // OR-combined match against `GauntletRow::resolve_source`,
675 // mirroring the `run_sources` opt-in policy: a row whose
676 // `resolve_source` is `None` (sidecar pre-dates the field,
677 // or a skip resolved no binary) never matches a populated
678 // filter, so a `--resolve-source` argument demands a tagged
679 // row rather than acting as a wildcard.
680 let row_resolve_source = row.resolve_source.as_deref();
681 let any = self
682 .resolve_sources
683 .iter()
684 .any(|want| row_resolve_source == Some(want.as_str()));
685 if !any {
686 return false;
687 }
688 }
689 if !self.cpu_budgets.is_empty() {
690 // OR-combined match against `GauntletRow::cpu_budget` rendered
691 // as a decimal string. A row with `cpu_budget == None` (skip)
692 // never matches a populated filter — same opt-in policy as
693 // `run_sources` / `kernels`.
694 let row_budget = row.cpu_budget.map(|n| n.to_string());
695 let any = self
696 .cpu_budgets
697 .iter()
698 .any(|want| row_budget.as_deref() == Some(want.as_str()));
699 if !any {
700 return false;
701 }
702 }
703 if !self.schedulers.is_empty() {
704 // OR-combined match against `GauntletRow::scheduler`
705 // (a `String`, never `None`). Strict equality on each
706 // entry — same shape as the other repeatable typed
707 // filters above.
708 let any = self.schedulers.contains(&row.scheduler);
709 if !any {
710 return false;
711 }
712 }
713 if !self.topologies.is_empty() {
714 // OR-combined match against `GauntletRow::topology`.
715 let any = self.topologies.contains(&row.topology);
716 if !any {
717 return false;
718 }
719 }
720 if !self.work_types.is_empty() {
721 // OR-combined match against `GauntletRow::work_type`.
722 let any = self.work_types.contains(&row.work_type);
723 if !any {
724 return false;
725 }
726 }
727 true
728 }
729}
730
731/// Drop rows from `rows` that do not match every populated filter
732/// field on `filter`. Returns the surviving rows in their original
733/// order. The caller is responsible for any further dedup or
734/// aggregation; this helper preserves duplicates as written.
735///
736/// Used by [`compare_partitions`] before the surviving rows reach
737/// [`compare_rows_by`], so the substring-`-E` filter and the typed
738/// filters compose: typed narrows happen first, substring runs over
739/// the surviving set.
740pub fn apply_row_filters(rows: &[GauntletRow], filter: &RowFilter) -> Vec<GauntletRow> {
741 rows.iter().filter(|r| filter.matches(r)).cloned().collect()
742}
743
744/// Match a single `--kernel` filter value against a row's
745/// `kernel_version`. Major.minor (two-segment) filter values match
746/// any patch release in that series via prefix; longer filter
747/// values use strict equality.
748///
749/// `want` is the user-supplied filter value (e.g. `6.12`,
750/// `6.14.2`, `6.15-rc3`). `row_kernel` is the sidecar-recorded
751/// kernel version (e.g. `6.12.5`). The two-segment cutoff matches
752/// the natural shape of `MAJOR.MINOR` versus
753/// `MAJOR.MINOR.PATCH` / `MAJOR.MINOR-rcN` — `6.12.` is a
754/// stable-series prefix; `6.14.2` is one specific release.
755///
756/// Examples:
757/// - `kernel_filter_matches("6.12", "6.12.5")` → true (prefix)
758/// - `kernel_filter_matches("6.12", "6.12")` → true (exact equal)
759/// - `kernel_filter_matches("6.12", "6.13.0")` → false
760/// - `kernel_filter_matches("6.14", "6.14-rc3")` → true (prefix
761/// admits the `-rcN` pre-release of the same series; per
762/// `kernel_path::decompose_version_for_compare`, `6.14-rc3`
763/// shares the `(major=6, minor=14, patch=0)` tuple with the
764/// `6.14` release, and the operator filtering on the series
765/// wants both)
766/// - `kernel_filter_matches("6.14", "6.14.0-rc3+")` → true
767/// (kernel banner shape — patch=0 plus `-rcN` plus `EXTRAVERSION`)
768/// - `kernel_filter_matches("6.14.2", "6.14.2")` → true
769/// - `kernel_filter_matches("6.14.2", "6.14.20")` → false
770/// (strict equality on three-segment filter — without the
771/// strict path, `6.14.2` would also match `6.14.20`,
772/// `6.14.21`, ..., which is not what the operator asked for)
773pub(crate) fn kernel_filter_matches(want: &str, row_kernel: &str) -> bool {
774 if is_major_minor_prefix(want) {
775 // Three accepted shapes for a major.minor (`MAJOR.MINOR`)
776 // prefix filter, all designed so the prefix is bounded by
777 // a non-digit separator that disambiguates the series:
778 //
779 // 1. Exact equal: `row_kernel == "6.14"`. The row's
780 // recorded version IS the major.minor string itself
781 // (no patch, no rc).
782 // 2. Trailing-dot prefix: `row_kernel.starts_with("6.14.")`.
783 // Covers patch releases (`6.14.0`, `6.14.5`) and
784 // kernel banner shapes (`6.14.0-rc3+`).
785 // 3. Trailing-dash prefix: `row_kernel.starts_with("6.14-")`.
786 // Covers the no-patch pre-release shape (`6.14-rc3`).
787 // Per `kernel_path` (KernelId::Version doc), this is a
788 // valid emitted shape; per
789 // `decompose_version_for_compare` it shares the
790 // `(major, minor, patch=0)` triple with the `6.14`
791 // release and the operator filtering on the series
792 // wants both.
793 //
794 // The non-digit separator after `want` (`.` or `-`)
795 // prevents `6.1` from spuriously matching `6.10.0` or
796 // `6.10-rc3` — both fail because the next character after
797 // `6.1` is `0`, which is neither separator. The `6.140`
798 // case is also rejected for the same reason.
799 row_kernel == want
800 || row_kernel.starts_with(&format!("{want}."))
801 || row_kernel.starts_with(&format!("{want}-"))
802 } else {
803 row_kernel == want
804 }
805}
806
807/// Whether a filter value looks like a major.minor PREFIX. Two
808/// non-empty dot-separated digit segments and nothing else
809/// (no `-rcN`, no third dot). Conservative: anything outside the
810/// `MAJOR.MINOR` shape falls through to strict equality so a typo
811/// like `6.14.2.` or `6.14-something` does not silently turn into
812/// a wildcard.
813fn is_major_minor_prefix(s: &str) -> bool {
814 let parts: Vec<&str> = s.split('.').collect();
815 parts.len() == 2
816 && parts
817 .iter()
818 .all(|p| !p.is_empty() && p.bytes().all(|b| b.is_ascii_digit()))
819}