ktstr/stats/metric.rs
1use super::*;
2
3/// Definition of a metric for the comparison pipeline.
4///
5/// Each entry describes polarity (`higher_is_worse`), dual-gate
6/// significance thresholds (`default_abs`, `default_rel`), a
7/// display unit string for formatted output, and a row accessor
8/// (`accessor`) that returns the metric's value from a
9/// [`GauntletRow`] without a hand-maintained name→field match.
10///
11/// The `accessor` field is skipped in serde output because `fn`
12/// pointers are not serializable. A future `Deserialize` impl
13/// would need callers to re-hydrate the accessor by looking up
14/// `name` via [`metric_def`] — the static [`METRICS`] table is
15/// the authoritative source of the function identity. No such
16/// impl exists today; the note is a forward-conditional so that
17/// if one is added, the migration path is spelled out rather
18/// than reinvented per site.
19///
20/// # Registered vs unregistered metrics
21///
22/// The static [`METRICS`] registry is the "core metric" set with
23/// hand-authored accessors, hand-tuned dual-gate thresholds
24/// (`default_abs` / `default_rel`), and display units. Each
25/// registered `MetricDef.accessor` reads a typed field on
26/// `GauntletRow` directly (e.g. `r.spread`, `r.gap_ms`).
27///
28/// Metrics that fall OUTSIDE this registry are carried on
29/// `GauntletRow.ext_metrics: BTreeMap<String, f64>`. Registered
30/// metrics never flow through `ext_metrics`; unregistered metrics
31/// never flow through the typed fields. [`MetricDef::read`] and
32/// `read_metric` check the registered-field accessor first and
33/// fall back to an `ext_metrics.get(name)` lookup — a name that
34/// matches neither returns `None`. Consumers that want to
35/// distinguish "registered-but-null" from "unregistered-and-
36/// absent" must inspect the registry directly rather than rely
37/// on the fallback.
38///
39/// # `#[non_exhaustive]` migration note
40///
41/// Downstream code that pattern-matches an instance of `MetricDef`
42/// must end the match with `..` so a future field addition does
43/// not become a breaking change. Prefer reading values through
44/// the static [`METRICS`] registry and [`metric_def`] lookup
45/// rather than constructing `MetricDef` values by hand.
46#[derive(Debug, Clone, serde::Serialize)]
47#[non_exhaustive]
48pub struct MetricDef {
49 pub name: &'static str,
50 /// Regression direction for this metric. A metric that
51 /// previously used `higher_is_worse: true` maps to
52 /// [`Polarity::LowerBetter`](crate::test_support::Polarity::LowerBetter)
53 /// (bigger values are regressions, so smaller is better);
54 /// `false` maps to
55 /// [`Polarity::HigherBetter`](crate::test_support::Polarity::HigherBetter).
56 /// The sense is INVERSE: the old bool answered "does growing
57 /// this value mean worse?" while the enum answers "what
58 /// direction do we want this to move?".
59 pub polarity: crate::test_support::Polarity,
60 /// Temporal aggregation kind. Drives how
61 /// [`aggregate_samples`] collapses N readings of the same
62 /// metric across multiple capture samples (e.g. periodic
63 /// monitor ticks within one run, or runs pooled for a
64 /// `cargo ktstr perf-delta` comparison) into one comparable
65 /// value. Distinct from [`Self::polarity`], which is the
66 /// "good direction" of the FINAL value: kind tells us HOW to
67 /// reduce a vec of samples; polarity tells us how to interpret
68 /// the reduced number.
69 ///
70 /// Default `Counter` matches the most common shape — every
71 /// kernel monotonic counter (SCX_EV_*, ttwu_count, run_delay,
72 /// cpustat[]) collapses by sum-of-deltas. ~80% of ktstr fields
73 /// are counters; the field exists so the remaining peaks and
74 /// gauges can opt out of sum-aggregation explicitly.
75 pub kind: MetricKind,
76 /// Absolute-materiality gate: a move smaller than this (in the metric's
77 /// [`Self::display_unit`]) is never a confident change, ANDed with
78 /// [`Self::default_rel`]. Its role depends on the metric's dynamic range
79 /// across workloads:
80 ///
81 /// - **Scale-bounded** metrics (a ratio of co-scaling counters, or a
82 /// naturally-bounded unit — `%` spread, `ms`/`µs` latency, `x` ratios,
83 /// `[0,1]` fractions): `default_abs` is a fixed unit-scale measurement-
84 /// noise floor. A sub-unit move is immaterial regardless of its relative
85 /// size, so a fixed floor is correct.
86 /// - **Scale-varying** metrics (a raw per-event count, or a rate normalized
87 /// only by time — `*_per_sec`, `ops/s`, `req/s`, `ns/s`): the baseline
88 /// spans orders of magnitude across workloads, so a fixed floor calibrated
89 /// for high throughput would MASK a large relative regression on a low-
90 /// throughput workload. Here `default_abs` is only a NEAR-IDLE activity
91 /// guard (it keeps a big relative swing on a near-idle baseline from
92 /// firing) and [`Self::default_rel`] carries materiality. Three tests
93 /// enforce that every scale-varying metric keeps a near-idle floor:
94 /// `throughput_rate_floors_are_near_idle` (per-time rates + throughput
95 /// carriers), `scale_varying_count_floors_are_near_idle` (raw counts and
96 /// ns/µs accumulations), and `mixed_class_scale_varying_floors_pinned`
97 /// (the mixed-class Peak/WorstLowest/PerPhase metrics, by allowlist).
98 pub default_abs: f64,
99 pub default_rel: f64,
100 pub display_unit: &'static str,
101 #[serde(skip)]
102 pub accessor: fn(&GauntletRow) -> Option<f64>,
103}
104
105/// Temporal aggregation classification for a metric.
106///
107/// Kernel-source-grounded per the metric-semantics taxonomy.
108/// Drives [`aggregate_samples`] — the function that collapses a
109/// slice of per-sample readings of the SAME metric into one
110/// representative value for downstream regression / display.
111///
112/// Reduction semantics by variant:
113/// - [`MetricKind::Counter`] — kernel monotonic counter; the
114/// temporal aggregate is the SUM of consecutive deltas across
115/// the sample window. For pre-deltaed inputs (each sample
116/// carries its own window's count) this is `samples.iter().sum()`.
117/// - [`MetricKind::Gauge`] — instantaneous value; the
118/// [`GaugeAgg`] subkind picks Avg / Last / Max.
119/// - [`MetricKind::Peak`] — kernel-side max-of-window (e.g.
120/// `max_run_delay`, `max_newidle_lb_cost`); temporal aggregate
121/// is max-of-max so a window-wise high-water never gets
122/// diluted.
123/// - [`MetricKind::Timestamp`] — wall/rq clock; the temporal
124/// aggregate is the LAST sample's value (a snapshot of "where
125/// the clock is now"). Diffing two captures gives elapsed
126/// time, but a single window's reduction picks the latest
127/// reading — averaging timestamps is meaningless.
128// Serialize only: MetricKind is serialized as part of MetricDef (which is
129// Serialize-only) but is never deserialized. A `Deserialize` derive here
130// would narrow to `Deserialize<'static>` because the Rate variant carries
131// `&'static str` fields (serde treats `&str` as borrowed), so it would not
132// satisfy `DeserializeOwned` and would break any future container that
133// deserializes an embedded MetricKind. Drop it rather than carry a fragile,
134// unused impl.
135#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize)]
136#[non_exhaustive]
137pub enum MetricKind {
138 /// Monotonic counter (SCX_EV_* event counters,
139 /// `cpustat[CPUTIME_*]`, `bpf_prog_stats.cnt`, `ttwu_count`,
140 /// `nr_migrations`, …). Aggregate by sum.
141 Counter,
142 /// Instantaneous value (`nr_running`, `local_dsq.nr`, current
143 /// `policy`, current `comm`). The [`GaugeAgg`] tag picks the
144 /// reduction: Avg for typical-load, Last for "what's happening
145 /// now", Max for worst-instant.
146 Gauge(GaugeAgg),
147 /// Kernel max-of-window (`max_run_delay`,
148 /// `max_newidle_lb_cost`, the per-CPU preempt-off peak).
149 /// Aggregate by max — a peak that ever fired must survive the
150 /// reduction.
151 Peak,
152 /// Clock or wall-time reading (`rq.clock`,
153 /// CLOCK_REALTIME-stamped capture timestamps). Aggregate by
154 /// Last — averaging timestamps loses meaning.
155 Timestamp,
156 /// PRE-DELTAED counter: each sample is already a delta-since-the-
157 /// previous-read, not a cumulative-since-boot total. Schedulers
158 /// that delta their scx_stats Metrics server-side per reader
159 /// request (e.g. scx_mitosis) produce this — one ktstr snapshot =
160 /// one reader request = one delta. The per-phase reduction is the
161 /// SUM of the in-phase deltas (NOT the `Counter` last-minus-first,
162 /// which would difference two deltas into nonsense); the flat-run
163 /// reduction is likewise the sum. Boundary: the first in-phase
164 /// delta straddles the phase boundary (it spans from the last
165 /// pre-phase read to the first in-phase read, so it includes a
166 /// little pre-phase activity); it is attributed to the phase its
167 /// read lands in — a slight left-edge over-attribution, the
168 /// deliberate semantic since a per-read delta cannot be split.
169 DeltaSum,
170 /// An INJECTED per-phase delta that SUMS across phases within a run but
171 /// folds by UNWEIGHTED MEAN across runs. Each per-phase value is a
172 /// thread-group CPU-time delta (`system_time_ns` / `user_time_ns`,
173 /// written directly into `PhaseBucket.metrics` by `phase_group_cpu_delta`
174 /// — there is no `read_sample` arm). The cross-PHASE fold is the SUM of the
175 /// disjoint per-phase deltas (like `Counter`), NOT a sample-count-weighted
176 /// mean: a per-phase delta is already proportional to the phase's
177 /// wall-clock duration, and the freeze `sample_count` is too, so a weighted
178 /// mean would double-count duration and collapse the run to a meaningless
179 /// duration-weighted average per-phase delta. The sum is the run's total
180 /// OBSERVED CPU time — first-to-last freeze WITHIN each phase — a lower
181 /// bound that excludes pre-first-freeze, post-last-freeze, and
182 /// inter-phase-gap windows (and single-freeze phases, which contribute
183 /// nothing), per `phase_group_cpu_delta`'s observed-window semantic; that
184 /// is sufficient for an A/B regression signal, where the same
185 /// observed-window sum is compared on both sides. Across RUNS each run
186 /// contributes exactly one total, folded by the UNWEIGHTED arithmetic mean
187 /// (`Σ / contributors`) over the runs that emitted the key — NOT weighted
188 /// by `run_sample_count` (the monitor capture count, an unrelated
189 /// population that would also silently zero-weight a monitor-off run). This
190 /// SUM-cross-phase / MEAN-cross-run pair is exactly why these deltas are
191 /// NOT `Gauge(Avg)` (weighted mean at BOTH levels — the bug this kind
192 /// fixes) and NOT `DeltaSum` (sum at both levels, which would inflate the
193 /// cross-run value by the run count). The value is run-wide POOLED (one
194 /// scalar per phase across all tgids), NOT per-cgroup; the cross-cgroup
195 /// same-step merge is `Commutative` (`a + b`, like `Counter`) but is the
196 /// defensive same-step-index path only — dead for these keys, which are
197 /// injected exactly once into the pooled host `PhaseBucket`. NOT
198 /// [`Self::is_derived`] — it carries a real per-phase value, unlike Rate /
199 /// Distribution.
200 PerPhaseDeltaSum,
201 /// Derived ratio of two component metrics — a RATE that must be
202 /// recomputed from its components at every in-map aggregation level, never
203 /// averaged as a ready-made ratio. The variant carries the registry
204 /// names of its `numerator` and `denominator` component metrics, each
205 /// itself registered with its own kind (e.g. a `Counter` numerator).
206 ///
207 /// A Rate has NO samples of its own. Its value is DERIVED from the
208 /// already-reduced component values as `map[numerator] /
209 /// map[denominator]` by the [`derive_rate_metrics`] post-pass. An
210 /// aggregation level that pools the components FIRST (each by its own
211 /// kind — a `Counter` numerator sums, a `Gauge(Avg)` averages) and
212 /// then re-derives the rate RE-POOLS correctly: for the common
213 /// `Counter / Counter` case the result is `Σnumerator / Σdenominator`,
214 /// NOT a mean of two phases' ready-made ratios `(r₁ + r₂) / 2` (which
215 /// is WRONG whenever the phases carry different denominator weight,
216 /// e.g. iterations-per-cpu-second across phases of unequal CPU time).
217 /// The numerator and denominator must already be expressed in units
218 /// whose quotient is the intended rate unit (the component
219 /// registration owns the unit choice; this variant does not scale).
220 ///
221 /// `derive_rate_metrics` runs as a post-pass wherever components co-locate:
222 /// per-phase reduction and carrier derivation, cross-phase bucket merge,
223 /// cross-run ext-metric reduction, and cross-cgroup pooled re-pools
224 /// (`crate::assert::populate_run_pooled_iteration_rate`,
225 /// `crate::assert::populate_run_pooled_taobench`,
226 /// `crate::assert::populate_run_pooled_schbench`).
227 /// The cross-CGROUP `AssertResult::merge` ext-metrics fold itself uses
228 /// worst-case polarity (min/max) and is NOT a re-pool site; the pooled
229 /// re-pool runs separately after it, at the eval layer, reading
230 /// `stats.cgroups` directly. The canonical `iteration_rate` components are
231 /// per-cgroup, and `populate_run_pooled_iteration_rate` re-pools
232 /// them post-merge.
233 ///
234 /// Because a single sample slice cannot express the re-pool, a Rate is
235 /// FORBIDDEN from the single-slice reducers ([`aggregate_finite`]
236 /// panics on it); the post-pass is its only producer.
237 Rate {
238 /// Registry name of the numerator component metric.
239 numerator: &'static str,
240 /// Registry name of the denominator component metric.
241 denominator: &'static str,
242 },
243 /// Derived DISTRIBUTIONAL aggregate re-pooled from a raw per-cgroup
244 /// sample set, never folded from ready-made per-cgroup reductions. The
245 /// variant names the [`SampleSource`] (which
246 /// [`crate::assert::PhaseCgroupStats`] sample vector feeds it) and the
247 /// [`SampleReduction`] (which statistic to compute over the pooled set).
248 ///
249 /// Like [`MetricKind::Rate`], a Distribution has NO value of its own at
250 /// the WITHIN-RUN levels: its run-level value is DERIVED post-merge by
251 /// `crate::assert::populate_run_distribution_metrics`, which pools the
252 /// raw samples from `stats.phases[].per_cgroup` across every phase and
253 /// cgroup and recomputes the statistic over the COMBINED set — the
254 /// percentile / CV / mean / extreme of the pooled distribution, NOT a
255 /// max or mean of per-cgroup reductions (the percentile of a union is
256 /// not the max of per-source percentiles). It is therefore FORBIDDEN
257 /// from the per-phase single-slice reducers
258 /// ([`aggregate_samples_for_phase`] returns None via
259 /// [`MetricKind::is_derived`]); the post-pass is its only within-run
260 /// producer. When the size-limited bulk frame strips the sample pools
261 /// (`crate::assert::strip_phase_cgroup_samples`), the producer falls
262 /// back to a worst-wins fold over the surviving per-cgroup `CgroupStats`
263 /// reductions so the metric degrades rather than vanishing.
264 ///
265 /// CROSS-RUN it is a HYBRID, unlike Rate: a run's components (the raw
266 /// sample vectors) do not survive into the cross-RUN ext-metrics map
267 /// (phases are dropped at the cross-RUN fold), so there is no combined
268 /// sample SET to re-pool across runs. The cross-RUN value is instead a
269 /// plain fold of the per-run derived values — an UNWEIGHTED mean (over the
270 /// runs that emitted the key, `sum / finite.len()`) for the percentile /
271 /// CV / mean reductions and a MAX for [`SampleReduction::Worst`] (the
272 /// peak run-delay) — applied by [`aggregate_finite`] over the per-run ext
273 /// values. So `is_derived`
274 /// skips it at the within-run sites, but the cross-RUN ext fold does
275 /// NOT skip it (only Rate, whose components DO survive cross-RUN, is
276 /// skipped there).
277 Distribution {
278 /// Which raw sample vector on
279 /// [`crate::assert::PhaseCgroupStats`] feeds this aggregate.
280 source: SampleSource,
281 /// Which statistic to recompute over the pooled sample set.
282 reduction: SampleReduction,
283 },
284 /// Derived LOWEST-WINS per-cgroup selector — the worst (lowest) cgroup's
285 /// `numerator / denominator` ratio across the run, re-pooled from per-cgroup
286 /// carriers rather than folded from ready-made ratios. None-aware lowest-wins
287 /// (the semantic the deleted `fold_lowest_some` carried in
288 /// [`crate::assert::AssertResult::merge`], now in
289 /// `crate::assert::populate_run_distribution_metrics`): a measured
290 /// `Some(0.0)` — a cgroup that ran zero iterations (real starvation) for the
291 /// efficiency selectors, or one with all pages off-node for
292 /// `worst_page_locality` — wins the worst bucket; a not-measured `None` (no
293 /// workers / no on-CPU time / no NUMA pages) is skipped; and an all-`None`
294 /// cohort produces no key (absence preserved as a missing ext entry, never a
295 /// `0.0`).
296 ///
297 /// Derived post-merge by
298 /// `crate::assert::populate_run_distribution_metrics`. The SOURCE depends on
299 /// the numerator: the iteration-efficiency selectors (`Iterations`) re-pool
300 /// from the `stats.cgroups[]` counters (which survive bulk-frame stripping,
301 /// so they need no degraded fallback); `worst_page_locality` (`NumaLocal`)
302 /// re-pools from the per-phase `stats.phases[].per_cgroup` NUMA carriers (the
303 /// reports-only `CgroupStats` hardcodes `page_locality` 0.0, so it cannot
304 /// source from `stats.cgroups[]`). Like Distribution it is `is_derived`
305 /// (skipped at the within-run reducers) and CROSS-RUN it MEAN-folds the
306 /// per-run derived values through [`aggregate_finite`].
307 WorstLowest {
308 /// The per-cgroup numerator (`Iterations` or `NumaLocal`).
309 numerator: WorstLowestNumerator,
310 /// The per-cgroup denominator the numerator is divided by.
311 denominator: WorstLowestDenominator,
312 },
313 /// Derived WORST-CGROUP wake-latency tail-amplification selector — the
314 /// highest per-cgroup `p99 / median` wake-latency ratio across the run.
315 /// Higher-is-worse (a stretched long tail), so "worst" is the MAX over
316 /// cgroups — the polarity-opposite of [`MetricKind::WorstLowest`]'s
317 /// lowest-wins. Re-selected post-merge by
318 /// `crate::assert::populate_run_distribution_metrics` from the
319 /// `stats.cgroups[]` entries via `CgroupStats::wake_latency_tail_ratio`
320 /// (deliberately NOT `pooled_p99 / pooled_median` of the cross-cgroup
321 /// union — that is the distinct `worst_p99_wake_latency_us` /
322 /// `worst_median_wake_latency_us` Distribution pair). Like Distribution /
323 /// WorstLowest it is [`MetricKind::is_derived`] (skipped at the within-run
324 /// reducers); the producer emits NO key when the run is below the
325 /// [`WAKE_LATENCY_TAIL_RATIO_MIN_ITERATIONS`] noise floor or no cgroup
326 /// carried a measurable tail (absence preserved as a missing ext entry,
327 /// never a `0.0` sentinel — the no-false-zero contract the deleted typed
328 /// field could not express).
329 ///
330 /// CROSS-RUN it folds, like every WorstLowest selector, by the UNWEIGHTED
331 /// exclude-missing MEAN through [`aggregate_finite`] (`sum / finite.len()`
332 /// over the runs that emitted the key) — the cohort's TYPICAL worst-cgroup
333 /// tail amplification, deliberately NOT a MAX: peak-of-peaks is reserved
334 /// for [`SampleReduction::Worst`] (a peak detector answering "did this ever
335 /// fire"), whereas this answers "what is this cohort's characteristic
336 /// worst-cgroup tail". A run below the floor never enters the mean, so no
337 /// sub-threshold run dilutes the cohort (the bug the ext relocation fixed:
338 /// the deleted typed cross-RUN fold summed every passing run's raw ratio
339 /// over `passes_observed`, folding noisy low-N runs in as real values).
340 WakeLatencyTailRatio,
341 /// Derived WORST-CGROUP cross-node migration-churn selector — the highest
342 /// per-cgroup `cross_node_migrated / numa_pages_total` ratio across the run.
343 /// LowerBetter (more cross-node migration is worse), so "worst" is the MAX
344 /// over cgroups — the polarity twin of `worst_page_locality`
345 /// ([`MetricKind::WorstLowest`] `NumaLocal`/`NumaTotal`, lowest-wins), sharing
346 /// the same per-phase NUMA carriers and the `numa_agg_per_cgroup` helper.
347 /// Re-pooled post-merge by
348 /// `crate::assert::populate_run_distribution_metrics` from
349 /// `stats.phases[].per_cgroup`: the cross-phase fold SUMs the per-phase
350 /// migration-counter deltas over the LATEST residency total
351 /// (`cross_node_migration_ratio_of(summed_migrated, latest_total)`), then
352 /// MAXes across cgroups that measured NUMA residency (`numa_pages_total > 0`);
353 /// a never-measured cohort yields no key (absence preserved as a missing ext
354 /// entry, never a `0.0`). A CHURN ratio (cumulative migration EVENTS over a
355 /// residency SNAPSHOT) — can legitimately exceed 1.0, NOT a bounded `[0,1]`
356 /// fraction. A dedicated max-selector like [`MetricKind::WakeLatencyTailRatio`]
357 /// (no generic numerator/denominator), since cross_node is the sole max-wins
358 /// phase-carrier ratio. Like the other derived kinds it is
359 /// [`MetricKind::is_derived`] (skipped at the within-run reducers) and
360 /// CROSS-RUN MEAN-folds through [`aggregate_finite`] over the runs that
361 /// EMITTED the key — the cohort's typical worst-cgroup churn. The deleted
362 /// typed `Gauge(Last)` field instead averaged its value over
363 /// `passes_observed`, folding a NUMA-less passing run's `0.0` sentinel into
364 /// the mean (dilution); the ext re-pool writes no key for a never-measured
365 /// run (absence preserved), so it never enters the divisor.
366 WorstCrossNodeRatio,
367 /// Per-phase-only scalar derived ONCE per phase from a phase-scoped
368 /// carrier, NOT from monitor samples and NOT re-pooled run-level. The sole
369 /// producer is [`crate::assert::derive_phase_metrics`], which derives two
370 /// families per phase:
371 /// - the schbench scalars: it pools each phase's
372 /// `crate::assert::PhaseCgroupStats` schbench carriers and re-derives a
373 /// percentile (from the merged latency histogram), a sample-weighted mean
374 /// (run-delay), or a count (loop_count), writing them into BOTH each
375 /// carrier's `PhaseCgroupStats::metrics` (per-cgroup, read via
376 /// `phase_cgroup_metric`) AND the pooled
377 /// `crate::assert::PhaseBucket::metrics` (read via `phase_metric`).
378 /// - the NON-schbench carrier scalars (wake/run-delay/off-cpu distributions
379 /// + migration/iterations/locality ratios, via `write_carrier_scalars`):
380 /// written ONLY into each `PhaseCgroupStats::metrics` (per-cgroup, read
381 /// via `phase_cgroup_metric`) — these have NO pooled
382 /// `crate::assert::PhaseBucket::metrics` entry; their run-level aggregate
383 /// is the `worst_*` ext-metrics key.
384 /// It is [`MetricKind::is_derived`] (so the within-run reducers —
385 /// [`aggregate_samples_for_phase`] and the phase-bucket merge loop — skip
386 /// it) and has NO run-level producer; it is ADDITIONALLY gated out of the
387 /// cross-RUN ext fold (`fold_ext_metrics`), since a per-phase scalar has no
388 /// meaningful cross-run aggregate. A unit marker (no payload): the
389 /// derivation owns the metric-name→computation mapping, so the kind need not
390 /// carry a percentile selector (which would leak `plat::Pct` through this
391 /// public enum).
392 // doc_lazy_continuation: pre-existing list-item wording surfaced by the clippy
393 // 1.94 bump; renders fine. Suppress rather than reflow the prose.
394 #[allow(clippy::doc_lazy_continuation)]
395 PerPhase,
396 /// A WHOLE-RUN distributional value (a percentile / min / max) re-pooled
397 /// run-level by UNIONING the per-phase per-cgroup raw distribution carriers
398 /// and re-deriving the statistic over the union — the schbench engine's
399 /// `*_whole` wakeup / request / rps keys, written by
400 /// `crate::assert::populate_run_pooled_schbench_distribution` from the
401 /// `PhaseCgroupStats::schbench` `PlatStats` histograms (`PlatStats::combine`
402 /// is an associative bucket-count add, so the merged histogram is the faithful
403 /// union and the re-derived percentile is the percentile OF the pooled sample
404 /// set, NOT a mean of per-source percentiles). UNLIKE
405 /// [`MetricKind::Distribution`] it is NOT cross-RUN folded: a percentile of a
406 /// union is not a mean of per-run percentiles, and the per-phase histograms
407 /// are dropped at the cross-run boundary (no pooled set survives to
408 /// re-derive), so the only honest cross-run treatment is the per-run
409 /// noise-compare — `crate::stats::noise_findings` reads each run's own
410 /// `*_whole` scalar and compares the spread, never averaging them. So it is
411 /// [`MetricKind::is_derived`] (the within-run reducers skip it; the value is
412 /// produced solely by the run-level union populate) AND gated out of the
413 /// cross-RUN ext fold (`fold_ext_metrics`); `noise_findings` is its only
414 /// consumer. ext-only (`accessor |_| None`); the `*_whole` names are distinct
415 /// from the per-phase [`MetricKind::PerPhase`] percentile keys (one registry
416 /// name = one kind) — the established per-phase-vs-whole-run coexistence (as
417 /// the taobench and schbench loop/run-delay whole-run keys also do).
418 PerRunDistribution,
419}
420
421/// Sub-classification for [`MetricKind::Gauge`] picking the
422/// per-window reduction. Most ktstr gauges are Avg ("typical-load
423/// over the window"); Last fits "current state" snapshots like
424/// `comm` / `policy`; Max fits worst-instant queue-depth probes.
425// Serialize-only, matching its container MetricKind (which is Serialize-only)
426// and the sibling MetricKind sub-enums (SampleSource / SampleReduction /
427// WorstLowestNumerator / WorstLowestDenominator). Nothing deserializes a
428// MetricKind / GaugeAgg, so the prior Deserialize derive was dead.
429#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize)]
430#[non_exhaustive]
431pub enum GaugeAgg {
432 /// Reduce by arithmetic mean. Default for `nr_running`-style
433 /// gauges where the question is "what was the typical load".
434 Avg,
435 /// Take the latest sample. Default for `comm` / `policy` /
436 /// `cgroup_path`-style snapshots where the value is "what is
437 /// it RIGHT NOW".
438 Last,
439 /// Take the max sample. Useful when a gauge is being used to
440 /// detect a worst-case regression (e.g. queue-depth probe
441 /// where any spike is the signal of interest).
442 Max,
443}
444
445/// The raw per-cgroup sample vector on
446/// [`crate::assert::PhaseCgroupStats`] that a [`MetricKind::Distribution`]
447/// re-pools over. Each variant maps to exactly one un-reduced sample
448/// vector the per-phase per-cgroup carrier holds (stored RAW in
449/// nanoseconds; the [`SampleReduction`] applies the ns→µs scale once).
450#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize)]
451#[non_exhaustive]
452// The `Ns` suffix on every variant documents the unit (all sources are RAW
453// nanoseconds) at each use site, not just in the enum doc; clippy's
454// enum_variant_names is a style heuristic that misfires on a meaningful shared
455// unit suffix — renaming would drop the unit, so the suffix is kept.
456#[allow(clippy::enum_variant_names)]
457pub enum SampleSource {
458 /// Per-wakeup latency samples in ns
459 /// (`crate::assert::PhaseCgroupStats::wake_latencies_ns`). One sample per
460 /// observed wakeup (reservoir-capped per cgroup), so the pooled set is the
461 /// cross-cgroup union of those capped per-wakeup samples.
462 WakeLatencyNs,
463 /// Per-worker schedstat run-delay samples in ns
464 /// (`crate::assert::PhaseCgroupStats::run_delays_ns`). One sample per worker
465 /// — each is that worker's `sched_info.run_delay` delta over the carrier's
466 /// window (whole-run last-minus-first for the step-local carrier; the
467 /// per-phase delta for the backdrop slice carrier), so the pool size is the
468 /// worker count, NOT a per-wakeup stream like `WakeLatencyNs`.
469 RunDelayNs,
470 /// Per-timer-cycle latency samples in ns
471 /// (`crate::assert::PhaseCgroupStats::timer_latencies_ns`). One sample per
472 /// `clock_nanosleep(CLOCK_MONOTONIC, TIMER_ABSTIME)` wake — the observed
473 /// wake time minus the absolute deadline, floored at 0 — recorded by
474 /// [`crate::workload::WorkType::TimerLatency`] (reservoir-capped per cgroup
475 /// like `WakeLatencyNs`). Distinct from `WakeLatencyNs` so cyclictest-style
476 /// timer latency does not blur with the blocking variants' wake latency in a
477 /// shared sidecar.
478 TimerLatencyNs,
479}
480
481/// The statistic a [`MetricKind::Distribution`] computes over its pooled
482/// [`SampleSource`] set. Each maps to the matching reduction
483/// `crate::assert::cgroup_stats` computes per cgroup, so the run-level
484/// re-pool reproduces that reduction over the COMBINED cross-cgroup set
485/// rather than folding ready-made per-cgroup reductions.
486#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize)]
487#[non_exhaustive]
488pub enum SampleReduction {
489 /// 99th percentile (nearest-rank), ns→µs.
490 P99,
491 /// 99.9th percentile (nearest-rank), ns→µs — the deep tail an RT /
492 /// cyclictest-style latency probe turns on (a single max is one sample;
493 /// p99.9 is the robust deep-tail percentile between p99 and max).
494 P999,
495 /// Median (50th percentile, nearest-rank), ns→µs.
496 Median,
497 /// Coefficient of variation (stddev / mean) over the pooled set,
498 /// `n = pool.len()`. Unitless.
499 Cv,
500 /// Arithmetic mean over the pooled set, ns→µs.
501 Mean,
502 /// Maximum (worst) sample over the pooled set, ns→µs. CROSS-RUN this is
503 /// the one reduction [`aggregate_finite`] folds by MAX (peak survives),
504 /// not MEAN — see [`MetricKind::Distribution`].
505 Worst,
506}
507
508/// The per-cgroup numerator of a [`MetricKind::WorstLowest`] lowest-wins
509/// selector. `#[non_exhaustive]`, mirroring [`MetricKind::Rate`]'s `numerator`.
510/// The producer branches on the numerator to pick the per-cgroup SOURCE:
511/// `Iterations` reads the `crate::assert::CgroupStats` counters; `NumaLocal`
512/// reads the per-phase NUMA carriers (`page_locality` is structurally 0.0 in the
513/// reports-only `CgroupStats`, so it must come from the phase carriers).
514#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize)]
515#[non_exhaustive]
516pub enum WorstLowestNumerator {
517 /// Per-cgroup total iteration count
518 /// (`crate::assert::CgroupStats::total_iterations`).
519 Iterations,
520 /// Per-cgroup pages resident on the expected NUMA node(s) — the
521 /// page-locality numerator, the LATEST per-phase residency snapshot summed
522 /// across the cgroup's workers (`crate::assert::PhaseCgroupStats::numa_pages_local`),
523 /// NOT a `CgroupStats` counter.
524 NumaLocal,
525}
526
527/// The per-cgroup denominator a [`MetricKind::WorstLowest`] numerator is divided
528/// by to form the lowest-wins ratio.
529#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize)]
530#[non_exhaustive]
531pub enum WorstLowestDenominator {
532 /// Worker count (`crate::assert::CgroupStats::num_workers`) — yields
533 /// iterations-per-worker (raw throughput, scales with the CPU budget).
534 NumWorkers,
535 /// On-CPU nanoseconds (`crate::assert::CgroupStats::total_cpu_time_ns`),
536 /// converted ns→s ONCE on the summed counter — yields the
537 /// overcommit-invariant iterations-per-CPU-second efficiency.
538 CpuTimeNs,
539 /// Total resident pages — the page-locality denominator, the LATEST
540 /// per-phase residency snapshot (`crate::assert::PhaseCgroupStats::numa_pages_total`),
541 /// shared with the cross-node ratio. Paired with `NumaLocal` to yield the
542 /// page-locality fraction; the per-cgroup ratio is absent (None) when the
543 /// cgroup measured no NUMA pages.
544 NumaTotal,
545}
546
547/// How a per-phase metric reduction merges across two
548/// [`crate::assert::AssertResult`]s that both carry a
549/// [`crate::assert::PhaseBucket`] at the same `step_index`.
550///
551/// Driven by [`MetricKind::merge_kind`] so a future
552/// [`MetricKind`] addition is forced to declare its merge
553/// semantic explicitly (the match is `#[non_exhaustive]`-aware
554/// via the helper rather than a bare `match` in every caller).
555///
556/// The split mirrors the rolling-aggregation contract in
557/// [`AssertResult::merge`](crate::assert::AssertResult::merge): the
558/// per-phase fold must commute so the accumulator pattern
559/// `AssertResult::pass().merge(real_a).merge(real_b)` yields the
560/// same result whether merges arrive in `a→b` or `b→a` order
561/// — EXCEPT for kinds whose reduction is intrinsically the LAST
562/// sample (`Gauge(Last)`, `Timestamp`), where the merge must
563/// resolve to the bucket whose `end_ms` is later.
564///
565/// Counter, Peak, and Gauge(Max/Avg) are commutative because their
566/// reductions are sum / max / weighted-mean respectively — all
567/// associative, commutative folds over reduced values. Gauge(Last)
568/// and Timestamp are NOT commutative under a per-merge cumulative
569/// fold (the "later" sample wins) so the merge uses `end_ms` as
570/// the tiebreaker rather than the operand order.
571#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
572#[non_exhaustive]
573pub enum MergeKind {
574 /// The reduction commutes: `merge(a, b) == merge(b, a)`. The
575 /// merge folds the two reduced values via the kind's natural
576 /// commutative operation (Counter → sum, Peak / Gauge(Max) →
577 /// max, Gauge(Avg) → weighted mean by `sample_count`).
578 Commutative,
579 /// The reduction is "the LATEST sample's value" (Gauge(Last),
580 /// Timestamp). The merge resolves to the value from whichever
581 /// bucket has the later `end_ms`; ties keep `self`.
582 NonCommutative,
583 /// The value is DERIVED post-merge from pooled components, never folded
584 /// from two already-reduced values. Covers every
585 /// [`MetricKind::is_derived`] kind:
586 /// - [`MetricKind::Rate`]: re-derived as `Σnumerator / Σdenominator` from
587 /// its component keys by [`derive_rate_metrics`];
588 /// - [`MetricKind::Distribution`] / [`MetricKind::WorstLowest`] /
589 /// [`MetricKind::WakeLatencyTailRatio`] / [`MetricKind::WorstCrossNodeRatio`]:
590 /// re-pooled post-merge by
591 /// `crate::assert::populate_run_distribution_metrics`;
592 /// - [`MetricKind::PerPhase`]: re-derived per phase by
593 /// `crate::assert::derive_phase_metrics`.
594 ///
595 /// The per-metric merge loop skips these derived keys entirely and the
596 /// post-pass produces them, so this variant is classification metadata: no
597 /// merge dispatches on it.
598 Recompute,
599}
600
601impl MetricKind {
602 /// Map each [`MetricKind`] variant to the corresponding
603 /// [`MergeKind`] used by per-phase
604 /// [`AssertResult::merge`](crate::assert::AssertResult::merge).
605 /// Centralising the mapping here means a future kind
606 /// addition fails the build until the new variant is wired
607 /// (the inner `match` is exhaustive even though `MetricKind`
608 /// is `#[non_exhaustive]` because this fn lives in the same
609 /// crate).
610 pub fn merge_kind(self) -> MergeKind {
611 match self {
612 MetricKind::Counter => MergeKind::Commutative,
613 MetricKind::Peak => MergeKind::Commutative,
614 MetricKind::Gauge(GaugeAgg::Avg) => MergeKind::Commutative,
615 MetricKind::Gauge(GaugeAgg::Max) => MergeKind::Commutative,
616 MetricKind::Gauge(GaugeAgg::Last) => MergeKind::NonCommutative,
617 MetricKind::Timestamp => MergeKind::NonCommutative,
618 // Per-phase reduction is a sum of in-phase deltas — an
619 // associative, commutative fold, so cross-AssertResult merge
620 // sums the two reduced values (same as Counter).
621 MetricKind::DeltaSum => MergeKind::Commutative,
622 // PerPhaseDeltaSum: the cross-cgroup same-step merge is a
623 // commutative sum (`a + b`, like Counter), but for these run-wide
624 // POOLED keys (one scalar per phase, injected once into the host
625 // bucket) it is the defensive same-step-index path only — two real
626 // values are never summed. (The SUM-cross-phase / MEAN-cross-run
627 // split is handled at the fold sites, not in this merge.)
628 MetricKind::PerPhaseDeltaSum => MergeKind::Commutative,
629 // A Rate is re-derived from its pooled components, never
630 // folded from two ready-made ratios.
631 MetricKind::Rate { .. } => MergeKind::Recompute,
632 // Distribution and WorstLowest are derived post-merge by
633 // `populate_run_distribution_metrics` (re-pooled from the
634 // per-cgroup raw samples / counters), so the per-phase merge
635 // loop skips them and re-derives — classification-only, like
636 // Rate. See [`MetricKind::is_derived`].
637 MetricKind::Distribution { .. } => MergeKind::Recompute,
638 MetricKind::WorstLowest { .. } => MergeKind::Recompute,
639 // Worst-cgroup wake-latency tail ratio: derived post-merge by
640 // `populate_run_distribution_metrics` (max over the merged
641 // `stats.cgroups` per-cgroup ratios), so the per-phase merge loop
642 // skips and re-derives it — classification-only, like the other
643 // derived kinds.
644 MetricKind::WakeLatencyTailRatio => MergeKind::Recompute,
645 // Worst-cgroup cross-node migration churn: derived post-merge by
646 // `populate_run_distribution_metrics` (max over the per-phase NUMA
647 // carriers' per-cgroup churn ratio), so the per-phase merge loop skips
648 // and re-derives it — classification-only, like the other derived kinds.
649 MetricKind::WorstCrossNodeRatio => MergeKind::Recompute,
650 // PerPhase is derived post-merge by `derive_phase_metrics` (schbench
651 // scalars into PhaseBucket.metrics + PhaseCgroupStats::metrics;
652 // non-schbench carrier scalars into PhaseCgroupStats::metrics only);
653 // the per-phase merge loop skips it (is_derived) and never re-derives
654 // via a kind — classification-only, like the other derived kinds.
655 MetricKind::PerPhase => MergeKind::Recompute,
656 // PerRunDistribution is derived run-level by
657 // `populate_run_pooled_schbench_distribution` (union of the per-phase
658 // per-cgroup PlatStats histograms, percentile re-derived over the
659 // union); the per-phase merge loop skips it (is_derived) and never
660 // re-derives via a kind — classification-only, like the other derived
661 // kinds.
662 MetricKind::PerRunDistribution => MergeKind::Recompute,
663 }
664 }
665
666 /// Whether this kind is DERIVED post-merge from other data rather than
667 /// reduced from its own per-phase sample slice: [`MetricKind::Rate`]
668 /// (from numerator/denominator components), [`MetricKind::Distribution`]
669 /// (re-pooled from the per-cgroup raw sample sets), [`MetricKind::WorstLowest`]
670 /// (lowest-wins over per-cgroup counters),
671 /// [`MetricKind::WakeLatencyTailRatio`] (max over the per-cgroup p99/median
672 /// wake-latency ratios, floor-gated), and [`MetricKind::WorstCrossNodeRatio`]
673 /// (max over the per-cgroup cross-node migration-churn ratios).
674 ///
675 /// Drives the WITHIN-RUN skip-sites that must not reduce a derived kind
676 /// from a slice: [`aggregate_samples_for_phase`] returns None, and the
677 /// per-phase build, the cross-phase
678 /// `crate::assert::merge_matched_phase_buckets` key-loop, and
679 /// [`crate::assert::populate_run_ext_metrics_from_phases`] all skip the
680 /// key then re-derive.
681 ///
682 /// NOT a uniform cross-RUN skip: at the cross-RUN ext fold
683 /// ([`group_and_average_by`], via `fold_ext_metrics`) [`MetricKind::Rate`],
684 /// [`MetricKind::PerPhase`], AND [`MetricKind::PerRunDistribution`] are
685 /// skipped — Rate's components survive cross-RUN so it re-derives there;
686 /// PerPhase is a per-phase-only scalar with no meaningful cross-RUN aggregate
687 /// (its skip also keeps [`aggregate_finite`]'s `PerPhase => unreachable!`
688 /// unreachable); and PerRunDistribution is a percentile-of-union whose
689 /// per-phase histograms are not shipped cross-RUN (a percentile of a union is
690 /// not a mean of per-run percentiles), so it is noise-compared per-run, never
691 /// folded — while Distribution / WorstLowest / WakeLatencyTailRatio /
692 /// WorstCrossNodeRatio, whose components do NOT survive cross-RUN, fall through
693 /// to be plainly folded (MEAN, or MAX for [`SampleReduction::Worst`]) by
694 /// [`aggregate_finite`]. So callers gate on `is_derived` for the within-run
695 /// sites and on `matches!(.., Rate { .. } | PerPhase | PerRunDistribution)`
696 /// for the cross-RUN ext fold.
697 pub fn is_derived(self) -> bool {
698 matches!(
699 self,
700 MetricKind::Rate { .. }
701 | MetricKind::Distribution { .. }
702 | MetricKind::WorstLowest { .. }
703 | MetricKind::WakeLatencyTailRatio
704 | MetricKind::WorstCrossNodeRatio
705 | MetricKind::PerPhase
706 | MetricKind::PerRunDistribution
707 )
708 }
709}
710
711/// Reduce a slice of per-sample readings of the same metric into
712/// one representative value, dispatching on [`MetricKind`]. Used
713/// by sample-windowed comparison paths (e.g. multi-tick monitor
714/// captures, perf-delta across multiple snapshot
715/// subdirectories) to collapse a sample vec into the value the
716/// existing scalar-comparison pipeline already understands.
717///
718/// Returns `None` when `samples` is empty — the caller decides
719/// whether absence is a missing-data condition or a benign
720/// "no samples in window" result. NaN samples are dropped from
721/// the reduction (same semantics as the existing percentile()
722/// helper); a final all-NaN input also returns `None`.
723///
724/// Semantics by kind:
725/// - `Counter` → sum of finite samples — the flat-run reduction
726/// for cross-RUN aggregation. NOT the right semantic for
727/// per-phase reduction of a cumulative-since-boot Counter
728/// (which would over-count). Callers wanting per-phase
729/// Counter reduction use [`aggregate_samples_for_phase`],
730/// which routes Counter through a dedicated last-minus-first
731/// branch instead of dispatching through here.
732/// - `Gauge(Avg)` → arithmetic mean of finite samples.
733/// - `Gauge(Last)` → last finite sample.
734/// - `Gauge(Max)` → max of finite samples.
735/// - `Peak` → max of finite samples.
736/// - `Timestamp` → last finite sample.
737///
738/// Live caller: [`aggregate_samples_for_phase`] dispatches every
739/// non-Counter kind through this entry point so the per-phase
740/// reduction inherits the flat-run semantic for Gauge / Peak /
741/// Timestamp without restating it. That fn is itself folded by
742/// [`crate::assert::build_phase_buckets`] whose live caller is
743/// the host-side `evaluate_vm_result` AssertResult-population
744/// site at `src/test_support/eval/mod.rs`.
745pub fn aggregate_samples(samples: &[f64], kind: MetricKind) -> Option<f64> {
746 let finite: Vec<f64> = samples.iter().copied().filter(|x| x.is_finite()).collect();
747 aggregate_finite(&finite, |_| 1, kind)
748}
749
750/// Weighted variant of [`aggregate_samples`]. Takes a slice of
751/// `(value, weight)` pairs so the lock-step shape is enforced by
752/// the type — there is no length-mismatch class for the caller to
753/// trigger. Weight is consulted for [`MetricKind::Gauge`] with
754/// [`GaugeAgg::Avg`] (weighted mean); other kinds fold by their
755/// natural reduction and ignore weight.
756///
757/// NaN-valued pairs drop along with their weight (filter operates
758/// on the value field — no risk of weights misaligning to other
759/// samples after filtering, unlike the previous parallel-slice
760/// shape).
761///
762/// Zero total weight degenerates to the unweighted mean per the
763/// `merge_metric_values` precedent. Weight sum uses `checked_add`
764/// with fallback to unweighted on overflow so a pathological
765/// caller can't crash the aggregator.
766pub fn aggregate_samples_weighted(pairs: &[(f64, usize)], kind: MetricKind) -> Option<f64> {
767 let finite: Vec<(f64, usize)> = pairs
768 .iter()
769 .copied()
770 .filter(|(x, _)| x.is_finite())
771 .collect();
772 if finite.is_empty() {
773 return None;
774 }
775 let values: Vec<f64> = finite.iter().map(|(x, _)| *x).collect();
776 aggregate_finite(&values, |i| finite[i].1, kind)
777}
778
779/// Inner fold shared by [`aggregate_samples`] (uniform weights)
780/// and [`aggregate_samples_weighted`] (caller-supplied weights).
781/// `weight_for(i)` returns the weight for the i-th element of
782/// `finite`; callers either pass `|_| 1` (unweighted) or a
783/// closure that reads from their pair vec (weighted). Pre-filtered
784/// `finite` carries only NaN-free values so the closure indexes
785/// into a known-good vec without risking shape drift.
786fn aggregate_finite(
787 finite: &[f64],
788 weight_for: impl Fn(usize) -> usize,
789 kind: MetricKind,
790) -> Option<f64> {
791 if finite.is_empty() {
792 return None;
793 }
794 Some(match kind {
795 // Counter (cumulative-since-boot, cross-RUN flat sum) and
796 // DeltaSum (each sample already a per-read delta) both reduce to
797 // a plain sum of the finite samples here; they differ only in
798 // the PER-PHASE path (Counter last-minus-first vs DeltaSum sum —
799 // see aggregate_samples_for_phase).
800 MetricKind::Counter | MetricKind::DeltaSum => finite.iter().sum(),
801 // PerPhaseDeltaSum at the CROSS-RUN fold: each contributor is one run's
802 // already-summed per-phase total, so runs fold by the UNWEIGHTED
803 // arithmetic mean over the runs that emitted the key — `Σ / len`, the
804 // same shape as the Distribution / WorstLowest cross-run mean below and
805 // deliberately NOT weighted by `run_sample_count`. The CROSS-PHASE sum
806 // that builds each run's total is done directly in
807 // `crate::assert::populate_run_ext_metrics_from_phases`, which does NOT
808 // route this kind through `aggregate_finite`, so this arm only ever runs
809 // at the cross-RUN ext fold.
810 MetricKind::PerPhaseDeltaSum => finite.iter().sum::<f64>() / (finite.len() as f64),
811 // Distribution Worst (peak run-delay): the cross-RUN fold is MAX
812 // so the high-water peak survives, distinct from the MEAN-folded
813 // percentile / CV / mean reductions below. (WITHIN-RUN no
814 // derived kind reaches here — `is_derived` skips every one at
815 // the per-phase reducers; this arm only fires at the cross-RUN ext
816 // fold in `group_and_average_by`.) Matched before the general
817 // `Distribution { .. }` mean arm so Worst takes MAX, not MEAN.
818 MetricKind::Distribution {
819 reduction: SampleReduction::Worst,
820 ..
821 } => finite.iter().copied().fold(f64::NEG_INFINITY, f64::max),
822 // Cross-RUN MEAN fold of the remaining Distribution reductions (p99 /
823 // median / CV / mean run-delay) and every WorstLowest selector: each
824 // per-run value is itself a within-run pooled reduction or a
825 // lowest-wins selector, NOT a monitor-sampled gauge, so the cross-RUN
826 // fold is an UNWEIGHTED arithmetic mean — `sum / finite.len()`, i.e.
827 // over the runs that EMITTED a finite value for the key. This matches
828 // the unweighted-mean SHAPE of the surviving typed siblings
829 // (spread, migration_ratio), but its
830 // divisor is the present-finite-contributor count, NOT the typed path's
831 // `sum / passes_observed`: a passing run that omitted the key (absent /
832 // dropped-non-finite ext entry) is EXCLUDED from the mean rather than
833 // folded in as 0.0 — the deliberate no-false-zero improvement the ext
834 // relocation buys (the old typed field defaulted a no-data run to 0.0).
835 // Weighting by `run_sample_count` (the MONITOR capture count) would
836 // weight by an unrelated population AND silently zero-weight a
837 // monitor-off run, so it is deliberately NOT used here. (WITHIN-RUN
838 // these never reach here — `is_derived` skips them at the per-phase
839 // reducers; this arm only fires at the cross-RUN ext fold in
840 // `group_and_average_by`.)
841 //
842 // EXTREMUM ASYMMETRY (on the record, ratified): every WorstLowest
843 // selector is a within-run lowest-wins ("worst cgroup") value yet folds
844 // cross-RUN by this MEAN, NOT by an extremum — UNLIKE worst_run_delay_us
845 // (SampleReduction::Worst), whose dedicated MAX arm above preserves the
846 // peak-of-peaks. Both reproduce the deleted typed cross-RUN folds
847 // exactly: run-delay is a peak detector (MAX), the iteration
848 // efficiencies are a starvation-floor cohort statistic (MEAN). Aligning
849 // WorstLowest to an extremum (a MIN arm gated on HigherBetter) would be
850 // a future product decision, tracked separately, not a Stage-1 fix.
851 //
852 // HYBRID caveat (sharpest for CV): a cross-RUN value here is a
853 // mean-of-per-run-reductions, NOT a reduction recomputed over the
854 // combined raw set — the raw samples do not survive cross-RUN (phases
855 // are dropped), so there is no union to re-pool. For p99 / median /
856 // mean run-delay this mean-of-summaries is a defensible cohort
857 // statistic; for worst_wake_latency_cv it is a mean-of-ratios (the
858 // fold-of-ready-made-ratios shape the Rate kind exists to avoid), not a
859 // pooled CV — accepted here only because no combined set exists to
860 // recompute over, and it reproduces the deleted typed path's shape
861 // exactly. See [`MetricKind::Distribution`].
862 MetricKind::Distribution { .. }
863 | MetricKind::WorstLowest { .. }
864 | MetricKind::WakeLatencyTailRatio
865 | MetricKind::WorstCrossNodeRatio => finite.iter().sum::<f64>() / (finite.len() as f64),
866 MetricKind::Gauge(GaugeAgg::Avg) => {
867 // Weighted mean: sum(v * w) / sum(w). Uniform-weight
868 // callers (aggregate_samples) reduce to arithmetic
869 // mean per weight_for == |_| 1. Zero total weight
870 // degenerates to the unweighted mean rather than
871 // dividing by zero; mirrors `merge_metric_values` at
872 // `crate::assert::merge_matched_phase_buckets` per
873 // single-source-of-truth.
874 //
875 // `checked_add` on the running weight sum so a
876 // pathological caller (huge per-RUN sample counts
877 // across many runs) saturates to MAX rather than
878 // wrapping silently in release. On overflow we
879 // collapse to the unweighted-mean fallback so the
880 // returned value stays plausible.
881 let total_weight: usize = finite
882 .iter()
883 .enumerate()
884 .try_fold(0usize, |acc, (i, _)| acc.checked_add(weight_for(i)))
885 .unwrap_or(0);
886 if total_weight == 0 {
887 finite.iter().sum::<f64>() / (finite.len() as f64)
888 } else {
889 finite
890 .iter()
891 .enumerate()
892 .map(|(i, x)| *x * (weight_for(i) as f64))
893 .sum::<f64>()
894 / (total_weight as f64)
895 }
896 }
897 MetricKind::Gauge(GaugeAgg::Last) | MetricKind::Timestamp => {
898 *finite.last().expect("non-empty by check above")
899 }
900 MetricKind::Gauge(GaugeAgg::Max) | MetricKind::Peak => {
901 finite.iter().copied().fold(f64::NEG_INFINITY, f64::max)
902 }
903 // A Rate is derived from its components by `derive_rate_metrics`,
904 // never reduced from a single sample slice (one slice cannot
905 // express Σnum/Σdenom). EVERY aggregation path skips Rate before
906 // reaching the reducers: `aggregate_samples_for_phase` returns
907 // None, and the per-phase build, the cross-phase merge, and both
908 // cross-RUN reducers skip Rate keys then re-derive via
909 // `derive_rate_metrics`. So reaching here is a routing bug.
910 MetricKind::Rate { .. } => unreachable!(
911 "MetricKind::Rate must be derived via derive_rate_metrics, \
912 not reduced from a sample slice"
913 ),
914 // PerPhase is derived post-merge by derive_phase_metrics (into
915 // PhaseBucket.metrics and/or PhaseCgroupStats::metrics) and is gated out
916 // of the cross-RUN ext fold (fold_ext_metrics) + the within-run reducers
917 // (is_derived), so it never reaches a sample-slice reduction. Reaching
918 // here is a routing bug (the gate or is_derived was bypassed).
919 MetricKind::PerPhase => unreachable!(
920 "MetricKind::PerPhase is derived by derive_phase_metrics, \
921 not reduced from a sample slice"
922 ),
923 // PerRunDistribution is produced run-level by
924 // populate_run_pooled_schbench_distribution / populate_run_pooled_taobench_distribution
925 // (union of the per-phase PlatStats histograms) and is gated out of BOTH
926 // the within-run reducers (is_derived) AND the cross-RUN ext fold
927 // (fold_ext_metrics skip) — its only consumer is noise_findings reading the
928 // per-run scalar. So it never reaches a sample-slice reduction; reaching
929 // here is a routing bug.
930 MetricKind::PerRunDistribution => unreachable!(
931 "MetricKind::PerRunDistribution is produced by \
932 populate_run_pooled_schbench_distribution / populate_run_pooled_taobench_distribution \
933 and noise-compared per-run, not reduced from a sample slice"
934 ),
935 })
936}
937
938/// Per-phase metric reduction with the correct semantic per
939/// [`MetricKind`].
940///
941/// Counter kinds bypass [`aggregate_samples`]'s flat-run `sum`
942/// (which is correct for cross-RUN aggregation, but wrong for
943/// cumulative-since-boot per-phase data — summing 10 samples at
944/// `[100, 150, 175, ...]` yields ~425 instead of the per-phase
945/// delta `175 - 100 = 75`) and route through
946/// [`phase_counter_delta`] instead. All other kinds use
947/// [`aggregate_samples`] verbatim, which is correct for them
948/// (Gauge avg/last/max, Peak max, Timestamp last, and DeltaSum — whose
949/// samples are ALREADY per-read deltas, so the per-phase reduction is
950/// the sum of the in-phase deltas, NOT a last-minus-first that would
951/// difference two deltas into nonsense).
952///
953/// `samples` are the per-Sample readings of `metric` collected
954/// over one phase's window of
955/// [`crate::scenario::sample::Sample`]s via `MetricDef::read_sample`
956/// once that helper is wired through.
957/// Returns `None` when every reading was `None` / `NaN`.
958///
959/// Live caller: [`crate::assert::build_phase_buckets`] folds
960/// per-phase sample slices through this entry point and the
961/// result lands on [`crate::assert::PhaseBucket::metrics`]; the
962/// host-side `evaluate_vm_result` at `src/test_support/eval/mod.rs`
963/// is the consumer that drives the call.
964pub fn aggregate_samples_for_phase(metric: &MetricDef, samples: &[f64]) -> Option<f64> {
965 match metric.kind {
966 MetricKind::Counter => phase_counter_delta(samples),
967 // Derived kinds (every `is_derived()`: Rate / Distribution / WorstLowest /
968 // WakeLatencyTailRatio / WorstCrossNodeRatio / PerPhase / PerRunDistribution)
969 // have no samples
970 // of their own: their value is produced by a post-pass
971 // (`derive_rate_metrics` / `crate::assert::populate_run_distribution_metrics`)
972 // from pooled components, not reduced from a per-phase slice. Return
973 // None so the build loop inserts no key here.
974 k if k.is_derived() => None,
975 _ => aggregate_samples(samples, metric.kind),
976 }
977}
978
979/// Per-phase reduction for [`MetricKind::Counter`]: compute the
980/// last finite sample minus the first finite sample, clamping
981/// negative results (counter reset across a scheduler restart)
982/// to 0 and emitting a `tracing::warn!` so the reset is visible
983/// in stderr. Mirrors the existing
984/// `crate::monitor`-side counter-delta clamp pattern used
985/// when reducing cumulative kernel counters across boundaries
986/// for the same reset-detection reason.
987///
988/// Edge cases (sentinel-free absent-vs-measured-zero):
989/// - 0 or 1 finite samples -> `None`. A delta is UNMEASURABLE from
990/// fewer than two points; absence here is distinct from a measured
991/// zero. The renderer's has-data signal is `PhaseBucket::sample_count`
992/// (see `expect_metric`), NOT this value, so absence loses no
993/// diagnostic. (Previously a 1-sample phase returned a phantom
994/// `Some(0.0)` that made a per-phase Counter claim read 0 even when
995/// the phase fired plenty — only one freeze landed.)
996/// - 2+ finite samples -> `Some(max(0.0, last - first))` (equal
997/// endpoints give a REAL `Some(0.0)`: the counter did not advance).
998///
999/// Live caller: [`aggregate_samples_for_phase`] dispatches the
1000/// Counter variant through this entry point.
1001pub fn phase_counter_delta(samples: &[f64]) -> Option<f64> {
1002 let finite: Vec<f64> = samples.iter().copied().filter(|x| x.is_finite()).collect();
1003 match finite.as_slice() {
1004 // 0 or 1 finite samples: a delta is unmeasurable from fewer than two
1005 // points -> None (sentinel-free contract). The 2+-equal case below
1006 // still yields a real Some(0.0).
1007 [] | [_] => None,
1008 [first, .., last] => {
1009 let delta = *last - *first;
1010 if delta < 0.0 {
1011 tracing::warn!(
1012 first = *first,
1013 last = *last,
1014 "phase_counter_delta: counter reset detected (last < first); clamping to 0"
1015 );
1016 Some(0.0)
1017 } else {
1018 Some(delta)
1019 }
1020 }
1021 }
1022}
1023
1024/// Derive every registered [`MetricKind::Rate`] metric in `metrics`
1025/// from its already-present numerator / denominator component values:
1026/// `metrics[rate] = metrics[numerator] / metrics[denominator]`.
1027///
1028/// This is the SOLE producer of a Rate metric's value. It runs as a
1029/// post-pass at aggregation sites where the components co-locate: per-phase
1030/// reduction and carrier derivation, cross-phase bucket merge, cross-run
1031/// ext-metric reduction, and cross-cgroup pooled re-pools
1032/// (`crate::assert::populate_run_pooled_iteration_rate`, run
1033/// post-`merge` at the eval layer to re-pool `iteration_rate` across a
1034/// run's cgroups, plus `crate::assert::populate_run_pooled_taobench` and
1035/// `crate::assert::populate_run_pooled_schbench` for the taobench/schbench
1036/// whole-run Rates). At each, the components are
1037/// pooled FIRST by their own kinds (a `Counter` numerator summed), then
1038/// the rate is re-derived — so for `Counter / Counter` the result is
1039/// `Σnumerator / Σdenominator`, the correct re-pool rather than a mean of
1040/// ready-made ratios. (The cross-CGROUP `AssertResult::merge` ext-metrics
1041/// fold itself uses worst-case polarity and is NOT a derive site — the
1042/// pooled re-pool above runs separately after it; see [`MetricKind::Rate`].)
1043///
1044/// A rate is skipped (its key left absent) when either component key is
1045/// missing, the denominator is zero, or either component is non-finite —
1046/// keeping an absent rate distinct from a real `0.0`.
1047///
1048/// INVARIANT: a producer must co-insert both components from the same
1049/// observation (both-or-neither per map). A partial pair could derive a
1050/// cross-paired rate and is never valid.
1051pub(crate) fn derive_rate_metrics(metrics: &mut std::collections::BTreeMap<String, f64>) {
1052 derive_rate_metrics_from(
1053 metrics,
1054 METRICS.iter().filter_map(|m| match m.kind {
1055 MetricKind::Rate {
1056 numerator,
1057 denominator,
1058 } => Some((m.name, numerator, denominator)),
1059 _ => None,
1060 }),
1061 );
1062}
1063
1064/// Inner of [`derive_rate_metrics`] taking the rate specs explicitly as
1065/// `(name, numerator, denominator)` so the derivation math is
1066/// unit-testable without a registered Rate metric in [`METRICS`].
1067pub(crate) fn derive_rate_metrics_from<'a>(
1068 metrics: &mut std::collections::BTreeMap<String, f64>,
1069 rates: impl Iterator<Item = (&'a str, &'a str, &'a str)>,
1070) {
1071 for (name, numerator, denominator) in rates {
1072 let (Some(num), Some(den)) = (
1073 metrics.get(numerator).copied(),
1074 metrics.get(denominator).copied(),
1075 ) else {
1076 continue;
1077 };
1078 if num.is_finite() && den.is_finite() && den != 0.0 {
1079 // Guard the QUOTIENT too: a finite num / finite tiny den can
1080 // overflow to +/-inf. Insert only a finite rate so an absent
1081 // rate stays distinct from a real value (no inf in the map).
1082 let rate = num / den;
1083 if rate.is_finite() {
1084 metrics.insert(name.to_string(), rate);
1085 }
1086 }
1087 }
1088}
1089
1090impl MetricDef {
1091 /// Read this metric's value from `row`. Consults the
1092 /// accessor first (for built-in `GauntletRow` fields) and
1093 /// falls back to `row.ext_metrics[self.name]` when the
1094 /// accessor returns `None`.
1095 pub fn read(&self, row: &GauntletRow) -> Option<f64> {
1096 (self.accessor)(row).or_else(|| row.ext_metrics.get(self.name).copied())
1097 }
1098
1099 /// Read this metric's value from a single
1100 /// [`crate::scenario::sample::Sample`] — the per-sample
1101 /// analogue of [`Self::read`] used by the per-phase
1102 /// aggregator to fold a window of samples into one
1103 /// [`crate::assert::PhaseBucket`] value per metric.
1104 ///
1105 /// Returns `None` for metrics that cannot be derived from a
1106 /// single-sample shape: most ktstr metrics are computed host-side
1107 /// (cross-CPU / cross-cgroup folds, run-level distributional
1108 /// re-pools, or monitor-axis windowing), not from one sample —
1109 /// `worst_spread`, `worst_gap_ms`, `worst_migration_ratio`,
1110 /// `max_imbalance_ratio`, the `worst_*_wake_latency_*` /
1111 /// `worst_mean_run_delay_us` / `worst_run_delay_us` distributions,
1112 /// `worst_iterations_per_worker` / `worst_iterations_per_cpu_sec`,
1113 /// `worst_page_locality`, `worst_cross_node_migration_ratio`,
1114 /// `worst_wake_latency_tail_ratio` — and have no single-sample
1115 /// reading.
1116 ///
1117 /// Wired per-sample arms (return `Some`): `max_dsq_depth` /
1118 /// `avg_dsq_depth` from `sample.snapshot`'s DSQ-walker,
1119 /// `total_fallback` / `total_keep_last` from its SCX events
1120 /// region, and the IRQ/steal cross-CPU sums `total_hardirqs`,
1121 /// `total_softirq_net_rx` / `total_softirq_net_tx` /
1122 /// `total_softirq_timer` / `total_softirq_sched`,
1123 /// `total_irq_time_ns`, `total_softirq_time_ns`, and
1124 /// `total_steal_time_ns` from its `per_cpu_time`. Every other
1125 /// registered metric falls to `_ => None`
1126 /// here, for one of three reasons: (1) it is a MONITOR-axis
1127 /// signal with no guest-`Snapshot` shape (`stuck_count`,
1128 /// `max_imbalance_ratio`, `avg_imbalance_ratio`) — folded
1129 /// per-phase from `MonitorSample` windowing in
1130 /// [`crate::assert::build_phase_buckets`], NOT from read_sample;
1131 /// (2) it has no per-sample source yet (`total_migrations`,
1132 /// `total_iterations` — per-task guest counters not captured per
1133 /// tick); or (3) it is a run-level metric with no single-sample
1134 /// reading (the `worst_*` family above).
1135 /// [`crate::stats::aggregate_samples_for_phase`] surfaces an
1136 /// all-None reduction as a `None` bucket entry — distinct from
1137 /// `Some(0.0)` (a real zero) — so the bucket renderer can paint
1138 /// "no data" vs "real zero" distinctly without losing information.
1139 ///
1140 /// Live caller: [`crate::assert::build_phase_buckets`] calls
1141 /// `read_sample` once per [`crate::stats::METRICS`] entry per
1142 /// sample to collect the per-sample readings the per-phase
1143 /// aggregator folds. The host-side `evaluate_vm_result` at
1144 /// `src/test_support/eval/mod.rs` drives the chain.
1145 pub fn read_sample(&self, sample: &crate::scenario::sample::Sample<'_>) -> Option<f64> {
1146 // Per-metric dispatch by registry name. Only the metrics
1147 // whose value is genuinely a per-sample reading are wired;
1148 // every other entry in the METRICS registry is
1149 // cross-cgroup folds or run-level distributional re-pools
1150 // computed host-side at `evaluate_vm_result` time
1151 // (worst-spread / worst-gap-ms fold; the
1152 // `worst_*_wake_latency_*` distributions + worst-iterations-per-
1153 // worker efficiencies re-pool) and have no single-sample
1154 // equivalent —
1155 // they fall through to None below and the phase
1156 // aggregator paints them as absent bucket entries
1157 // (distinct from a real zero — sentinel-free contract).
1158 match self.name {
1159 // BPF dsq-state walker captures per-DSQ depth at the
1160 // freeze instant. `local_dsq_depth` is the per-CPU
1161 // local DSQ; take max across CPUs because the metric
1162 // is Peak-kind ("worst depth this instant"). DsqState
1163 // sets `origin = "local cpu N"` for local DSQs (see
1164 // src/monitor/scx_walker.rs `DsqState::origin`); the
1165 // filter pins the metric to the local-DSQ class so
1166 // global / bypass / user DSQs do not pollute the
1167 // reading.
1168 "max_dsq_depth" => sample
1169 .snapshot
1170 .dsq_states()
1171 .iter()
1172 .filter(|d| d.origin.starts_with("local cpu "))
1173 .map(|d| u64::from(d.nr))
1174 .max()
1175 .map(|v| v as f64),
1176 // Per-sample arithmetic mean of the same local-CPU
1177 // DSQ depth readings `max_dsq_depth` walks. Returns
1178 // `None` when no local DSQs are present so the bucket
1179 // renderer can distinguish "no data" from "real zero"
1180 // (sentinel-free contract); a zero-population set
1181 // never enters the mean.
1182 "avg_dsq_depth" => {
1183 let locals: Vec<f64> = sample
1184 .snapshot
1185 .dsq_states()
1186 .iter()
1187 .filter(|d| d.origin.starts_with("local cpu "))
1188 .map(|d| u64::from(d.nr) as f64)
1189 .collect();
1190 if locals.is_empty() {
1191 None
1192 } else {
1193 Some(locals.iter().sum::<f64>() / locals.len() as f64)
1194 }
1195 }
1196 // Cumulative `select_cpu_fallback` counter at the
1197 // freeze instant. The host's event-counter walker
1198 // builds a per-tick timeline of CPU-summed counters
1199 // (`EventCounterSample` at src/monitor/dump/mod.rs:477);
1200 // `.last()` gives the cumulative reading at the most
1201 // recent tick within this freeze's capture window.
1202 // Counter-kind reduction folds `last - first` across
1203 // the phase's sample window, yielding the per-phase
1204 // delta (the genuine "how many fallbacks fired during
1205 // THIS phase").
1206 "total_fallback" => sample
1207 .snapshot
1208 .event_counter_timeline()
1209 .last()
1210 .map(|e| e.select_cpu_fallback as f64),
1211 // Cumulative `dispatch_keep_last` counter; same
1212 // per-tick timeline source as `total_fallback`. Same
1213 // Counter-kind reduction semantic; per-phase delta
1214 // surfaces the keep-last count for THIS phase.
1215 "total_keep_last" => sample
1216 .snapshot
1217 .event_counter_timeline()
1218 .last()
1219 .map(|e| e.dispatch_keep_last as f64),
1220 // IRQ observability: cross-CPU SUM of the cumulative per-CPU
1221 // counter at this freeze. Counter kind takes the per-phase
1222 // last-minus-first (phase_counter_delta) over these per-freeze
1223 // totals. The per-CPU set is fixed across freezes (every CPU is
1224 // present every freeze), so the cross-CPU sum has NO task-set-change
1225 // inflation — the exact reason system_time_ns below is NOT a
1226 // read_sample arm but these are. Empty per_cpu_time -> None
1227 // (loud-absent, never a false zero). Softirq vectors index against
1228 // the compile-pinned named consts, never bare literals.
1229 "total_hardirqs" => {
1230 // saturating fold (applies to every IRQ arm below): overflow-safe
1231 // cross-CPU spatial sum of the guest per-CPU counter — a corrupt /
1232 // hostile per-CPU u64::MAX must clamp, not wrap, this per-freeze
1233 // total (the Counter delta reads it). Exact for every in-range value.
1234 let cpus = sample.snapshot.per_cpu_time();
1235 (!cpus.is_empty()).then(|| {
1236 cpus.iter()
1237 .map(|c| c.irqs_sum)
1238 .fold(0u64, u64::saturating_add) as f64
1239 })
1240 }
1241 "total_softirq_net_rx" => {
1242 let cpus = sample.snapshot.per_cpu_time();
1243 (!cpus.is_empty()).then(|| {
1244 cpus.iter()
1245 .map(|c| c.softirqs[crate::monitor::btf_offsets::SOFTIRQ_NET_RX])
1246 .fold(0u64, u64::saturating_add) as f64
1247 })
1248 }
1249 "total_softirq_net_tx" => {
1250 let cpus = sample.snapshot.per_cpu_time();
1251 (!cpus.is_empty()).then(|| {
1252 cpus.iter()
1253 .map(|c| c.softirqs[crate::monitor::btf_offsets::SOFTIRQ_NET_TX])
1254 .fold(0u64, u64::saturating_add) as f64
1255 })
1256 }
1257 "total_softirq_timer" => {
1258 let cpus = sample.snapshot.per_cpu_time();
1259 (!cpus.is_empty()).then(|| {
1260 cpus.iter()
1261 .map(|c| c.softirqs[crate::monitor::btf_offsets::SOFTIRQ_TIMER])
1262 .fold(0u64, u64::saturating_add) as f64
1263 })
1264 }
1265 "total_softirq_sched" => {
1266 let cpus = sample.snapshot.per_cpu_time();
1267 (!cpus.is_empty()).then(|| {
1268 cpus.iter()
1269 .map(|c| c.softirqs[crate::monitor::btf_offsets::SOFTIRQ_SCHED])
1270 .fold(0u64, u64::saturating_add) as f64
1271 })
1272 }
1273 "total_irq_time_ns" => {
1274 let cpus = sample.snapshot.per_cpu_time();
1275 (!cpus.is_empty()).then(|| {
1276 cpus.iter()
1277 .map(|c| c.cpustat_irq_ns)
1278 .fold(0u64, u64::saturating_add) as f64
1279 })
1280 }
1281 "total_softirq_time_ns" => {
1282 let cpus = sample.snapshot.per_cpu_time();
1283 (!cpus.is_empty()).then(|| {
1284 cpus.iter()
1285 .map(|c| c.cpustat_softirq_ns)
1286 .fold(0u64, u64::saturating_add) as f64
1287 })
1288 }
1289 "total_steal_time_ns" => {
1290 let cpus = sample.snapshot.per_cpu_time();
1291 (!cpus.is_empty()).then(|| {
1292 cpus.iter()
1293 .map(|c| c.cpustat_steal_ns)
1294 .fold(0u64, u64::saturating_add) as f64
1295 })
1296 }
1297 // `system_time_ns` / `user_time_ns` are deliberately absent
1298 // here: they are NOT read per-sample. A per-sample
1299 // cross-thread SUM followed by a Counter `last - first`
1300 // inflates whenever the captured task set changes between
1301 // freezes — a task carrying a large cumulative counter that
1302 // appears only in a LATER sample dumps its entire pre-phase
1303 // history into the delta. They are injected post-hoc as a
1304 // per-thread-GROUP delta (each tgid's first-seen-to-last-seen
1305 // `thread_group_cputime`) by
1306 // [`crate::assert::phase_group_cpu_delta`], which subtracts
1307 // each group's own first-seen total and so bounds the result
1308 // by wall-clock × cores. Still observer-free — that injector
1309 // reads the same frozen `task_struct` enrichments.
1310 //
1311 // Every other metric stays None. The 16 host-only
1312 // names (full list in the doc comment above) compute
1313 // cross-cgroup folds at `evaluate_vm_result` time and
1314 // have no per-sample equivalent until a per-cgroup
1315 // per-sample capture path lands; surfacing them via a
1316 // synthetic single-sample value would falsify the
1317 // per-phase trajectory the bucket renderer paints.
1318 _ => None,
1319 }
1320 }
1321
1322 /// Returns `true` when a metric INCREASING is the bad direction:
1323 /// [`LowerBetter`](crate::test_support::Polarity::LowerBetter),
1324 /// [`TargetValue`](crate::test_support::Polarity::TargetValue), and the
1325 /// conservative [`Unknown`](crate::test_support::Polarity::Unknown)
1326 /// default (an unclassified metric is treated as higher-is-worse so a
1327 /// real regression in it is still caught). `false` for
1328 /// [`HigherBetter`](crate::test_support::Polarity::HigherBetter) and
1329 /// [`Informational`](crate::test_support::Polarity::Informational).
1330 ///
1331 /// This is the cross-cgroup FOLD direction (max-vs-min when merging
1332 /// per-cgroup `ext_metrics`, see [`crate::assert::AssertResult::merge`])
1333 /// and the timeline-narrative direction. The PERF-DELTA VERDICT path
1334 /// uses [`classify_direction`](Self::classify_direction) instead, which
1335 /// returns `None` for `Informational` so it never gates. `Informational`
1336 /// folding as `false` (min) here is harmless: the system-wide monitor
1337 /// counters that carry it are row-level and never hit the per-cgroup
1338 /// merge.
1339 pub const fn higher_is_worse(&self) -> bool {
1340 use crate::test_support::Polarity;
1341 matches!(
1342 self.polarity,
1343 Polarity::LowerBetter | Polarity::TargetValue(_) | Polarity::Unknown
1344 )
1345 }
1346
1347 /// Verdict direction for the perf-delta comparison:
1348 /// - `Some(true)` — an INCREASE is a regression (`LowerBetter` /
1349 /// `TargetValue` / the conservative `Unknown` default),
1350 /// - `Some(false)` — a DECREASE is a regression (`HigherBetter`),
1351 /// - `None` — [`Informational`](crate::test_support::Polarity::Informational):
1352 /// directionless; the comparison records and displays it but NEVER
1353 /// classifies it as regression/improvement and it NEVER affects the
1354 /// exit code.
1355 ///
1356 /// The verdict sites in [`compare_partitions`] branch on the `Option`:
1357 /// `None` => informational, `Some(hiw)` => the dual-gated
1358 /// regression/improvement split. This matches
1359 /// [`higher_is_worse`](Self::higher_is_worse) for every variant EXCEPT
1360 /// `Informational` (there `false`/min-fold, here `None`/never-gated) —
1361 /// the deliberate split between "fold needs a direction" and "verdict
1362 /// must stay neutral".
1363 pub const fn classify_direction(&self) -> Option<bool> {
1364 self.polarity.classify_direction()
1365 }
1366
1367 /// Whether this metric's value can reach the AGGREGATE findings the
1368 /// perf-delta failure gate reads — the cross-run scalar compare
1369 /// ([`compare_partitions`], `noise_adjust == false`) or the per-run noise
1370 /// compare ([`compare_partitions_noise`], `noise_adjust == true`). `false`
1371 /// for names whose value never lands on a compared row in that mode, so a
1372 /// `--must-fail` gate on one could never fire (a silent no-op):
1373 /// - [`MetricKind::PerPhase`]: `accessor` is `None`, it has no run-level
1374 /// producer, and it is gated out of the cross-run ext fold — its value
1375 /// lives only in per-phase carriers, never on a `GauntletRow`, so it
1376 /// reaches NEITHER compare. Always `false`.
1377 /// - [`MetricKind::PerRunDistribution`]: `accessor` is `None` and it is
1378 /// gated out of the cross-run ext fold, so it is absent on the scalar
1379 /// compare's cross-run-folded rows — but each run carries its own
1380 /// `*_whole` scalar that [`compare_partitions_noise`] reads, so it CAN
1381 /// gate under `--noise-adjust`. `noise_adjust`-only.
1382 ///
1383 /// Every other kind reaches both compares; whether it then produces a
1384 /// *regression* (vs an informational finding) is a separate
1385 /// direction question — see [`classify_direction`](Self::classify_direction).
1386 pub const fn gates_aggregate(&self, noise_adjust: bool) -> bool {
1387 match self.kind {
1388 MetricKind::PerPhase => false,
1389 MetricKind::PerRunDistribution => noise_adjust,
1390 _ => true,
1391 }
1392 }
1393}
1394
1395/// Unified metric registry covering all built-in and extensible metrics.
1396///
1397/// The comparison pipeline uses `higher_is_worse` to determine regression
1398/// direction, `default_abs`/`default_rel` for dual-gate significance
1399/// thresholds, and `display_unit` for formatted output. Per-test
1400/// assertion overrides can still use their own thresholds; this registry
1401/// is the source of truth for polarity and display.
1402///
1403/// `AssertResult::merge` consults `higher_is_worse` via [`metric_def`]
1404/// when folding per-cgroup `ext_metrics` into the scenario-level worst
1405/// case: `true` takes max, `false` takes min. Unknown names (not in
1406/// this registry) default to max; register a `MetricDef` here before
1407/// relying on min-polarity merge. The comparison system
1408/// ([`compare_partitions`]) uses `higher_is_worse` for delta direction.
1409///
1410/// # Metric-name triples (registry / field / DataFrame column)
1411///
1412/// Each metric is referenced by three names across the pipeline.
1413/// The registry name is the stable surface — sidecars, CI gates,
1414/// and `cargo ktstr perf-delta` output all quote it verbatim —
1415/// and cannot be renamed without silently invalidating downstream
1416/// consumers. The field name on [`GauntletRow`] and the polars
1417/// DataFrame column name are internal; they are kept terse and
1418/// match each other, but diverge from the registry name where
1419/// the domain-level wording adds context (`worst_*`, `total_*`,
1420/// `max_*`) that would be noise on an already-qualified field.
1421/// Nine divergent triples:
1422///
1423/// | Registry (`MetricDef.name`) | `GauntletRow` field | DataFrame column |
1424/// |---|---|---|
1425/// | `worst_spread` | `spread` | `spread` |
1426/// | `worst_gap_ms` | `gap_ms` | `gap_ms` |
1427/// | `total_migrations` | `migrations` | `migrations` |
1428/// | `worst_migration_ratio` | `migration_ratio` | `migration_ratio` |
1429/// | `max_imbalance_ratio` | `imbalance_ratio` | `imbalance` |
1430/// | `max_dsq_depth` | `max_dsq_depth` | `dsq_depth` |
1431/// | `stuck_count` | `stuck_count` | `stuck` |
1432/// | `total_fallback` | `fallback_count` | `fallback` |
1433/// | `total_keep_last` | `keep_last_count` | `keep_last` |
1434///
1435/// One of the remaining metrics in [`METRICS`] has matching
1436/// registry / field / DataFrame column names backed by a typed
1437/// `GauntletRow` field (`total_iterations`) and is not listed — no
1438/// translation to document.
1439///
1440/// The ten wake-latency / run-delay / iteration-efficiency / NUMA roll-ups
1441/// (`worst_p99_wake_latency_us`, `worst_median_wake_latency_us`,
1442/// `worst_wake_latency_cv`, `worst_mean_run_delay_us`,
1443/// `worst_run_delay_us`, `worst_iterations_per_worker`,
1444/// `worst_iterations_per_cpu_sec`, `worst_wake_latency_tail_ratio`,
1445/// `worst_page_locality`, `worst_cross_node_migration_ratio`) are
1446/// DERIVED kinds ([`MetricKind::Distribution`] / [`MetricKind::WorstLowest`]
1447/// / [`MetricKind::WakeLatencyTailRatio`] / [`MetricKind::WorstCrossNodeRatio`])
1448/// with NO typed `GauntletRow`
1449/// field: their accessors are `|_| None` and
1450/// `crate::assert::populate_run_distribution_metrics` re-pools their value
1451/// into `ext_metrics` post-merge, so [`MetricDef::read`] reads them through
1452/// the ext fallback.
1453///
1454/// `worst_` naming convention: it is the codebase-wide prefix for a
1455/// cross-cgroup roll-up, independent of polarity and of HOW the roll-up is
1456/// formed. Polarity-directional selectors (`worst_spread`, and the derived
1457/// `worst_cross_node_migration_ratio`, both LowerBetter → max) and
1458/// [`MetricKind::WorstLowest`] (`worst_page_locality` +
1459/// `worst_iterations_per_*`, None-aware lowest-wins where a measured 0.0
1460/// wins) both surface the most problematic cgroup; whereas
1461/// [`MetricKind::Distribution`] (`worst_p99_wake_latency_us` etc.) is the
1462/// POOLED cross-cgroup distribution over the combined sample set, NOT a
1463/// per-cgroup selection — here `worst_` is retained for sidecar /
1464/// DataFrame / CI-gate name stability rather than literal accuracy. A
1465/// `lowest_*` rename of the HigherBetter selectors was weighed and
1466/// rejected as a high-churn rename across sidecars / DataFrames / CI gates
1467/// for no readability gain.
1468///
1469/// Quoting the matching list instead of a bare count avoids
1470/// silent drift on rename: a metric whose registry / field /
1471/// column names diverge belongs in the table above, while a
1472/// matching triple belongs in this paragraph; a future rename
1473/// that forgets to migrate the metric across the boundary
1474/// surfaces here as a stale list rather than a wrong count.
1475///
1476/// Consumers that cross the registry / DataFrame boundary should
1477/// go through [`MetricDef::read`] / the accessor closure rather
1478/// than hand-translating by string. The four-name mapping for
1479/// `worst_spread` specifically is documented in detail on the
1480/// [`GauntletRow::spread`] field (adds the
1481/// [`ScenarioStats::worst_spread`](crate::assert::ScenarioStats::worst_spread)
1482/// upstream source as a fourth name).
1483/// Registry names for the schbench per-phase metrics ([`MetricKind::PerPhase`]).
1484/// Shared by the [`METRICS`] entries below and the schbench per-phase derivation
1485/// (`crate::assert::derive_phase_metrics`) so the registered name and
1486/// the key the derivation writes into `crate::assert::PhaseBucket::metrics` are
1487/// one source of truth. Latency keys are µs (the unit `plat` buckets in);
1488/// sched-delay keys are µs (converted from ns at derivation); loop_count is a
1489/// bare count.
1490pub(crate) const SCHBENCH_WAKEUP_P50_US: &str = "wakeup_p50_latency_us";
1491pub(crate) const SCHBENCH_WAKEUP_P90_US: &str = "wakeup_p90_latency_us";
1492pub(crate) const SCHBENCH_WAKEUP_P99_US: &str = "wakeup_p99_latency_us";
1493pub(crate) const SCHBENCH_WAKEUP_P999_US: &str = "wakeup_p999_latency_us";
1494pub(crate) const SCHBENCH_REQUEST_P50_US: &str = "request_p50_latency_us";
1495pub(crate) const SCHBENCH_REQUEST_P90_US: &str = "request_p90_latency_us";
1496pub(crate) const SCHBENCH_REQUEST_P99_US: &str = "request_p99_latency_us";
1497pub(crate) const SCHBENCH_REQUEST_P999_US: &str = "request_p999_latency_us";
1498pub(crate) const SCHBENCH_SCHED_DELAY_MSG_US: &str = "sched_delay_msg_us";
1499pub(crate) const SCHBENCH_SCHED_DELAY_WORKER_US: &str = "sched_delay_worker_us";
1500pub(crate) const SCHBENCH_LOOP_COUNT: &str = "schbench_loop_count";
1501// schbench WHOLE-RUN Class-3 keys (loop count + role-separate run-delay gate
1502// Rates) for perf-delta --noise-adjust. Re-pooled run-level by
1503// `populate_run_pooled_schbench` from the per-phase per-cgroup
1504// `SchbenchPhaseStats` raw pairs (Σ over all phases+cgroups). The four
1505// `total_schbench_*` run-delay/pcount Counters are the rate components
1506// (RENDER_SUPPRESSED) for the two sample-weighted Σrun_delay/Σpcount gate Rates
1507// (workload-scoped siblings of the system-wide `total_run_delay_ns_per_sched`);
1508// the message and worker thread ROLES pool separately (different per-schedule
1509// wait populations). The per-phase `sched_delay_msg/worker_us` is the SAME
1510// Σrun_delay_ns/Σpcount per-schedule mean at phase scope (NOT schbench's native
1511// mean-of-per-thread-means, a separate whole-run SchbenchResult stat) and stays
1512// PerPhase display-only — only these Rates gate, no double-count.
1513// `total_schbench_loops` is the whole-run loop Counter (distinct from the
1514// per-phase `schbench_loop_count`).
1515pub(crate) const TOTAL_SCHBENCH_MSG_RUN_DELAY_NS: &str = "total_schbench_msg_run_delay_ns";
1516pub(crate) const TOTAL_SCHBENCH_MSG_PCOUNT: &str = "total_schbench_msg_pcount";
1517pub(crate) const TOTAL_SCHBENCH_WORKER_RUN_DELAY_NS: &str = "total_schbench_worker_run_delay_ns";
1518pub(crate) const TOTAL_SCHBENCH_WORKER_PCOUNT: &str = "total_schbench_worker_pcount";
1519pub(crate) const TOTAL_SCHBENCH_LOOPS: &str = "total_schbench_loops";
1520// CPU-SECOND throughput pair: `total_schbench_worker_cpu_sec` is the whole-run
1521// Σ worker CLOCK_THREAD_CPUTIME_ID window (Counter component,
1522// RENDER_SUPPRESSED; message-thread CPU excluded, mirroring schbench's
1523// Σ worker runtimes) and `schbench_total_loops_per_cpu_sec` the derived Rate
1524// (Σloops / Σworker CPU-sec) — completed cycles per CPU-second the workers
1525// actually received. Dilation-safe by construction (host preemption inflates
1526// wall, not CPU); the wall picture reconstructs as `rate / D` via the
1527// sidecar's `host_dilation`. The per-phase sibling is
1528// `schbench_loops_per_cpu_sec` (PerPhase, from the same carrier field).
1529pub(crate) const TOTAL_SCHBENCH_WORKER_CPU_SEC: &str = "total_schbench_worker_cpu_sec";
1530pub(crate) const SCHBENCH_TOTAL_LOOPS_PER_CPU_SEC: &str = "schbench_total_loops_per_cpu_sec";
1531pub(crate) const SCHBENCH_LOOPS_PER_CPU_SEC: &str = "schbench_loops_per_cpu_sec";
1532pub(crate) const SCHBENCH_MSG_RUN_DELAY_NS_PER_SCHED: &str = "schbench_msg_run_delay_ns_per_sched";
1533pub(crate) const SCHBENCH_WORKER_RUN_DELAY_NS_PER_SCHED: &str =
1534 "schbench_worker_run_delay_ns_per_sched";
1535// schbench WHOLE-RUN distributional keys for perf-delta --noise-adjust:
1536// each per-phase percentile/min/max re-pooled run-level by
1537// `populate_run_pooled_schbench_distribution` (union of the per-phase per-cgroup
1538// PlatStats histograms, percentile re-derived over the union). MetricKind::
1539// PerRunDistribution: noise-compared per-run, NEVER cross-run folded. `*_whole`
1540// names keep them registry-distinct from the per-phase PerPhase keys above (one
1541// name = one kind). Latency LowerBetter; rps HigherBetter.
1542pub(crate) const SCHBENCH_WAKEUP_P50_US_WHOLE: &str = "wakeup_p50_latency_us_whole";
1543pub(crate) const SCHBENCH_WAKEUP_P90_US_WHOLE: &str = "wakeup_p90_latency_us_whole";
1544pub(crate) const SCHBENCH_WAKEUP_P99_US_WHOLE: &str = "wakeup_p99_latency_us_whole";
1545pub(crate) const SCHBENCH_WAKEUP_P999_US_WHOLE: &str = "wakeup_p999_latency_us_whole";
1546pub(crate) const SCHBENCH_WAKEUP_MIN_US_WHOLE: &str = "wakeup_min_latency_us_whole";
1547pub(crate) const SCHBENCH_WAKEUP_MAX_US_WHOLE: &str = "wakeup_max_latency_us_whole";
1548pub(crate) const SCHBENCH_REQUEST_P50_US_WHOLE: &str = "request_p50_latency_us_whole";
1549pub(crate) const SCHBENCH_REQUEST_P90_US_WHOLE: &str = "request_p90_latency_us_whole";
1550pub(crate) const SCHBENCH_REQUEST_P99_US_WHOLE: &str = "request_p99_latency_us_whole";
1551pub(crate) const SCHBENCH_REQUEST_P999_US_WHOLE: &str = "request_p999_latency_us_whole";
1552pub(crate) const SCHBENCH_REQUEST_MIN_US_WHOLE: &str = "request_min_latency_us_whole";
1553pub(crate) const SCHBENCH_REQUEST_MAX_US_WHOLE: &str = "request_max_latency_us_whole";
1554pub(crate) const SCHBENCH_RPS_P20_WHOLE: &str = "rps_p20_whole";
1555pub(crate) const SCHBENCH_RPS_P50_WHOLE: &str = "rps_p50_whole";
1556pub(crate) const SCHBENCH_RPS_P90_WHOLE: &str = "rps_p90_whole";
1557pub(crate) const SCHBENCH_RPS_MIN_WHOLE: &str = "rps_min_whole";
1558pub(crate) const SCHBENCH_RPS_MAX_WHOLE: &str = "rps_max_whole";
1559// taobench per-phase metric keys (the WorkType::Taobench engine's CPU-throughput + hit
1560// ratios, derived per-phase by write_taobench_scalars; MetricKind::PerPhase).
1561// total/fast CPU-throughput are HigherBetter; slow throughput + hit_ratio +
1562// hit_rate are Informational (slow throughput is a component, not a direction;
1563// the hit numbers are run-validity signals, not regression directions). The two hit keys are distinct
1564// axes: `taobench_hit_ratio` is RESPONSE-time (fast_ops / (fast_ops + slow_ops),
1565// the whole-run analog is `taobench_hit_fraction`) and `taobench_hit_rate` is
1566// COMMAND-time (1 - get_misses / get_cmds, the whole-run analog is
1567// `taobench_command_hit_rate`). Under open-loop arrival the two diverge
1568// (request-time vs response-time).
1569pub(crate) const TAOBENCH_TOTAL_OPS_PER_CPU_SEC: &str = "taobench_total_ops_per_cpu_sec";
1570pub(crate) const TAOBENCH_FAST_OPS_PER_CPU_SEC: &str = "taobench_fast_ops_per_cpu_sec";
1571pub(crate) const TAOBENCH_SLOW_OPS_PER_CPU_SEC: &str = "taobench_slow_ops_per_cpu_sec";
1572/// Response-time per-phase hit ratio: fast_ops / (fast_ops + slow_ops).
1573pub(crate) const TAOBENCH_HIT_RATIO: &str = "taobench_hit_ratio";
1574/// Command-time per-phase hit rate: 1 - get_misses / get_cmds.
1575pub(crate) const TAOBENCH_HIT_RATE: &str = "taobench_hit_rate";
1576// taobench per-phase open-loop SERVE-LATENCY percentiles (µs): the
1577// coordinated-omission serve latency distribution per phase (PerPhase,
1578// LowerBetter), pooled cross-cgroup + re-derived by `write_taobench_scalars`.
1579// Absent in closed loop (no serve samples).
1580pub(crate) const TAOBENCH_SERVE_P50_US: &str = "taobench_serve_p50_us";
1581pub(crate) const TAOBENCH_SERVE_P90_US: &str = "taobench_serve_p90_us";
1582pub(crate) const TAOBENCH_SERVE_P99_US: &str = "taobench_serve_p99_us";
1583pub(crate) const TAOBENCH_SERVE_P999_US: &str = "taobench_serve_p999_us";
1584pub(crate) const TAOBENCH_SERVE_MIN_US: &str = "taobench_serve_min_us";
1585pub(crate) const TAOBENCH_SERVE_MAX_US: &str = "taobench_serve_max_us";
1586// taobench WHOLE-RUN Rate component + Rate keys (run-level CPU-throughput + hit
1587// fraction, pooled cross-cgroup by `populate_run_pooled_taobench` and derived by
1588// `derive_rate_metrics`). Distinct from the per-phase
1589// `taobench_*_ops_per_cpu_sec` above
1590// (`MetricKind::PerPhase`, invisible to the whole-run cross-run fold): these are
1591// registered `Rate`/`Counter` METRICS so they reach perf-delta `--noise-adjust`
1592// spread. The four `total_taobench_*` Counters are the rate components (their
1593// `total_` prefix satisfies the Counter naming gate); they are
1594// `RENDER_SUPPRESSED_COMPONENTS` so the compare output shows the rates, not the
1595// raw counts.
1596pub(crate) const TOTAL_TAOBENCH_OPS: &str = "total_taobench_ops";
1597pub(crate) const TOTAL_TAOBENCH_FAST_OPS: &str = "total_taobench_fast_ops";
1598pub(crate) const TOTAL_TAOBENCH_SLOW_OPS: &str = "total_taobench_slow_ops";
1599pub(crate) const TOTAL_TAOBENCH_WALL_SEC: &str = "total_taobench_wall_sec";
1600// CPU-SECOND window: Σ client-thread CLOCK_THREAD_CPUTIME_ID (Counter
1601// component) — the DENOMINATOR of the three
1602// `taobench_*_ops_per_cpu_sec_whole` Rates
1603// below (CPU-second denominated: ops per CPU-second the client threads
1604// actually received; dilation-safe, wall reconstructs as `rate / D` or
1605// exactly as Σops / `total_taobench_wall_sec`, which stays as window
1606// evidence).
1607pub(crate) const TOTAL_TAOBENCH_CPU_SEC: &str = "total_taobench_cpu_sec";
1608pub(crate) const TAOBENCH_TOTAL_OPS_PER_CPU_SEC_WHOLE: &str =
1609 "taobench_total_ops_per_cpu_sec_whole";
1610pub(crate) const TAOBENCH_FAST_OPS_PER_CPU_SEC_WHOLE: &str = "taobench_fast_ops_per_cpu_sec_whole";
1611pub(crate) const TAOBENCH_SLOW_OPS_PER_CPU_SEC_WHOLE: &str = "taobench_slow_ops_per_cpu_sec_whole";
1612pub(crate) const TAOBENCH_HIT_FRACTION: &str = "taobench_hit_fraction";
1613// taobench WHOLE-RUN open-loop serve-latency percentiles (µs): the union of the
1614// per-phase per-cgroup serve histograms re-derived run-level
1615// (`MetricKind::PerRunDistribution` — noise-compared per-run, never cross-run
1616// folded), pooled by `populate_run_pooled_taobench_distribution`. `*_whole`
1617// names, distinct from the per-phase `taobench_serve_*_us` keys above.
1618pub(crate) const TAOBENCH_SERVE_P50_US_WHOLE: &str = "taobench_serve_p50_us_whole";
1619pub(crate) const TAOBENCH_SERVE_P90_US_WHOLE: &str = "taobench_serve_p90_us_whole";
1620pub(crate) const TAOBENCH_SERVE_P99_US_WHOLE: &str = "taobench_serve_p99_us_whole";
1621pub(crate) const TAOBENCH_SERVE_P999_US_WHOLE: &str = "taobench_serve_p999_us_whole";
1622pub(crate) const TAOBENCH_SERVE_MIN_US_WHOLE: &str = "taobench_serve_min_us_whole";
1623pub(crate) const TAOBENCH_SERVE_MAX_US_WHOLE: &str = "taobench_serve_max_us_whole";
1624// taobench WHOLE-RUN command-time hit: the request-time hit rate (distinct from
1625// the response-time `taobench_hit_fraction`; the two diverge under open-loop
1626// arrival). hits = cmds − misses, pooled cross-cgroup by
1627// `populate_run_pooled_taobench`; `taobench_command_hit_rate` = Σhits/Σcmds
1628// (`total_` Counter components satisfy the naming gate; the Rate ends in `_rate`).
1629// Whole-run ratio Rates use their rate-form name, never the `_whole` suffix
1630// (which is the PerRunDistribution marker).
1631pub(crate) const TOTAL_TAOBENCH_GET_CMDS: &str = "total_taobench_get_cmds";
1632pub(crate) const TOTAL_TAOBENCH_GET_HITS: &str = "total_taobench_get_hits";
1633pub(crate) const TAOBENCH_COMMAND_HIT_RATE: &str = "taobench_command_hit_rate";
1634// Per-phase latency min/max (schbench's `min=`/`max=` table footer,
1635// `schbench.c:579`): the per-phase PlatStats already carries them, so these are
1636// emitted from `q.min`/`q.max`. LowerBetter (a higher min/max latency is worse).
1637pub(crate) const SCHBENCH_WAKEUP_MIN_US: &str = "wakeup_min_latency_us";
1638pub(crate) const SCHBENCH_WAKEUP_MAX_US: &str = "wakeup_max_latency_us";
1639pub(crate) const SCHBENCH_REQUEST_MIN_US: &str = "request_min_latency_us";
1640pub(crate) const SCHBENCH_REQUEST_MAX_US: &str = "request_max_latency_us";
1641// Per-phase achieved wall-RPS distribution (schbench's RPS table,
1642// PLIST_FOR_RPS = 20/50/90, `schbench.c:130`) + min/max. Preserved as native
1643// benchmark diagnostics; host preemption dilutes these values, so the registry
1644// keeps them Informational and uses schbench_loops_per_cpu_sec directionally.
1645pub(crate) const SCHBENCH_RPS_P20: &str = "rps_p20";
1646pub(crate) const SCHBENCH_RPS_P50: &str = "rps_p50";
1647pub(crate) const SCHBENCH_RPS_P90: &str = "rps_p90";
1648pub(crate) const SCHBENCH_RPS_MIN: &str = "rps_min";
1649pub(crate) const SCHBENCH_RPS_MAX: &str = "rps_max";
1650
1651pub static METRICS: &[MetricDef] = &[
1652 MetricDef {
1653 // `"worst_spread"` is the wire/surface name — emitted in
1654 // sidecars, referenced by CI gates, and printed by
1655 // `cargo ktstr perf-delta`. Internally the field on
1656 // `GauntletRow` is named `spread` and the polars DataFrame
1657 // column keeps that shorter name; see the doc on
1658 // `GauntletRow.spread` for the rationale (rename-of-
1659 // registry-name is not safe because existing gate configs
1660 // match this string by value).
1661 name: "worst_spread",
1662 polarity: crate::test_support::Polarity::LowerBetter,
1663 kind: MetricKind::Gauge(GaugeAgg::Last),
1664 default_abs: 5.0,
1665 default_rel: 0.25,
1666 display_unit: "%",
1667 accessor: |r| Some(r.spread),
1668 },
1669 MetricDef {
1670 name: "worst_gap_ms",
1671 polarity: crate::test_support::Polarity::LowerBetter,
1672 kind: MetricKind::Peak,
1673 default_abs: 500.0,
1674 default_rel: 0.50,
1675 display_unit: "ms",
1676 accessor: |r| Some(r.gap_ms as f64),
1677 },
1678 MetricDef {
1679 name: "total_migrations",
1680 polarity: crate::test_support::Polarity::Informational,
1681 kind: MetricKind::Counter,
1682 default_abs: 2.0,
1683 default_rel: 0.30,
1684 display_unit: "",
1685 accessor: |r| Some(r.migrations as f64),
1686 },
1687 MetricDef {
1688 name: "worst_migration_ratio",
1689 polarity: crate::test_support::Polarity::LowerBetter,
1690 kind: MetricKind::Gauge(GaugeAgg::Last),
1691 default_abs: 0.05,
1692 default_rel: 0.20,
1693 display_unit: "",
1694 accessor: |r| Some(r.migration_ratio),
1695 },
1696 MetricDef {
1697 name: "max_imbalance_ratio",
1698 polarity: crate::test_support::Polarity::LowerBetter,
1699 kind: MetricKind::Peak,
1700 default_abs: 1.0,
1701 default_rel: 0.25,
1702 display_unit: "x",
1703 accessor: |r| Some(r.imbalance_ratio),
1704 },
1705 MetricDef {
1706 // Per-phase mean of per-tick imbalance_ratio observations
1707 // (max(nr_running) / max(1, min(nr_running)) per CPU; full-
1708 // class count). Sourced from MonitorSample (not Snapshot)
1709 // because Snapshot exposes only scx_rq.nr_running (SCX-
1710 // only) while imbalance is meaningful only across the
1711 // full per-CPU runqueue. Populated by build_phase_buckets
1712 // via per-phase MonitorSample windowing — bypasses
1713 // MetricDef::read_sample (which dispatches off
1714 // sample.snapshot only) per the data-axis split. Kind
1715 // Gauge(Avg) folds across cgroups via weighted-mean per
1716 // sample_count; Polarity::LowerBetter mirrors the Peak
1717 // sibling.
1718 name: "avg_imbalance_ratio",
1719 polarity: crate::test_support::Polarity::LowerBetter,
1720 kind: MetricKind::Gauge(GaugeAgg::Avg),
1721 default_abs: 0.5,
1722 default_rel: 0.25,
1723 display_unit: "x",
1724 accessor: |_| None,
1725 },
1726 MetricDef {
1727 name: "max_dsq_depth",
1728 polarity: crate::test_support::Polarity::LowerBetter,
1729 kind: MetricKind::Peak,
1730 default_abs: 10.0,
1731 default_rel: 0.50,
1732 display_unit: "",
1733 accessor: |r| Some(r.max_dsq_depth as f64),
1734 },
1735 MetricDef {
1736 // Per-sample mean of local-CPU DSQ depths sourced from
1737 // the BPF DSQ walker (Snapshot::dsq_states() filtered by
1738 // `origin.starts_with("local cpu ")`), reduced per phase
1739 // via the Gauge(Avg) path. The DSQ-walker axis is the
1740 // authoritative source — it reads the actual scheduler
1741 // dispatch queues. The legacy Timeline::build path
1742 // computed avg_dsq_depth from MonitorSample.CpuSnapshot.
1743 // local_dsq_depth (a per-CPU rq-level metric); the new
1744 // DSQ-walker axis is more accurate for an scx scheduler
1745 // because it observes the dispatch queue directly rather
1746 // than the rq-level reflection.
1747 //
1748 // Truncation caveat: when scx_walker hits MAX_NODES_PER_LIST
1749 // (per src/monitor/scx_walker.rs), the captured DSQs are a
1750 // prefix of the full set. The mean then shifts toward the
1751 // captured prefix's central tendency; a 64-CPU box capturing
1752 // only 20 DSQs reports the mean of those 20, not the mean
1753 // over 64. max_dsq_depth (the Peak sibling) is robust to
1754 // this (max-of-captured surfaces the deepest queue ever
1755 // captured); avg_dsq_depth has no such monotonicity. If
1756 // walker truncation becomes routine, add a denom-aware
1757 // version that sums-then-divides by the topology's
1758 // expected local-CPU count.
1759 //
1760 // Accessor falls back to ext_metrics (no typed GauntletRow
1761 // field; promoting to typed is gated on cross-RUN
1762 // aggregation needs surfacing).
1763 name: "avg_dsq_depth",
1764 polarity: crate::test_support::Polarity::LowerBetter,
1765 kind: MetricKind::Gauge(GaugeAgg::Avg),
1766 default_abs: 5.0,
1767 default_rel: 0.50,
1768 display_unit: "",
1769 accessor: |_| None,
1770 },
1771 MetricDef {
1772 name: "stuck_count",
1773 polarity: crate::test_support::Polarity::LowerBetter,
1774 kind: MetricKind::Counter,
1775 // abs=1.0 (vs 5.0 for the event counters below): one additional
1776 // scheduler stall is high-signal, so a delta of a single whole
1777 // stall — gated by the 0.50 rel threshold — is worth flagging.
1778 default_abs: 1.0,
1779 default_rel: 0.50,
1780 display_unit: "",
1781 accessor: |r| Some(r.stuck_count),
1782 },
1783 MetricDef {
1784 name: "total_fallback",
1785 polarity: crate::test_support::Polarity::Informational,
1786 kind: MetricKind::Counter,
1787 default_abs: 5.0,
1788 default_rel: 0.30,
1789 // Integer event count, not a rate — the source field on
1790 // `MonitorSummary::event_deltas.total_fallback` is a cumulative
1791 // delta across the run, not per-second. Empty unit matches the
1792 // other counter metrics (`stuck_count`, `total_iterations`,
1793 // `total_migrations`).
1794 display_unit: "",
1795 accessor: |r| Some(r.fallback_count as f64),
1796 },
1797 MetricDef {
1798 name: "total_keep_last",
1799 polarity: crate::test_support::Polarity::Informational,
1800 kind: MetricKind::Counter,
1801 default_abs: 5.0,
1802 default_rel: 0.30,
1803 // Integer event count, not a rate — see `total_fallback`
1804 // rationale above. Source field is
1805 // `MonitorSummary::event_deltas.total_dispatch_keep_last`.
1806 display_unit: "",
1807 accessor: |r| Some(r.keep_last_count as f64),
1808 },
1809 MetricDef {
1810 // Ext-only SUM-folding numerator for fallback_per_vcpu_sec. Separate
1811 // from the typed display-average total_fallback field.
1812 name: "total_fallback_pooled",
1813 polarity: crate::test_support::Polarity::Informational,
1814 kind: MetricKind::Counter,
1815 default_abs: 1.0,
1816 default_rel: 0.30,
1817 display_unit: "",
1818 accessor: |_| None,
1819 },
1820 MetricDef {
1821 // Ext-only SUM-folding numerator for keep_last_per_vcpu_sec.
1822 name: "total_keep_last_pooled",
1823 polarity: crate::test_support::Polarity::Informational,
1824 kind: MetricKind::Counter,
1825 default_abs: 1.0,
1826 default_rel: 0.30,
1827 display_unit: "",
1828 accessor: |_| None,
1829 },
1830 MetricDef {
1831 // Mean vCPU pthread CPU-clock advance over the event endpoints. The
1832 // Counter fold makes cross-run activity rates re-pool as Σevents/ΣCPU.
1833 name: "total_event_vcpu_sec",
1834 polarity: crate::test_support::Polarity::Informational,
1835 kind: MetricKind::Counter,
1836 default_abs: 0.001,
1837 default_rel: 0.30,
1838 display_unit: "s",
1839 accessor: |_| None,
1840 },
1841 MetricDef {
1842 name: "fallback_per_vcpu_sec",
1843 polarity: crate::test_support::Polarity::LowerBetter,
1844 kind: MetricKind::Rate {
1845 numerator: "total_fallback_pooled",
1846 denominator: "total_event_vcpu_sec",
1847 },
1848 default_abs: 1.0,
1849 default_rel: 0.30,
1850 display_unit: "/vcpu-s",
1851 accessor: |_| None,
1852 },
1853 MetricDef {
1854 name: "keep_last_per_vcpu_sec",
1855 polarity: crate::test_support::Polarity::LowerBetter,
1856 kind: MetricKind::Rate {
1857 numerator: "total_keep_last_pooled",
1858 denominator: "total_event_vcpu_sec",
1859 },
1860 default_abs: 1.0,
1861 default_rel: 0.30,
1862 display_unit: "/vcpu-s",
1863 accessor: |_| None,
1864 },
1865 // -- System-wide schedstat aggregates. Read host-side from guest memory at
1866 // -- freeze (zero observer effect) via `MonitorSummary::schedstat_deltas`
1867 // -- (per-rq `struct rq` schedstat fields summed across CPUs over the run);
1868 // -- `sidecar_to_row` inserts them into `GauntletRow::ext_metrics` so the
1869 // -- `|_| None` accessors surface them through the ext fallback. The seven
1870 // -- raw counters are `Polarity::Informational` — directionless (more
1871 // -- wakeups / context-switches / yields is neither inherently better nor
1872 // -- worse), so they are SHOWN but NEVER gated. They are also
1873 // -- WINDOW-DURATION- and LOAD-CONFOUNDED raw sums (a longer monitor window
1874 // -- or more offered runnable work inflates them independent of the
1875 // -- scheduler) — a second reason they are Informational, not LowerBetter:
1876 // -- a large raw delta is not a regression. The duration- and load-robust
1877 // -- GATED signals are the per-schedule mean (`total_run_delay_ns_per_sched`)
1878 // -- and the locality ratio (`ttwu_local_fraction`) derived below; four of
1879 // -- the raw counters double as those Rates' Counter components.
1880 MetricDef {
1881 // Numerator of `total_run_delay_ns_per_sched`. Cumulative runqueue-wait
1882 // delay (ns) across all tasks + all CPUs (`rq.rq_sched_info.run_delay`).
1883 // `total_` prefix satisfies the Counter naming gate.
1884 name: "total_run_delay",
1885 polarity: crate::test_support::Polarity::Informational,
1886 kind: MetricKind::Counter,
1887 default_abs: 1000.0,
1888 default_rel: 0.10,
1889 display_unit: "ns",
1890 accessor: |_| None,
1891 },
1892 MetricDef {
1893 // Denominator of `total_run_delay_ns_per_sched`. Count of non-idle task
1894 // arrivals (`rq.rq_sched_info.pcount`) — the number of schedules the
1895 // run-delay accrued over.
1896 name: "total_pcount",
1897 polarity: crate::test_support::Polarity::Informational,
1898 kind: MetricKind::Counter,
1899 default_abs: 1.0,
1900 default_rel: 0.10,
1901 display_unit: "",
1902 accessor: |_| None,
1903 },
1904 MetricDef {
1905 // schedule() invocation count (`rq.sched_count` — incremented once per
1906 // __schedule() call, a superset of context switches since re-picking the
1907 // same task still counts). Informational: more scheduler entries can
1908 // mean responsiveness OR thrashing — no direction.
1909 name: "total_sched_count",
1910 polarity: crate::test_support::Polarity::Informational,
1911 kind: MetricKind::Counter,
1912 default_abs: 1.0,
1913 default_rel: 0.10,
1914 display_unit: "",
1915 accessor: |_| None,
1916 },
1917 MetricDef {
1918 // `sched_yield()` call count (`rq.yld_count`). Informational (workload
1919 // behavior, not a scheduler-quality signal).
1920 name: "total_yld_count",
1921 polarity: crate::test_support::Polarity::Informational,
1922 kind: MetricKind::Counter,
1923 default_abs: 1.0,
1924 default_rel: 0.10,
1925 display_unit: "",
1926 accessor: |_| None,
1927 },
1928 MetricDef {
1929 // Go-idle count (`rq.sched_goidle`): times a CPU picked the idle task.
1930 // Informational (good utilization vs wasted idle — ambiguous).
1931 name: "total_sched_goidle",
1932 polarity: crate::test_support::Polarity::Informational,
1933 kind: MetricKind::Counter,
1934 default_abs: 1.0,
1935 default_rel: 0.10,
1936 display_unit: "",
1937 accessor: |_| None,
1938 },
1939 MetricDef {
1940 // Denominator of `ttwu_local_fraction`. Total wakeups (`rq.ttwu_count`)
1941 // — workload activity. Informational.
1942 name: "total_ttwu_count",
1943 polarity: crate::test_support::Polarity::Informational,
1944 kind: MetricKind::Counter,
1945 default_abs: 1.0,
1946 default_rel: 0.10,
1947 display_unit: "",
1948 accessor: |_| None,
1949 },
1950 MetricDef {
1951 // Numerator of `ttwu_local_fraction`. Wakeups kept on the waking CPU
1952 // (`rq.ttwu_local`). Informational on its own; the locality RATIO below
1953 // carries the direction.
1954 name: "total_ttwu_local",
1955 polarity: crate::test_support::Polarity::Informational,
1956 kind: MetricKind::Counter,
1957 default_abs: 1.0,
1958 default_rel: 0.10,
1959 display_unit: "",
1960 accessor: |_| None,
1961 },
1962 MetricDef {
1963 // GATED. System-wide per-schedule MEAN runqueue-wait delay =
1964 // Σrun_delay / Σpcount, re-derived across CPUs/runs by
1965 // `derive_rate_metrics` (the `Rate` kind's `MergeKind::Recompute` pools
1966 // the components — never a mean-of-ratios). Duration- and load-robust
1967 // (per-EVENT, not per-time): the system-wide analog of the
1968 // workload-scoped per-task `mean_run_delay_us` (schbench's
1969 // `mean_sched_delay = run_delay/pcount`). LowerBetter. Absent when
1970 // `total_pcount` is 0 (no schedules) or CONFIG_SCHEDSTATS is off
1971 // (components absent).
1972 name: "total_run_delay_ns_per_sched",
1973 polarity: crate::test_support::Polarity::LowerBetter,
1974 kind: MetricKind::Rate {
1975 numerator: "total_run_delay",
1976 denominator: "total_pcount",
1977 },
1978 default_abs: 100.0,
1979 default_rel: 0.15,
1980 display_unit: "ns",
1981 accessor: |_| None,
1982 },
1983 MetricDef {
1984 // GATED. Wakeup LOCALITY = Σttwu_local / Σttwu_count, re-derived by
1985 // `derive_rate_metrics`. A fraction in [0, 1]: the share of wakeups kept
1986 // on the waking CPU (better cache locality, fewer cross-CPU hops on
1987 // wakeup). HigherBetter. Absent when `total_ttwu_count` is 0 or
1988 // CONFIG_SCHEDSTATS is off.
1989 name: "ttwu_local_fraction",
1990 polarity: crate::test_support::Polarity::HigherBetter,
1991 kind: MetricKind::Rate {
1992 numerator: "total_ttwu_local",
1993 denominator: "total_ttwu_count",
1994 },
1995 default_abs: 0.05,
1996 default_rel: 0.10,
1997 display_unit: "",
1998 accessor: |_| None,
1999 },
2000 MetricDef {
2001 // GATED. Go-idle FRACTION = Σsched_goidle / Σsched_count, re-derived by
2002 // `derive_rate_metrics`. A fraction in [0, 1]: the share of `schedule()`
2003 // calls that picked the idle task (the CPU found nothing runnable).
2004 // Load-normalized (per-schedule, not per-time), so it is duration- AND
2005 // arrival-rate-stable — the genuinely-useful-for-spread schedstat rate
2006 // (a bare per-second rate carries the same spread as the raw total when
2007 // cohort runs share a duration, so it adds nothing at equal duration).
2008 // Informational: a high idle fraction is ambiguous — efficient when no
2009 // runnable work exists, but a starvation symptom when runnable work is
2010 // not dispatched — so it surfaces in `--noise-adjust` spread but does
2011 // not gate a regression verdict. Absent when `total_sched_count` is 0
2012 // (no schedules) or CONFIG_SCHEDSTATS is off (components absent).
2013 name: "sched_goidle_fraction",
2014 polarity: crate::test_support::Polarity::Informational,
2015 kind: MetricKind::Rate {
2016 numerator: "total_sched_goidle",
2017 denominator: "total_sched_count",
2018 },
2019 default_abs: 0.05,
2020 default_rel: 0.10,
2021 display_unit: "",
2022 accessor: |_| None,
2023 },
2024 // Dilation-safe schedstat activity densities: each total_* schedstat
2025 // Counter divided by total_schedstat_vcpu_sec (the mean pthread CPU-clock
2026 // advance across the monitored vCPUs). Unlike the
2027 // per-schedule ratios above (total_run_delay_ns_per_sched / *_fraction,
2028 // load-normalized per-EVENT), these are per delivered vCPU CPU time. They
2029 // remain stable when the host preempts the VM and compare differing run
2030 // durations without treating stolen wall time as scheduler inactivity.
2031 // Rate kind => cross-run Σnumerator/Σdenominator (CPU-time-weighted), NOT a
2032 // mean of per-run rates. All Informational (activity density has no
2033 // universal better-direction) except run_delay_per_vcpu_sec (LowerBetter).
2034 // Absent when CONFIG_SCHEDSTATS is off or complete vCPU-clock evidence is
2035 // unavailable/degenerate.
2036 MetricDef {
2037 // Hidden rate-denominator component (NOT user-facing): the schedstat
2038 // mean vCPU pthread CPU-clock advance in seconds, co-inserted with the
2039 // total_* schedstat counters when available. Counter so it survives the
2040 // cross-RUN Sum-fold (Σcount / Σvcpu-sec re-derives).
2041 name: "total_schedstat_vcpu_sec",
2042 polarity: crate::test_support::Polarity::Informational,
2043 kind: MetricKind::Counter,
2044 default_abs: 0.1,
2045 default_rel: 0.30,
2046 display_unit: "s",
2047 accessor: |_| None,
2048 },
2049 MetricDef {
2050 // Σrun_delay / Σmean-vCPU-CPU-seconds — scheduling-wait delay density.
2051 // LowerBetter. Distinct from total_run_delay_ns_per_sched (per event).
2052 name: "run_delay_per_vcpu_sec",
2053 polarity: crate::test_support::Polarity::LowerBetter,
2054 kind: MetricKind::Rate {
2055 numerator: "total_run_delay",
2056 denominator: "total_schedstat_vcpu_sec",
2057 },
2058 default_abs: 1000.0,
2059 default_rel: 0.30,
2060 display_unit: "ns/vcpu-s",
2061 accessor: |_| None,
2062 },
2063 MetricDef {
2064 // Σpcount / Σmean-vCPU-CPU-seconds — task-arrival (non-idle schedule)
2065 // activity density. Informational (scheduling activity tracks offered
2066 // load + scheduler behavior together, no universal direction).
2067 name: "pcount_per_vcpu_sec",
2068 polarity: crate::test_support::Polarity::Informational,
2069 kind: MetricKind::Rate {
2070 numerator: "total_pcount",
2071 denominator: "total_schedstat_vcpu_sec",
2072 },
2073 default_abs: 1.0,
2074 default_rel: 0.30,
2075 display_unit: "/vcpu-s",
2076 accessor: |_| None,
2077 },
2078 MetricDef {
2079 // Σsched_count / Σmean-vCPU-CPU-seconds — schedule() activity density
2080 // (rq.sched_count increments once per __schedule() call, a superset of
2081 // context switches since re-picking the same task still counts).
2082 // Informational. The CPU-time sibling of the precomputed struct rate
2083 // that was retired; cross-run-foldable here (Σnum/Σden), the struct
2084 // field was not.
2085 name: "sched_count_per_vcpu_sec",
2086 polarity: crate::test_support::Polarity::Informational,
2087 kind: MetricKind::Rate {
2088 numerator: "total_sched_count",
2089 denominator: "total_schedstat_vcpu_sec",
2090 },
2091 default_abs: 1.0,
2092 default_rel: 0.30,
2093 display_unit: "/vcpu-s",
2094 accessor: |_| None,
2095 },
2096 MetricDef {
2097 // Σyld_count / Σmean-vCPU-CPU-seconds — sched_yield() activity density.
2098 // Informational; high-signal only under a yield-storm pathology.
2099 name: "yld_count_per_vcpu_sec",
2100 polarity: crate::test_support::Polarity::Informational,
2101 kind: MetricKind::Rate {
2102 numerator: "total_yld_count",
2103 denominator: "total_schedstat_vcpu_sec",
2104 },
2105 default_abs: 1.0,
2106 default_rel: 0.30,
2107 display_unit: "/vcpu-s",
2108 accessor: |_| None,
2109 },
2110 MetricDef {
2111 // Σttwu_count / Σmean-vCPU-CPU-seconds — wakeup activity density.
2112 // (wakeup volume; the locality DIRECTION is ttwu_local_fraction, not a
2113 // per-second magnitude — so ttwu_local has no _per_sec rate).
2114 name: "ttwu_count_per_vcpu_sec",
2115 polarity: crate::test_support::Polarity::Informational,
2116 kind: MetricKind::Rate {
2117 numerator: "total_ttwu_count",
2118 denominator: "total_schedstat_vcpu_sec",
2119 },
2120 default_abs: 1.0,
2121 default_rel: 0.30,
2122 display_unit: "/vcpu-s",
2123 accessor: |_| None,
2124 },
2125 MetricDef {
2126 // Σsched_goidle / Σmean-vCPU-CPU-seconds — go-idle activity density.
2127 // Informational; the per-TIME companion to sched_goidle_fraction (the
2128 // per-schedule share) — a high goidle/sec can signal wakeup-thrash.
2129 name: "sched_goidle_per_vcpu_sec",
2130 polarity: crate::test_support::Polarity::Informational,
2131 kind: MetricKind::Rate {
2132 numerator: "total_sched_goidle",
2133 denominator: "total_schedstat_vcpu_sec",
2134 },
2135 default_abs: 1.0,
2136 default_rel: 0.30,
2137 display_unit: "/vcpu-s",
2138 accessor: |_| None,
2139 },
2140 MetricDef {
2141 // Whole-run mean per-CPU runqueue depth (`rq.nr_running`, ALL scheduling
2142 // classes), read host-side from guest memory via
2143 // `MonitorSummary::avg_nr_running`. The occupancy LEVEL — distinct from
2144 // `avg_dsq_depth` (scx DSQ only) and `avg_imbalance_ratio` (cross-CPU
2145 // SKEW, not level). `MetricKind::Gauge(Avg)`: the cross-run fold is the
2146 // sample-weighted pooled mean (Σ avg×samples / Σ samples via
2147 // `aggregate_samples_weighted`, weight = `run_sample_count`). The weight
2148 // is sample count, not samples×CPUs — EXACT under same-topology pairing
2149 // (CPU count is a pairing dim, so cross-folded runs share it; the same
2150 // basis `avg_imbalance_ratio` uses). LowerBetter — higher mean depth =
2151 // more tasks waiting, but load-confounded (more offered runnable tasks
2152 // raises it independent of the scheduler), the same caveat
2153 // `avg_dsq_depth` carries; meaningful for same-offered-load A/B.
2154 // ext_metrics-only (accessor `|_| None`, surfaced via the ext fallback);
2155 // absent when the run has no monitor samples.
2156 name: "avg_nr_running",
2157 polarity: crate::test_support::Polarity::LowerBetter,
2158 kind: MetricKind::Gauge(GaugeAgg::Avg),
2159 default_abs: 0.5,
2160 default_rel: 0.20,
2161 display_unit: "",
2162 accessor: |_| None,
2163 },
2164 MetricDef {
2165 // Wake-latency p99, re-pooled over the COMBINED wake-latency sample
2166 // set across every cgroup (and phase), NOT a max of per-cgroup p99s.
2167 // Distribution kind: derived post-merge by
2168 // `crate::assert::populate_run_distribution_metrics`; accessor is
2169 // |_| None so `MetricDef::read` takes the ext_metrics value the
2170 // re-pool writes. (The `worst_` name is retained for sidecar /
2171 // DataFrame / CI-gate stability — see the `worst_` naming
2172 // convention on [`METRICS`].)
2173 name: "worst_p99_wake_latency_us",
2174 polarity: crate::test_support::Polarity::LowerBetter,
2175 kind: MetricKind::Distribution {
2176 source: SampleSource::WakeLatencyNs,
2177 reduction: SampleReduction::P99,
2178 },
2179 default_abs: 50.0,
2180 default_rel: 0.25,
2181 display_unit: "\u{00b5}s",
2182 accessor: |_| None,
2183 },
2184 MetricDef {
2185 // Wake-latency median (50th pct), re-pooled over the combined wake
2186 // set — see `worst_p99_wake_latency_us`.
2187 name: "worst_median_wake_latency_us",
2188 polarity: crate::test_support::Polarity::LowerBetter,
2189 kind: MetricKind::Distribution {
2190 source: SampleSource::WakeLatencyNs,
2191 reduction: SampleReduction::Median,
2192 },
2193 default_abs: 20.0,
2194 default_rel: 0.25,
2195 display_unit: "\u{00b5}s",
2196 accessor: |_| None,
2197 },
2198 MetricDef {
2199 // Wake-latency coefficient of variation (stddev/mean), re-pooled
2200 // over the combined wake set with a population-WEIGHTED variance and
2201 // mean (denominator = Σ per-sample population weights, i.e. the
2202 // reconstructed true wakeup population; == `pool.len()` only below the
2203 // reservoir cap, where every weight is 1.0) — see
2204 // `worst_p99_wake_latency_us`.
2205 name: "worst_wake_latency_cv",
2206 polarity: crate::test_support::Polarity::LowerBetter,
2207 kind: MetricKind::Distribution {
2208 source: SampleSource::WakeLatencyNs,
2209 reduction: SampleReduction::Cv,
2210 },
2211 default_abs: 0.10,
2212 default_rel: 0.25,
2213 display_unit: "",
2214 accessor: |_| None,
2215 },
2216 MetricDef {
2217 // Run-level timer-latency p99 (WorkType::TimerLatency cyclictest probe),
2218 // re-pooled over the combined timer-latency sample set across every
2219 // cgroup and phase (NOT a max of per-cgroup p99s). Distribution: derived
2220 // post-merge by populate_run_distribution_metrics; accessor |_| None
2221 // reads the ext_metrics value the re-pool writes.
2222 name: "worst_p99_timer_latency_us",
2223 polarity: crate::test_support::Polarity::LowerBetter,
2224 kind: MetricKind::Distribution {
2225 source: SampleSource::TimerLatencyNs,
2226 reduction: SampleReduction::P99,
2227 },
2228 default_abs: 50.0,
2229 default_rel: 0.25,
2230 display_unit: "\u{00b5}s",
2231 accessor: |_| None,
2232 },
2233 MetricDef {
2234 // Run-level timer-latency median — see worst_p99_timer_latency_us.
2235 name: "worst_median_timer_latency_us",
2236 polarity: crate::test_support::Polarity::LowerBetter,
2237 kind: MetricKind::Distribution {
2238 source: SampleSource::TimerLatencyNs,
2239 reduction: SampleReduction::Median,
2240 },
2241 default_abs: 20.0,
2242 default_rel: 0.25,
2243 display_unit: "\u{00b5}s",
2244 accessor: |_| None,
2245 },
2246 MetricDef {
2247 // Run-level timer-latency p99.9 (the deep RT tail) — see
2248 // worst_p99_timer_latency_us.
2249 name: "worst_p999_timer_latency_us",
2250 polarity: crate::test_support::Polarity::LowerBetter,
2251 kind: MetricKind::Distribution {
2252 source: SampleSource::TimerLatencyNs,
2253 reduction: SampleReduction::P999,
2254 },
2255 default_abs: 100.0,
2256 default_rel: 0.25,
2257 display_unit: "\u{00b5}s",
2258 accessor: |_| None,
2259 },
2260 MetricDef {
2261 // Run-level WORST (max) timer-latency — the cyclictest headline.
2262 // MAX-folds cross-RUN (SampleReduction::Worst, the peak survives) via
2263 // aggregate_finite, distinct from the MEAN-folded percentiles above.
2264 // Named worst_* with no pNN exactly like worst_run_delay_us
2265 // (Distribution{RunDelayNs, Worst}).
2266 name: "worst_timer_latency_us",
2267 polarity: crate::test_support::Polarity::LowerBetter,
2268 kind: MetricKind::Distribution {
2269 source: SampleSource::TimerLatencyNs,
2270 reduction: SampleReduction::Worst,
2271 },
2272 default_abs: 200.0,
2273 default_rel: 0.25,
2274 display_unit: "\u{00b5}s",
2275 accessor: |_| None,
2276 },
2277 MetricDef {
2278 // Raw completed work is duration- and host-contention-sensitive. Keep
2279 // it visible as a diagnostic component, but use `iteration_rate` for
2280 // directional comparisons.
2281 name: "total_iterations",
2282 polarity: crate::test_support::Polarity::Informational,
2283 kind: MetricKind::Counter,
2284 default_abs: 2.0,
2285 default_rel: 0.10,
2286 display_unit: "",
2287 accessor: |r| Some(r.total_iterations as f64),
2288 },
2289 MetricDef {
2290 // Run-level POOLED CPU-seconds — the DENOMINATOR component of the
2291 // pooled `iteration_rate` Rate. ext_metrics-only (accessor
2292 // |_| None): populate_run_pooled_iteration_rate sums the
2293 // MEASURED cgroups' CgroupStats.total_cpu_time_ns (total_cpu_time_ns >
2294 // 0) and inserts the ns→s value (= Σns / 1e9) at the post-merge eval
2295 // site. The measured-only filter leaves this denominator unchanged
2296 // (excluded cgroups contribute 0 ns) — it matters for the numerator,
2297 // whose excluded cgroups carry nonzero iterations. The /1e9 lives
2298 // there (NOT in derive_rate_metrics, which does a bare num/den),
2299 // applied ONCE on the summed ns. `total_` prefix satisfies the Counter
2300 // gate.
2301 name: "total_cpu_time_sec",
2302 polarity: crate::test_support::Polarity::Informational,
2303 kind: MetricKind::Counter,
2304 default_abs: 1.0,
2305 default_rel: 0.30,
2306 display_unit: "s",
2307 accessor: |_| None,
2308 },
2309 MetricDef {
2310 // Run-level POOLED iteration count — the NUMERATOR component of the
2311 // pooled `iteration_rate` Rate, summed over cgroups with
2312 // MEASURED cpu-time (total_cpu_time_ns > 0). ext_metrics-only,
2313 // DISTINCT from the typed `total_iterations` Counter on purpose: the
2314 // typed field is skipped from ext_metrics (TYPED_FIELD_NAMES) and folds
2315 // cross-RUN as a MEAN (group_and_average_by's round_u64 divides the
2316 // accumulated sum by the contributor count — a display average), while
2317 // a Rate numerator must fold cross-RUN as a SUM (aggregate_finite
2318 // Counter arm, no divide) so Σnum/Σdenom re-pools. One shared key
2319 // cannot carry both folds, so the numerator gets its own ext key. It
2320 // also sums only MEASURED cgroups, where the typed field's per-RUN
2321 // cross-cgroup merge sums ALL cgroups — so it equals the merge-summed
2322 // typed total_iterations unless an excluded (zero-cpu-time) cgroup
2323 // carried iterations>0, in which case it is LESS.
2324 // `total_` prefix satisfies the Counter naming gate.
2325 name: "total_iterations_pooled",
2326 polarity: crate::test_support::Polarity::Informational,
2327 kind: MetricKind::Counter,
2328 default_abs: 1.0,
2329 default_rel: 0.10,
2330 display_unit: "",
2331 accessor: |_| None,
2332 },
2333 MetricDef {
2334 // The single canonical worker iteration rate, pooled across cgroups,
2335 // phases, and runs: Σiterations / Σdelivered guest CPU-seconds.
2336 // MetricKind::Rate over the two Counter components above re-derives it
2337 // at every aggregation level rather than averaging ratios.
2338 // Distinct from the per-cgroup `worst_iterations_per_cpu_sec`
2339 // WorstLowest metric (the lowest-wins min-fold starvation selector):
2340 // this is the POOLED cohort rate and is invariant to host preemption.
2341 //
2342 // SAME physical quantity as worst_iterations_per_cpu_sec (iter/CPU-s
2343 // efficiency), so it shares that sibling's compare thresholds:
2344 // default_rel=0.10 (a 10% efficiency change is the regression signal)
2345 // and default_abs=10.0 (near-zero anti-jitter floor — a real busy
2346 // workload's rate is orders of magnitude larger). NOT the looser
2347 name: "iteration_rate",
2348 polarity: crate::test_support::Polarity::HigherBetter,
2349 kind: MetricKind::Rate {
2350 numerator: "total_iterations_pooled",
2351 denominator: "total_cpu_time_sec",
2352 },
2353 default_abs: 10.0,
2354 default_rel: 0.10,
2355 display_unit: "iter/cpu-s",
2356 accessor: |_| None,
2357 },
2358 MetricDef {
2359 // Per-phase SYSTEM (in-kernel) CPU time in nanoseconds. Read
2360 // host-side from frozen task_struct.stime + the thread-group
2361 // signal_struct.stime accumulator (zero guest work). Injected
2362 // post-hoc — NOT a read_sample metric — as a per-thread-GROUP
2363 // delta over the phase: `crate::assert::phase_group_cpu_delta`
2364 // sums each tgid's `thread_group_cputime` (signal + live-thread
2365 // stime) at its first and last appearance among the phase's
2366 // freeze samples and takes `last - first` = system CPU time the
2367 // group spent during the phase. PerPhaseDeltaSum: the per-phase value
2368 // is already a delta, so the disjoint per-phase deltas SUM across the
2369 // run (the run's total OBSERVED system CPU time — a lower bound
2370 // excluding head / tail / inter-phase-gap windows; see the kind doc),
2371 // and the per-run totals fold by UNWEIGHTED MEAN cross-RUN (NOT
2372 // sample-count-weighted), like user_time_ns. Raw CPU time varies with
2373 // the CPU the host delivered, so it is diagnostic; system_cpu_fraction
2374 // is the directional overhead signal.
2375 name: "system_time_ns",
2376 polarity: crate::test_support::Polarity::Informational,
2377 kind: MetricKind::PerPhaseDeltaSum,
2378 default_abs: 1000.0,
2379 default_rel: 0.30,
2380 display_unit: "ns",
2381 accessor: |_| None,
2382 },
2383 MetricDef {
2384 // Per-phase USER-mode CPU time in nanoseconds. Same host-side /
2385 // injected / PerPhaseDeltaSum shape as `system_time_ns` (task_struct
2386 // .utime + the thread-group signal_struct.utime accumulator,
2387 // per-tgid delta via `crate::assert::phase_group_cpu_delta`; SUM
2388 // cross-phase, unweighted MEAN cross-run).
2389 // Pairs with it so diagnostics can distinguish "system time rose,
2390 // user work flat" from "both rose". Raw CPU time is informational;
2391 // utime already includes gtime so the two are never summed elsewhere.
2392 name: "user_time_ns",
2393 polarity: crate::test_support::Polarity::Informational,
2394 kind: MetricKind::PerPhaseDeltaSum,
2395 default_abs: 1000.0,
2396 default_rel: 0.30,
2397 display_unit: "ns",
2398 accessor: |_| None,
2399 },
2400 MetricDef {
2401 // Sum of system_time_ns + user_time_ns over the identical task-group
2402 // endpoints. Hidden denominator for system_cpu_fraction.
2403 name: "observed_task_cpu_time_ns",
2404 polarity: crate::test_support::Polarity::Informational,
2405 kind: MetricKind::PerPhaseDeltaSum,
2406 default_abs: 1000.0,
2407 default_rel: 0.30,
2408 display_unit: "ns",
2409 accessor: |_| None,
2410 },
2411 MetricDef {
2412 // Fraction of observed task CPU spent in-kernel. Unlike raw system time,
2413 // this composition is invariant to host preemption reducing the phase's
2414 // delivered CPU budget, while still exposing kernel-spin regressions.
2415 name: "system_cpu_fraction",
2416 polarity: crate::test_support::Polarity::LowerBetter,
2417 kind: MetricKind::Rate {
2418 numerator: "system_time_ns",
2419 denominator: "observed_task_cpu_time_ns",
2420 },
2421 default_abs: 0.02,
2422 default_rel: 0.30,
2423 display_unit: "",
2424 accessor: |_| None,
2425 },
2426 // ---- IRQ observability ----
2427 // Host-side observer-free IRQ signals from PerCpuTimeStats (freeze
2428 // Snapshot, src/monitor/dump/mod.rs), cross-CPU folded at
2429 // read_sample and carried through ext_metrics (accessor |_| None) like
2430 // system_time_ns. The time signals require CONFIG_IRQ_TIME_ACCOUNTING;
2431 // loud-absent (None), never false-zero, when off. Per-phase
2432 // reduction is the Counter last-minus-first over the bucket's freeze
2433 // captures (needs num_snapshots >= 2). The per-CPU SPATIAL axis
2434 // (max_cpu_hardirqs + max_cpu_hardirq_concentration, the busiest-CPU
2435 // dimension vs this cross-CPU SUM) is registered below; per-softirq
2436 // spatial-max is a follow-up.
2437 MetricDef {
2438 // Sum of kernel_stat.irqs_sum across CPUs — total hardirqs fired
2439 // (per-CPU monotonic count, __kstat_incr_irqs_this_cpu,
2440 // kernel/irq/internals.h). NOT gated on irqtime (always populates).
2441 name: "total_hardirqs",
2442 polarity: crate::test_support::Polarity::Informational,
2443 kind: MetricKind::Counter,
2444 default_abs: 10.0,
2445 default_rel: 0.50,
2446 display_unit: "",
2447 accessor: |_| None,
2448 },
2449 MetricDef {
2450 // Sum of kernel_stat.softirqs[NET_RX] across CPUs (index via
2451 // SOFTIRQ_NAMES; kstat_incr_softirqs_this_cpu, kernel/softirq.c). The
2452 // load-bearing softirq for NetTraffic RX.
2453 name: "total_softirq_net_rx",
2454 polarity: crate::test_support::Polarity::Informational,
2455 kind: MetricKind::Counter,
2456 default_abs: 10.0,
2457 default_rel: 0.50,
2458 display_unit: "",
2459 accessor: |_| None,
2460 },
2461 MetricDef {
2462 // Sum of kernel_stat.softirqs[NET_TX] across CPUs.
2463 name: "total_softirq_net_tx",
2464 polarity: crate::test_support::Polarity::Informational,
2465 kind: MetricKind::Counter,
2466 default_abs: 10.0,
2467 default_rel: 0.50,
2468 display_unit: "",
2469 accessor: |_| None,
2470 },
2471 MetricDef {
2472 // Sum of kernel_stat.softirqs[TIMER] across CPUs.
2473 name: "total_softirq_timer",
2474 polarity: crate::test_support::Polarity::Informational,
2475 kind: MetricKind::Counter,
2476 default_abs: 10.0,
2477 default_rel: 0.50,
2478 display_unit: "",
2479 accessor: |_| None,
2480 },
2481 MetricDef {
2482 // Sum of kernel_stat.softirqs[SCHED] across CPUs.
2483 name: "total_softirq_sched",
2484 polarity: crate::test_support::Polarity::Informational,
2485 kind: MetricKind::Counter,
2486 default_abs: 10.0,
2487 default_rel: 0.50,
2488 display_unit: "",
2489 accessor: |_| None,
2490 },
2491 MetricDef {
2492 // Sum of kernel_cpustat.cpustat[CPUTIME_IRQ] across CPUs — raw ns in
2493 // hardirq (irqtime_account_delta, kernel/sched/cputime.c). Read from
2494 // guest memory as ns (NOT /proc/stat jiffies — no nsec_to_clock_t).
2495 // Requires CONFIG_IRQ_TIME_ACCOUNTING; Counter/ns like system_time_ns.
2496 name: "total_irq_time_ns",
2497 polarity: crate::test_support::Polarity::Informational,
2498 kind: MetricKind::Counter,
2499 default_abs: 1000.0,
2500 default_rel: 0.50,
2501 display_unit: "ns",
2502 accessor: |_| None,
2503 },
2504 MetricDef {
2505 // Sum of kernel_cpustat.cpustat[CPUTIME_SOFTIRQ] across CPUs — raw ns
2506 // in softirq. Requires CONFIG_IRQ_TIME_ACCOUNTING.
2507 name: "total_softirq_time_ns",
2508 polarity: crate::test_support::Polarity::Informational,
2509 kind: MetricKind::Counter,
2510 default_abs: 1000.0,
2511 default_rel: 0.50,
2512 display_unit: "ns",
2513 accessor: |_| None,
2514 },
2515 MetricDef {
2516 // Sum of kernel_cpustat.cpustat[CPUTIME_STEAL] across CPUs — raw ns the
2517 // hypervisor stole (account_steal_time; needs CONFIG_PARAVIRT_TIME_
2518 // ACCOUNTING + kvm-clock steal-time). CPUTIME_STEAL is an unconditional
2519 // enum member (enum cpu_usage_stat, include/linux/kernel_stat.h), so
2520 // steal-accounting-off reads a constant 0 — a measured Some(0.0), NOT
2521 // loud-absent like the BTF-gated avg_irq gauge.
2522 name: "total_steal_time_ns",
2523 polarity: crate::test_support::Polarity::Informational,
2524 kind: MetricKind::Counter,
2525 default_abs: 1000.0,
2526 default_rel: 0.50,
2527 display_unit: "ns",
2528 accessor: |_| None,
2529 },
2530 MetricDef {
2531 // Mean across CPUs of rq->avg_irq.util_avg — the PELT IRQ load average
2532 // (struct sched_avg, kernel/sched/sched.h; range [0, 1024] =
2533 // SCHED_CAPACITY_SCALE). INSTANTANEOUS gauge (decaying PELT), NEVER
2534 // deltaed. Requires CONFIG_HAVE_SCHED_AVG_IRQ (def_bool y when
2535 // (IRQ_TIME_ACCOUNTING || PARAVIRT_TIME_ACCOUNTING) && SMP — init/Kconfig).
2536 // Distinct from taskstats avg_irq_delay_ns (irq-DELAY accounting); this
2537 // is PELT util.
2538 name: "avg_irq_util",
2539 polarity: crate::test_support::Polarity::LowerBetter,
2540 kind: MetricKind::Gauge(GaugeAgg::Avg),
2541 default_abs: 20.0,
2542 default_rel: 0.30,
2543 display_unit: "",
2544 accessor: |_| None,
2545 },
2546 MetricDef {
2547 // Host spatial-max ACROSS CPUs of the INSTANTANEOUS rq->avg_irq.util_avg
2548 // gauge (worst-CPU IRQ load at the freeze) — NOT a kernel max-of-window.
2549 // Peak because both the spatial and temporal reduces are max over
2550 // instantaneous values (no cumulative-delta hazard, unlike a counter's
2551 // spatial-max; per-CPU axis is a follow-up). Range [0, 1024].
2552 name: "max_avg_irq_util",
2553 polarity: crate::test_support::Polarity::LowerBetter,
2554 kind: MetricKind::Peak,
2555 default_abs: 50.0,
2556 default_rel: 0.30,
2557 display_unit: "",
2558 accessor: |_| None,
2559 },
2560 MetricDef {
2561 // DERIVED activity density: total_hardirqs divided by delivered guest
2562 // CPU-seconds over the same capture endpoints. Host preemption is not
2563 // part of the denominator.
2564 name: "hardirqs_per_cpu_sec",
2565 polarity: crate::test_support::Polarity::Informational,
2566 kind: MetricKind::Rate {
2567 numerator: "total_hardirqs",
2568 denominator: "total_phase_guest_cpu_sec",
2569 },
2570 default_abs: 1.0,
2571 default_rel: 0.30,
2572 display_unit: "irq/cpu-s",
2573 accessor: |_| None,
2574 },
2575 MetricDef {
2576 // NET_RX softirq activity per delivered guest CPU-second.
2577 name: "net_rx_softirqs_per_cpu_sec",
2578 polarity: crate::test_support::Polarity::Informational,
2579 kind: MetricKind::Rate {
2580 numerator: "total_softirq_net_rx",
2581 denominator: "total_phase_guest_cpu_sec",
2582 },
2583 default_abs: 1.0,
2584 default_rel: 0.30,
2585 display_unit: "softirq/cpu-s",
2586 accessor: |_| None,
2587 },
2588 MetricDef {
2589 // DERIVED rate: total_irq_time_ns / total delivered guest CPU ns. Both
2590 // are cross-CPU sums over the same endpoints, so this is a true [0,1]
2591 // fraction on wide VMs and excludes host-stolen time.
2592 name: "irq_time_fraction",
2593 polarity: crate::test_support::Polarity::LowerBetter,
2594 kind: MetricKind::Rate {
2595 numerator: "total_irq_time_ns",
2596 denominator: "total_phase_guest_cpu_ns",
2597 },
2598 default_abs: 0.02,
2599 default_rel: 0.30,
2600 display_unit: "",
2601 accessor: |_| None,
2602 },
2603 MetricDef {
2604 // Hidden rate-denominator component: delivered guest CPU seconds across
2605 // all vCPUs over the IRQ counter endpoints, excluding steal.
2606 name: "total_phase_guest_cpu_sec",
2607 polarity: crate::test_support::Polarity::Informational,
2608 kind: MetricKind::Counter,
2609 default_abs: 0.1,
2610 default_rel: 0.30,
2611 display_unit: "s",
2612 accessor: |_| None,
2613 },
2614 MetricDef {
2615 // Nanosecond twin of total_phase_guest_cpu_sec for irq_time_fraction.
2616 name: "total_phase_guest_cpu_ns",
2617 polarity: crate::test_support::Polarity::Informational,
2618 kind: MetricKind::Counter,
2619 default_abs: 1000.0,
2620 default_rel: 0.30,
2621 display_unit: "ns",
2622 accessor: |_| None,
2623 },
2624 MetricDef {
2625 // Per-CPU IRQ spatial axis: the BUSIEST CPU's hardirq delta over the
2626 // phase — max over CPUs of each CPU's (last - first freeze) irqs_sum,
2627 // correlated by the per_cpu_time cpu field (NOT the cross-CPU sum, which
2628 // is total_hardirqs). Custom per-CPU-delta fold in assert::phase_build,
2629 // NOT a read_sample arm (read_sample yields one f64 per freeze, no
2630 // per-CPU vector). Peak = spatial-max of a per-CPU cumulative-counter
2631 // delta. Informational: a high busiest-CPU count is ambiguous (high
2632 // traffic vs concentration) — the concentration ratio below is the
2633 // balance signal, mirroring the raw-counts-Informational split.
2634 name: "max_cpu_hardirqs",
2635 polarity: crate::test_support::Polarity::Informational,
2636 kind: MetricKind::Peak,
2637 default_abs: 10.0,
2638 default_rel: 0.50,
2639 display_unit: "",
2640 accessor: |_| None,
2641 },
2642 MetricDef {
2643 // IRQ-concentration ratio: max_cpu_hardirqs / mean per-CPU hardirq delta
2644 // over the SAME reporting-CPU set — the busiest CPU's share of the
2645 // average. Range [1, num_cpus]: 1.0 = perfectly even, higher = IRQs
2646 // concentrated on one CPU. Peak (worst per-phase concentration),
2647 // LowerBetter. Computed in the same per-CPU-delta fold, NOT a Rate (a
2648 // Peak numerator fails every_rate_metric_has_registered_counter_components,
2649 // and max/mean is not Σ-poolable). DELIBERATELY max/MEAN, distinct from
2650 // the sibling max_imbalance_ratio's max/MIN: max/min explodes when any
2651 // CPU takes ~0 IRQs, whereas max/mean measures disproportionate SHARE
2652 // (the IRQ-steering question). Absent (None) when < 2 reporting CPUs or
2653 // mean == 0.
2654 name: "max_cpu_hardirq_concentration",
2655 polarity: crate::test_support::Polarity::LowerBetter,
2656 kind: MetricKind::Peak,
2657 default_abs: 1.0,
2658 default_rel: 0.25,
2659 display_unit: "x",
2660 accessor: |_| None,
2661 },
2662 MetricDef {
2663 // Per-CPU NET_RX softirq spatial axis: the BUSIEST CPU's NET_RX softirq
2664 // delta over the phase — max over CPUs of each CPU's (last - first freeze)
2665 // kstat.softirqs[NET_RX] delta, correlated by the per_cpu_time cpu field
2666 // (NOT the cross-CPU sum, which is total_softirq_net_rx). Counts softirq
2667 // RUNS/invocations (handle_softirqs increments once per pending NET_RX bit
2668 // per dispatch via kstat_incr_softirqs_this_cpu), NOT packets — a
2669 // softirq-frequency / affinity-concentration signal. Custom per-CPU-delta
2670 // fold in assert::phase_build (fold_per_cpu_spatial_max), NOT a read_sample
2671 // arm. Peak = spatial-max of a per-CPU cumulative-counter delta. The
2672 // softirq sibling of max_cpu_hardirqs; Informational for the same reason —
2673 // a high busiest-CPU count is ambiguous (high RX traffic vs concentration),
2674 // the concentration ratio below is the balance signal.
2675 name: "max_cpu_softirq_net_rx",
2676 polarity: crate::test_support::Polarity::Informational,
2677 kind: MetricKind::Peak,
2678 default_abs: 10.0,
2679 default_rel: 0.50,
2680 display_unit: "",
2681 accessor: |_| None,
2682 },
2683 MetricDef {
2684 // NET_RX-softirq-concentration ratio: max_cpu_softirq_net_rx / mean
2685 // per-CPU NET_RX softirq delta over the SAME reporting-CPU set — the
2686 // busiest CPU's share of the average. Range [1, num_cpus]: 1.0 = even,
2687 // higher = NET_RX softirqs concentrated on one CPU (the single-queue-NIC
2688 // vs RPS/RSS-spread signal). Peak, LowerBetter, max/mean — the softirq
2689 // sibling of max_cpu_hardirq_concentration (same NOT-a-Rate, max/MEAN-not-
2690 // max/MIN, >=2-reporting-CPU + mean>0 discipline). Absent (None) when
2691 // < 2 reporting CPUs or mean == 0.
2692 name: "max_cpu_softirq_net_rx_concentration",
2693 polarity: crate::test_support::Polarity::LowerBetter,
2694 kind: MetricKind::Peak,
2695 default_abs: 1.0,
2696 default_rel: 0.25,
2697 display_unit: "x",
2698 accessor: |_| None,
2699 },
2700 MetricDef {
2701 // Mean ACROSS CPUs of the scx_layered util-compensation SCALE over the
2702 // capture window — the factor by which a CPU's useful-work capacity is
2703 // scaled up to compensate for IRQ / softirq / stolen time. Per CPU over
2704 // the first->last per_cpu_time freeze: scale = delta_total / available,
2705 // where delta_total = Σ of ALL 8 kernel_cpustat[] ns deltas
2706 // (user+nice+system+idle+iowait+irq+softirq+steal) and available =
2707 // delta_total - (irq+softirq+steal); clamped to [1.0, 20.0], and
2708 // available == 0 yields the 1.0 floor. Byte-faithful to scx_layered's
2709 // util_compensation compute — the ns-vs-µs unit cancels in the ratio
2710 // (scx_layered reads /proc microseconds; we read kernel_cpustat ns, the
2711 // same slots /proc/stat formats from). 1.0 = no IRQ/steal interference;
2712 // higher = more capacity stolen, so LowerBetter. An idle ktstr VM reads
2713 // exactly 1.0 — the MEASURED clamp floor (a real Some), NOT loud-absent;
2714 // a compensation > 1.0 requires an IRQ/steal-generating workload.
2715 // Gauge(Avg): cross-phase folds weighted-mean to run-level, cross-run
2716 // means — the typical compensation magnitude. Custom per-CPU-delta fold
2717 // in assert::phase_build (fold_util_comp_scale), NOT a read_sample arm: a
2718 // per-CPU clamp-then-mean is not expressible as a scalar Counter/Rate.
2719 // System-axis mean: scx_layered clamps per-CPU then applies per-LAYER;
2720 // ktstr has no layers, so the run-level signal is the mean of the
2721 // per-CPU scale distribution. cpustat[CPUTIME_SOFTIRQ] excludes
2722 // softirq deferred to ksoftirqd (irqtime_account_irq's
2723 // curr != this_cpu_ksoftirqd() guard, kernel/sched/cputime.c) — the same
2724 // undercount scx_layered inherits from /proc, so faithful to it; the
2725 // scale is a lower bound on true IRQ+softirq pressure.
2726 name: "avg_cpu_util_comp_scale",
2727 polarity: crate::test_support::Polarity::LowerBetter,
2728 kind: MetricKind::Gauge(GaugeAgg::Avg),
2729 default_abs: 0.5,
2730 default_rel: 0.30,
2731 display_unit: "x",
2732 accessor: |_| None,
2733 },
2734 MetricDef {
2735 // Mean across (freeze, live task) of scx_lavd's per-task
2736 // normalized_lat_cri (task_ctx.normalized_lat_cri, [0,1024]) — the
2737 // scheduler's latency-criticality score, host-read from the sdt_alloc
2738 // arena (BPF_MAP_TYPE_ARENA) each freeze and BTF-rendered, NOT a kernel
2739 // counter and NOT a BPF .bss field. A GAUGE (an instantaneous per-task
2740 // value lavd recomputes each schedule, scx_lavd lat_cri.bpf.c: lat_cri is
2741 // squared then waker/wakee-propagated, normalized to [0,1024]), so folded
2742 // as a mean over every (freeze, task) observation. Informational: a
2743 // scheduler-internal decision signal with no good/bad direction.
2744 // normalized (not raw lat_cri) for cross-run comparability — raw lat_cri
2745 // is squared + propagated + load-dependent. Custom per-task fold in
2746 // assert::phase_build (fold_lat_cri), NOT a read_sample arm. Distinct from
2747 // lavd's own .bss sys_stat.avg_lat_cri EWMA over SCHEDULED tasks (surfaced
2748 // via watch_bpf_map as the scx_lavd_avg_lat_cri key) — this is an
2749 // instantaneous host walk over ALL live task_ctx, INCLUDING not-yet-scored
2750 // slots that render 0, so the mean is population-sensitive to task-alloc
2751 // churn. Loud-absent for non-lavd schedulers (the rendered payload has no
2752 // such member).
2753 name: "avg_task_lat_cri",
2754 polarity: crate::test_support::Polarity::Informational,
2755 kind: MetricKind::Gauge(GaugeAgg::Avg),
2756 default_abs: 50.0,
2757 default_rel: 0.30,
2758 display_unit: "",
2759 accessor: |_| None,
2760 },
2761 MetricDef {
2762 // Max across (freeze, live task) of scx_lavd's per-task
2763 // normalized_lat_cri ([0,1024]) — the worst-case latency-criticality
2764 // observed over the phase. Peak (spatial+temporal max of an instantaneous
2765 // gauge, no delta). Informational. Same host sdt_alloc-arena source +
2766 // per-task fold (fold_lat_cri) + normalized rationale + loud-absent as
2767 // avg_task_lat_cri.
2768 name: "max_task_lat_cri",
2769 polarity: crate::test_support::Polarity::Informational,
2770 kind: MetricKind::Peak,
2771 default_abs: 100.0,
2772 default_rel: 0.30,
2773 display_unit: "",
2774 accessor: |_| None,
2775 },
2776 MetricDef {
2777 // Per-cgroup IRQ-pressure spatial axis: the busiest workload-leaf cgroup's
2778 // PSI-irq `full` stall DELTA over the phase (decoded µs) — max over the
2779 // workload-root leaf cgroups of each leaf's (last - first freeze)
2780 // cgroup->psi total[PSI_AVGS][PSI_IRQ_FULL], correlated across freezes by
2781 // (cgroup_kva, serial_nr) — the serial disambiguates a freed slab KVA
2782 // reused by a new cgroup. The per-cgroup analog of max_cpu_hardirqs (the
2783 // busiest-CELL dimension);
2784 // attributes IRQ-servicing stall to the workload cell that induced it,
2785 // which the system-wide total_irq_pressure_us cannot. Custom per-cgroup
2786 // delta fold (assert::phase_build fold_per_cgroup_psi), NOT a read_sample
2787 // arm. Peak = spatial-max of a per-cgroup cumulative-counter delta.
2788 // Informational: an absolute per-cell stall is workload-confounded (more
2789 // work → more stall) — the concentration ratio below is the isolation
2790 // signal, mirroring the max_cpu_hardirqs raw-counts split.
2791 name: "max_cgroup_irq_pressure",
2792 polarity: crate::test_support::Polarity::Informational,
2793 kind: MetricKind::Peak,
2794 default_abs: 1.0,
2795 default_rel: 0.50,
2796 display_unit: "µs",
2797 accessor: |_| None,
2798 },
2799 MetricDef {
2800 // Per-cgroup IRQ-pressure concentration: max_cgroup_irq_pressure / the
2801 // mean per-leaf IRQ-full stall delta over the SAME reporting-leaf set —
2802 // the busiest cell's share of the average. Range [1, num_leaves]: 1.0 =
2803 // evenly spread, higher = IRQ-servicing stall concentrated on one workload
2804 // cell (the cgroup-isolation / cell-steering signal). Peak, LowerBetter,
2805 // max/MEAN — the per-cgroup sibling of max_cpu_hardirq_concentration (same
2806 // NOT-a-Rate, max/MEAN-not-max/MIN, >=2-reporting-leaf + mean>0 discipline;
2807 // disjoint leaves — cgroup2's no-internal-process rule — so no
2808 // double-count). Absent (None) when < 2 reporting leaves or mean == 0.
2809 name: "max_cgroup_irq_pressure_concentration",
2810 polarity: crate::test_support::Polarity::LowerBetter,
2811 kind: MetricKind::Peak,
2812 default_abs: 1.0,
2813 default_rel: 0.25,
2814 display_unit: "x",
2815 accessor: |_| None,
2816 },
2817 MetricDef {
2818 // Per-cgroup IRQ-pressure GAUGE: the worst workload-leaf cgroup's PSI-irq
2819 // `full` avg10 (decoded 10s-EWMA percent, 0..=100) — per freeze the max
2820 // across the leaves, then the max across the phase's freezes. The
2821 // instantaneous-pressure companion to max_cgroup_irq_pressure (a gauge, so
2822 // a spatial-max with no delta — the max_avg_irq_util shape on the cgroup
2823 // axis). Peak; LowerBetter (less IRQ pressure on the worst cell is better).
2824 // Custom fold (fold_per_cgroup_psi), NOT a read_sample arm. Loud-absent
2825 // when no leaf reported PSI (psi_cgroups off / absent workload root).
2826 name: "max_cgroup_psi_irq_avg10",
2827 polarity: crate::test_support::Polarity::LowerBetter,
2828 kind: MetricKind::Peak,
2829 default_abs: 5.0,
2830 default_rel: 0.30,
2831 display_unit: "%",
2832 accessor: |_| None,
2833 },
2834 MetricDef {
2835 // System-wide PSI-irq `full` avg10: the mean over monitor samples of the
2836 // decoded 10s-EWMA full IRQ pressure (percent, 0..=100), host-walked from
2837 // the global `psi_system` (NOT a guest /proc read). Gauge(Avg) like
2838 // `avg_irq_util` — an instantaneous smoothed gauge, never deltaed; the
2839 // cross-run fold sample-weights it. LowerBetter (less IRQ pressure is
2840 // better). ext-only (accessor |_| None), folded from MonitorSummary in
2841 // group::sidecar_to_row. Loud-absent (None) when CONFIG_PSI /
2842 // CONFIG_IRQ_TIME_ACCOUNTING is off (no PSI_IRQ_FULL in BTF), never 0.0.
2843 name: "psi_irq_full_avg10",
2844 polarity: crate::test_support::Polarity::LowerBetter,
2845 kind: MetricKind::Gauge(GaugeAgg::Avg),
2846 default_abs: 5.0,
2847 default_rel: 0.30,
2848 display_unit: "%",
2849 accessor: |_| None,
2850 },
2851 MetricDef {
2852 // Cumulative system-wide PSI-irq `full` stall over the monitoring window
2853 // (µs): the end-start delta of `total[PSI_AVGS][PSI_IRQ_FULL]` (decoded
2854 // ns→µs), host-walked from `psi_system`. Counter (a monotonic cumulative
2855 // total, end-start deltaed; saturating on reset) like `total_irq_time_ns`,
2856 // so the cross-run fold Σ-pools it. Informational: an absolute stall time
2857 // is workload-confounded (longer run → more stall) — the avg10 gauge is
2858 // the magnitude-normalized signal; mirrors the total_irq_time_ns split.
2859 // ext-only, same loud-absent gate as `psi_irq_full_avg10`.
2860 name: "total_irq_pressure_us",
2861 polarity: crate::test_support::Polarity::Informational,
2862 kind: MetricKind::Counter,
2863 default_abs: 1.0,
2864 default_rel: 0.50,
2865 display_unit: "µs",
2866 accessor: |_| None,
2867 },
2868 MetricDef {
2869 // Mean schedstat run-delay, re-pooled as the mean over the COMBINED
2870 // run-delay sample set across every cgroup (and phase), RAW ns→µs
2871 // once — see `worst_p99_wake_latency_us`. Each sample is one per-WORKER
2872 // cumulative sched_info.run_delay total (NOT per-dispatch), so the pool
2873 // size is the worker count — see
2874 // [`crate::assert::PhaseCgroupStats::run_delays_ns`]. Distribution kind;
2875 // accessor |_| None (ext_metrics-sourced from the re-pool).
2876 name: "worst_mean_run_delay_us",
2877 polarity: crate::test_support::Polarity::LowerBetter,
2878 kind: MetricKind::Distribution {
2879 source: SampleSource::RunDelayNs,
2880 reduction: SampleReduction::Mean,
2881 },
2882 default_abs: 50.0,
2883 default_rel: 0.25,
2884 display_unit: "\u{00b5}s",
2885 accessor: |_| None,
2886 },
2887 MetricDef {
2888 // Worst (max) schedstat run-delay over the combined run-delay sample
2889 // set, RAW ns→µs once. Distribution kind with the Worst reduction:
2890 // the one Distribution reduction whose cross-RUN fold is MAX (the
2891 // peak survives), not MEAN — see [`crate::stats::SampleReduction::Worst`].
2892 name: "worst_run_delay_us",
2893 polarity: crate::test_support::Polarity::LowerBetter,
2894 kind: MetricKind::Distribution {
2895 source: SampleSource::RunDelayNs,
2896 reduction: SampleReduction::Worst,
2897 },
2898 default_abs: 100.0,
2899 default_rel: 0.50,
2900 display_unit: "\u{00b5}s",
2901 accessor: |_| None,
2902 },
2903 MetricDef {
2904 // Ratio of p99 / median wake latency, worst-case across
2905 // cgroups. `LowerBetter` because a higher ratio signals a
2906 // stretched long tail. Unitless; baseline is 1.0 (p99 == median
2907 // is the perfect-uniform floor set by order-statistic
2908 // ordering). `default_abs = 0.5` guards against trivially
2909 // small deltas that percent-only gates would flag; `default_rel
2910 // = 0.25` matches the wake-latency metrics' percent gate.
2911 //
2912 // BASIS: the per-cgroup worst — the MAX over each cgroup's own
2913 // p99/median ratio (`CgroupStats::wake_latency_tail_ratio`), selected
2914 // post-merge over `stats.cgroups`. Deliberately NOT
2915 // `pooled_p99 / pooled_median` of the `worst_p99_wake_latency_us` /
2916 // `worst_median_wake_latency_us` Distributions (those re-pool the
2917 // cross-cgroup union), so the two do not satisfy
2918 // `tail_ratio == pooled_p99/pooled_median`.
2919 //
2920 // CROSS-RUN FOLD = unweighted exclude-missing MEAN (NOT MAX), by
2921 // design. `MetricKind::WakeLatencyTailRatio` is a WITHIN-RUN
2922 // worst-across-cgroups selector; cross-RUN `aggregate_finite`
2923 // MEAN-folds the per-run worst values over ONLY the runs that cleared
2924 // the floor (divisor = present-finite-contributor count), so a cohort
2925 // of repeated runs reports its TYPICAL worst-cgroup tail amplification
2926 // — the operator-facing cohort-comparison default shared with every
2927 // WorstLowest selector. It deliberately does NOT fold by MAX: MAX
2928 // (peak-of-peaks) is reserved for `SampleReduction::Worst`
2929 // (worst_run_delay_us), a peak DETECTOR; this answers "what is this
2930 // cohort's characteristic worst-cgroup tail". Aligning worst-across
2931 // selectors to a cross-RUN extremum is a tracked product decision (see
2932 // the EXTREMUM ASYMMETRY note in `aggregate_finite`), not this fix.
2933 //
2934 // Samples-required noise gate, enforced at the PRODUCER (not an
2935 // accessor): `crate::assert::populate_run_distribution_metrics` emits
2936 // NO ext key when the run completed fewer than
2937 // [`WAKE_LATENCY_TAIL_RATIO_MIN_ITERATIONS`] iterations (with few
2938 // samples the p99 estimate is effectively the observed maximum and the
2939 // ratio is dominated by a single outlier, not a distributional signal),
2940 // and none when no cgroup carried a measurable tail. An absent key is
2941 // EXCLUDED from the cross-RUN mean (no sub-threshold run dilutes the
2942 // cohort) and read as `None` by `compare_rows`, where the `(None,
2943 // None)` arm skips the pair entirely (no verdict, no coverage diff).
2944 // This REPLACES the deleted
2945 // typed field's accessor gate, which (a) summed every passing run's raw
2946 // ratio over `passes_observed` cross-RUN — folding noisy low-N runs in
2947 // as real values — and (b) re-gated the AGGREGATED row against a MEANED
2948 // iteration count. See [`WAKE_LATENCY_TAIL_RATIO_MIN_ITERATIONS`] for
2949 // the threshold-value rationale.
2950 //
2951 // accessor |_| None: ext_metrics-sourced from the post-merge producer.
2952 name: "worst_wake_latency_tail_ratio",
2953 polarity: crate::test_support::Polarity::LowerBetter,
2954 kind: MetricKind::WakeLatencyTailRatio,
2955 default_abs: 0.5,
2956 default_rel: 0.25,
2957 display_unit: "x",
2958 accessor: |_| None,
2959 },
2960 MetricDef {
2961 // Per-worker iteration throughput, worst (lowest) cgroup.
2962 // `HigherBetter` mirrors [`total_iterations`]: a cgroup that
2963 // fell behind regresses this downward, and a cross-variant
2964 // improvement raises it. `default_abs = 10.0` is the absolute
2965 // iteration-count floor below which deltas are noise;
2966 // `default_rel = 0.10` mirrors the `total_iterations` gate.
2967 //
2968 // Derivation of `abs = 10`: this metric is PER-WORKER. In-tree
2969 // fixtures span `workers_per_cgroup` from 1 through 8 (see
2970 // the KtstrTestEntry declarations under src/scenario/*.rs and
2971 // tests/*.rs); `CtxBuilder`'s `workers_per_cgroup`
2972 // defaults to 1, with scenario-level overrides raising it. A
2973 // per-worker floor of 10 therefore corresponds to
2974 // aggregate regressions of 10-80 total iterations across the
2975 // supported worker counts — high enough that a lightly-
2976 // loaded scheduler's jitter does not flag a regression, low
2977 // enough that a genuine drop (e.g. a cgroup that fell behind
2978 // by 10 iterations at workers=1, or 80 at workers=8) still
2979 // trips the gate. Going below 10 would flag normal cross-run
2980 // jitter on single-worker configs; going above 10 would mask
2981 // regressions on low-worker-count tests. The `rel=0.10`
2982 // companion gate handles larger throughputs proportionally,
2983 // so the `abs=10` floor only binds in the small-count regime
2984 // where rel-only would let single-digit losses slip through.
2985 //
2986 // WorstLowest kind: the lowest (worst) cgroup's
2987 // total_iterations / num_workers, re-pooled post-merge by
2988 // `crate::assert::populate_run_distribution_metrics` from the
2989 // per-cgroup counters via the None-aware lowest-wins fold (a
2990 // measured Some(0.0) wins; a no-workers None is skipped). Accessor
2991 // |_| None — ext_metrics-sourced; an all-None cohort writes no key.
2992 name: "worst_iterations_per_worker",
2993 polarity: crate::test_support::Polarity::Informational,
2994 kind: MetricKind::WorstLowest {
2995 numerator: WorstLowestNumerator::Iterations,
2996 denominator: WorstLowestDenominator::NumWorkers,
2997 },
2998 default_abs: 10.0,
2999 default_rel: 0.10,
3000 display_unit: "",
3001 accessor: |_| None,
3002 },
3003 MetricDef {
3004 // Overcommit-INVARIANT per-cgroup efficiency (iterations per
3005 // CPU-second). `HigherBetter`: a cgroup that lost efficiency
3006 // regresses this downward. Unlike worst_iterations_per_worker
3007 // (raw work, scales with the host-CPU budget), this is the metric
3008 // to compare across `cpu_budget` settings — the overcommit marker
3009 // and compare-path warning point operators here.
3010 //
3011 // `default_rel = 0.10` is the binding proportional gate (a 10%
3012 // efficiency change is the regression signal), mirroring the
3013 // per-worker sibling. `default_abs = 10.0` (iterations/CPU-second)
3014 // is a near-zero noise floor: for any real busy workload the rate
3015 // is orders of magnitude larger, so the floor only binds for a
3016 // near-idle cgroup, where it stops a large rel% on a tiny rate
3017 // from flagging jitter. Distinct from the per-worker metric's
3018 // floor (which scales with worker count) — this is a per-second
3019 // rate, so the floor is a flat anti-noise guard, not a per-worker
3020 // derivation.
3021 //
3022 // WorstLowest kind: the lowest (worst) cgroup's
3023 // total_iterations / (total_cpu_time_ns / 1e9), re-pooled post-merge
3024 // by `crate::assert::populate_run_distribution_metrics` (None when a
3025 // cgroup has no workers or no on-CPU time; lowest measured wins).
3026 // Accessor |_| None — ext_metrics-sourced.
3027 name: "worst_iterations_per_cpu_sec",
3028 polarity: crate::test_support::Polarity::HigherBetter,
3029 kind: MetricKind::WorstLowest {
3030 numerator: WorstLowestNumerator::Iterations,
3031 denominator: WorstLowestDenominator::CpuTimeNs,
3032 },
3033 default_abs: 10.0,
3034 default_rel: 0.10,
3035 // Same physical quantity as the pooled iteration_rate;
3036 // share its unit string rather than leaving this one under-specified.
3037 display_unit: "iter/cpu-s",
3038 accessor: |_| None,
3039 },
3040 MetricDef {
3041 // The WORST (lowest) per-cgroup page-locality fraction across the run.
3042 // HigherBetter, so lowest-wins = worst — a WorstLowest selector
3043 // (None-aware: a measured 0.0, all pages off-node, WINS the lowest; a
3044 // cgroup that measured no NUMA pages is skipped, not a 0.0 sentinel).
3045 // Re-pooled post-merge from the per-phase NUMA carriers
3046 // (assert::populate_run_distribution_metrics, numa_agg_per_cgroup) — NOT
3047 // a typed field: the reports-only CgroupStats hardcodes page_locality 0.0
3048 // (no expected-node set), and the prior typed Gauge field folded via
3049 // fold_lowest_nonzero, which SKIPPED a measured 0.0 and reported a
3050 // better-than-worst cross-run value. accessor None: ext-sourced.
3051 name: "worst_page_locality",
3052 polarity: crate::test_support::Polarity::HigherBetter,
3053 kind: MetricKind::WorstLowest {
3054 numerator: WorstLowestNumerator::NumaLocal,
3055 denominator: WorstLowestDenominator::NumaTotal,
3056 },
3057 default_abs: 0.05,
3058 default_rel: 0.10,
3059 display_unit: "",
3060 accessor: |_| None,
3061 },
3062 MetricDef {
3063 // The WORST (highest) per-cgroup cross-node migration-churn ratio across
3064 // the run. LowerBetter, so highest-wins = worst — a WorstCrossNodeRatio
3065 // max-selector re-pooled post-merge from the per-phase NUMA carriers
3066 // (assert::populate_run_distribution_metrics, numa_agg_per_cgroup) — NOT a
3067 // typed field: the prior typed Gauge(Last) field/GauntletRow column was
3068 // merge-max-folded within-run but cross-run averaged each run's value over
3069 // passes_observed (folding a NUMA-less run's 0.0 sentinel in), AND diverged
3070 // from run_metric (which already re-derived from the per-phase carriers), so
3071 // the sidecar and the in-test read gave different values on multi-phase
3072 // runs. accessor None: ext-sourced.
3073 name: "worst_cross_node_migration_ratio",
3074 polarity: crate::test_support::Polarity::LowerBetter,
3075 kind: MetricKind::WorstCrossNodeRatio,
3076 default_abs: 0.05,
3077 default_rel: 0.20,
3078 display_unit: "",
3079 accessor: |_| None,
3080 },
3081 // -- schbench per-phase metrics (MetricKind::PerPhase) --
3082 // Derived ONCE per phase by `crate::assert::derive_phase_metrics`
3083 // from the phase's pooled schbench histograms / run-delay raw pairs, written
3084 // directly into `PhaseBucket::metrics`. is_derived (skipped by the within-run
3085 // reducers + the phase-bucket merge) with no run-level producer; a per-phase
3086 // A/B claim reads them via `phase_metric`. `accessor: |_| None` — they never
3087 // live on a `GauntletRow`. Latency p50/p90 mirror worst_median_wake_latency_us
3088 // (abs 20), p99/p999 + sched-delay mirror worst_p99/mean (abs 50); all rel 0.25.
3089 MetricDef {
3090 name: SCHBENCH_WAKEUP_P50_US,
3091 polarity: crate::test_support::Polarity::LowerBetter,
3092 kind: MetricKind::PerPhase,
3093 default_abs: 20.0,
3094 default_rel: 0.25,
3095 display_unit: "\u{00b5}s",
3096 accessor: |_| None,
3097 },
3098 MetricDef {
3099 name: SCHBENCH_WAKEUP_P90_US,
3100 polarity: crate::test_support::Polarity::LowerBetter,
3101 kind: MetricKind::PerPhase,
3102 default_abs: 20.0,
3103 default_rel: 0.25,
3104 display_unit: "\u{00b5}s",
3105 accessor: |_| None,
3106 },
3107 MetricDef {
3108 name: SCHBENCH_WAKEUP_P99_US,
3109 polarity: crate::test_support::Polarity::LowerBetter,
3110 kind: MetricKind::PerPhase,
3111 default_abs: 50.0,
3112 default_rel: 0.25,
3113 display_unit: "\u{00b5}s",
3114 accessor: |_| None,
3115 },
3116 MetricDef {
3117 name: SCHBENCH_WAKEUP_P999_US,
3118 polarity: crate::test_support::Polarity::LowerBetter,
3119 kind: MetricKind::PerPhase,
3120 default_abs: 50.0,
3121 default_rel: 0.25,
3122 display_unit: "\u{00b5}s",
3123 accessor: |_| None,
3124 },
3125 MetricDef {
3126 name: SCHBENCH_REQUEST_P50_US,
3127 polarity: crate::test_support::Polarity::LowerBetter,
3128 kind: MetricKind::PerPhase,
3129 default_abs: 20.0,
3130 default_rel: 0.25,
3131 display_unit: "\u{00b5}s",
3132 accessor: |_| None,
3133 },
3134 MetricDef {
3135 name: SCHBENCH_REQUEST_P90_US,
3136 polarity: crate::test_support::Polarity::LowerBetter,
3137 kind: MetricKind::PerPhase,
3138 default_abs: 20.0,
3139 default_rel: 0.25,
3140 display_unit: "\u{00b5}s",
3141 accessor: |_| None,
3142 },
3143 MetricDef {
3144 name: SCHBENCH_REQUEST_P99_US,
3145 polarity: crate::test_support::Polarity::LowerBetter,
3146 kind: MetricKind::PerPhase,
3147 default_abs: 50.0,
3148 default_rel: 0.25,
3149 display_unit: "\u{00b5}s",
3150 accessor: |_| None,
3151 },
3152 MetricDef {
3153 name: SCHBENCH_REQUEST_P999_US,
3154 polarity: crate::test_support::Polarity::LowerBetter,
3155 kind: MetricKind::PerPhase,
3156 default_abs: 50.0,
3157 default_rel: 0.25,
3158 display_unit: "\u{00b5}s",
3159 accessor: |_| None,
3160 },
3161 MetricDef {
3162 name: SCHBENCH_SCHED_DELAY_MSG_US,
3163 polarity: crate::test_support::Polarity::LowerBetter,
3164 kind: MetricKind::PerPhase,
3165 default_abs: 50.0,
3166 default_rel: 0.25,
3167 display_unit: "\u{00b5}s",
3168 accessor: |_| None,
3169 },
3170 MetricDef {
3171 name: SCHBENCH_SCHED_DELAY_WORKER_US,
3172 polarity: crate::test_support::Polarity::LowerBetter,
3173 kind: MetricKind::PerPhase,
3174 default_abs: 50.0,
3175 default_rel: 0.25,
3176 display_unit: "\u{00b5}s",
3177 accessor: |_| None,
3178 },
3179 MetricDef {
3180 // Raw completed cycles in a fixed wall-time phase. Diagnostic only;
3181 // schbench_loops_per_cpu_sec is the directional throughput metric.
3182 name: SCHBENCH_LOOP_COUNT,
3183 polarity: crate::test_support::Polarity::Informational,
3184 kind: MetricKind::PerPhase,
3185 default_abs: 1.0,
3186 default_rel: 0.30,
3187 display_unit: "",
3188 accessor: |_| None,
3189 },
3190 // taobench per-phase CPU-throughput + hit ratios (WorkType::Taobench engine,
3191 // derived by write_taobench_scalars). total/fast throughput HigherBetter; slow throughput
3192 // + hit_ratio + hit_rate Informational (a component / run-validity signals,
3193 // never a regression direction — see classify_direction). The throughput keys are
3194 // CPU-SECOND denominated (ops per client CPU-second received — dilation-safe;
3195 // wall reconstructs as rate / D via the sidecar's host_dilation); the
3196 // CPU denomination is explicit in each key.
3197 MetricDef {
3198 name: TAOBENCH_TOTAL_OPS_PER_CPU_SEC,
3199 polarity: crate::test_support::Polarity::HigherBetter,
3200 kind: MetricKind::PerPhase,
3201 default_abs: 10.0,
3202 default_rel: 0.10,
3203 display_unit: "ops/cpu-s",
3204 accessor: |_| None,
3205 },
3206 MetricDef {
3207 name: TAOBENCH_FAST_OPS_PER_CPU_SEC,
3208 polarity: crate::test_support::Polarity::HigherBetter,
3209 kind: MetricKind::PerPhase,
3210 default_abs: 10.0,
3211 default_rel: 0.10,
3212 display_unit: "ops/cpu-s",
3213 accessor: |_| None,
3214 },
3215 MetricDef {
3216 name: TAOBENCH_SLOW_OPS_PER_CPU_SEC,
3217 polarity: crate::test_support::Polarity::Informational,
3218 kind: MetricKind::PerPhase,
3219 default_abs: 10.0,
3220 default_rel: 0.10,
3221 display_unit: "ops/cpu-s",
3222 accessor: |_| None,
3223 },
3224 MetricDef {
3225 name: TAOBENCH_HIT_RATIO,
3226 polarity: crate::test_support::Polarity::Informational,
3227 kind: MetricKind::PerPhase,
3228 default_abs: 0.02,
3229 default_rel: 0.05,
3230 display_unit: "",
3231 accessor: |_| None,
3232 },
3233 MetricDef {
3234 name: TAOBENCH_HIT_RATE,
3235 polarity: crate::test_support::Polarity::Informational,
3236 kind: MetricKind::PerPhase,
3237 default_abs: 0.02,
3238 default_rel: 0.05,
3239 display_unit: "",
3240 accessor: |_| None,
3241 },
3242 // taobench per-phase open-loop SERVE-LATENCY percentiles (µs, LowerBetter,
3243 // PerPhase): the coordinated-omission serve distribution per phase. Thresholds
3244 // mirror the schbench per-phase latency siblings (p50/p90/min abs 20; p99/p999
3245 // abs 50; max abs 50 / rel 0.50 for the noisier tail). Absent in closed loop.
3246 MetricDef {
3247 name: TAOBENCH_SERVE_P50_US,
3248 polarity: crate::test_support::Polarity::LowerBetter,
3249 kind: MetricKind::PerPhase,
3250 default_abs: 20.0,
3251 default_rel: 0.25,
3252 display_unit: "\u{00b5}s",
3253 accessor: |_| None,
3254 },
3255 MetricDef {
3256 name: TAOBENCH_SERVE_P90_US,
3257 polarity: crate::test_support::Polarity::LowerBetter,
3258 kind: MetricKind::PerPhase,
3259 default_abs: 20.0,
3260 default_rel: 0.25,
3261 display_unit: "\u{00b5}s",
3262 accessor: |_| None,
3263 },
3264 MetricDef {
3265 name: TAOBENCH_SERVE_P99_US,
3266 polarity: crate::test_support::Polarity::LowerBetter,
3267 kind: MetricKind::PerPhase,
3268 default_abs: 50.0,
3269 default_rel: 0.25,
3270 display_unit: "\u{00b5}s",
3271 accessor: |_| None,
3272 },
3273 MetricDef {
3274 name: TAOBENCH_SERVE_P999_US,
3275 polarity: crate::test_support::Polarity::LowerBetter,
3276 kind: MetricKind::PerPhase,
3277 default_abs: 50.0,
3278 default_rel: 0.25,
3279 display_unit: "\u{00b5}s",
3280 accessor: |_| None,
3281 },
3282 MetricDef {
3283 name: TAOBENCH_SERVE_MIN_US,
3284 polarity: crate::test_support::Polarity::LowerBetter,
3285 kind: MetricKind::PerPhase,
3286 default_abs: 20.0,
3287 default_rel: 0.25,
3288 display_unit: "\u{00b5}s",
3289 accessor: |_| None,
3290 },
3291 MetricDef {
3292 name: TAOBENCH_SERVE_MAX_US,
3293 polarity: crate::test_support::Polarity::LowerBetter,
3294 kind: MetricKind::PerPhase,
3295 default_abs: 50.0,
3296 default_rel: 0.50,
3297 display_unit: "\u{00b5}s",
3298 accessor: |_| None,
3299 },
3300 // taobench WHOLE-RUN CPU-throughput + hit Rates and their Counter components, pooled
3301 // cross-cgroup by `crate::assert::populate_run_pooled_taobench` and derived
3302 // by `derive_rate_metrics`. The four `total_taobench_*` Counters are the rate
3303 // components (ext_metrics-only, accessor |_| None; `total_` prefix satisfies
3304 // the Counter naming gate) and are `RENDER_SUPPRESSED_COMPONENTS`, so their
3305 // default_abs/default_rel are inert at the compare layer — the entries exist
3306 // for the re-pool (`name` is the component key, `kind` drives the Counter
3307 // SUM-fold). Cross-RUN each component SUMs, so the Rates re-pool as
3308 // Σnumerator / Σdenominator (aggregate throughput, not a mean of per-run rates).
3309 // HIT is exposed whole-run BOTH ways: the RESPONSE-time taobench_hit_fraction
3310 // (Σfast/Σcompleted) AND the COMMAND-time taobench_command_hit_rate (Σhits/Σcmds,
3311 // hits = cmds − misses — the whole-run analog of the per-phase
3312 // taobench_hit_rate). Under closed-loop every issued lookup completes so the
3313 // two converge; under OPEN-LOOP arrival they diverge (a slow/overloaded run
3314 // issues lookups that have not yet completed), which is why both carry distinct
3315 // --noise-adjust spread and both are registered.
3316 MetricDef {
3317 name: TOTAL_TAOBENCH_OPS,
3318 polarity: crate::test_support::Polarity::Informational,
3319 kind: MetricKind::Counter,
3320 default_abs: 10.0,
3321 default_rel: 0.10,
3322 display_unit: "",
3323 accessor: |_| None,
3324 },
3325 MetricDef {
3326 name: TOTAL_TAOBENCH_FAST_OPS,
3327 polarity: crate::test_support::Polarity::Informational,
3328 kind: MetricKind::Counter,
3329 default_abs: 10.0,
3330 default_rel: 0.10,
3331 display_unit: "",
3332 accessor: |_| None,
3333 },
3334 MetricDef {
3335 name: TOTAL_TAOBENCH_SLOW_OPS,
3336 polarity: crate::test_support::Polarity::Informational,
3337 kind: MetricKind::Counter,
3338 default_abs: 10.0,
3339 default_rel: 0.10,
3340 display_unit: "",
3341 accessor: |_| None,
3342 },
3343 MetricDef {
3344 // Whole-run wall window (ns→s applied once at the producer). Counter —
3345 // cross-RUN SUM, mirroring `total_cpu_time_sec`. NOT the qps
3346 // denominator anymore (that is `total_taobench_cpu_sec`); kept as
3347 // window EVIDENCE from which the wall picture reconstructs exactly
3348 // (Σops / Σwall). `total_` prefix satisfies the Counter naming gate.
3349 name: TOTAL_TAOBENCH_WALL_SEC,
3350 polarity: crate::test_support::Polarity::Informational,
3351 kind: MetricKind::Counter,
3352 default_abs: 1.0,
3353 default_rel: 0.30,
3354 display_unit: "s",
3355 accessor: |_| None,
3356 },
3357 MetricDef {
3358 // Whole-run Σ client-thread CLOCK_THREAD_CPUTIME_ID window (ns→s at
3359 // the producer) — the qps DENOMINATOR (rate component; suppressed).
3360 // Dispatcher CPU excluded (modeled backing-store latency, not
3361 // workload throughput CPU).
3362 name: TOTAL_TAOBENCH_CPU_SEC,
3363 polarity: crate::test_support::Polarity::Informational,
3364 kind: MetricKind::Counter,
3365 default_abs: 1.0,
3366 default_rel: 0.30,
3367 display_unit: "s",
3368 accessor: |_| None,
3369 },
3370 MetricDef {
3371 // Whole-run total throughput = Σcompleted ops / Σclient CPU-seconds
3372 // received (CPU-SECOND denominated — dilation-safe; the wall picture
3373 // reconstructs as `rate / D` via the sidecar's `host_dilation`, or
3374 // exactly as Σops / `total_taobench_wall_sec`). HigherBetter
3375 // (throughput). Shares the per-phase
3376 // `taobench_total_ops_per_cpu_sec` thresholds.
3377 // Absent when no Taobench cgroup ran or no client CPU was measured
3378 // (components absent).
3379 name: TAOBENCH_TOTAL_OPS_PER_CPU_SEC_WHOLE,
3380 polarity: crate::test_support::Polarity::HigherBetter,
3381 kind: MetricKind::Rate {
3382 numerator: TOTAL_TAOBENCH_OPS,
3383 denominator: TOTAL_TAOBENCH_CPU_SEC,
3384 },
3385 default_abs: 10.0,
3386 default_rel: 0.10,
3387 display_unit: "ops/cpu-s",
3388 accessor: |_| None,
3389 },
3390 MetricDef {
3391 // Whole-run hit (fast-path) throughput = Σfast ops / Σclient
3392 // CPU-seconds. HigherBetter.
3393 name: TAOBENCH_FAST_OPS_PER_CPU_SEC_WHOLE,
3394 polarity: crate::test_support::Polarity::HigherBetter,
3395 kind: MetricKind::Rate {
3396 numerator: TOTAL_TAOBENCH_FAST_OPS,
3397 denominator: TOTAL_TAOBENCH_CPU_SEC,
3398 },
3399 default_abs: 10.0,
3400 default_rel: 0.10,
3401 display_unit: "ops/cpu-s",
3402 accessor: |_| None,
3403 },
3404 MetricDef {
3405 // Whole-run slow-path throughput = Σslow ops / Σclient CPU-seconds.
3406 // Informational — the slow path is a component of total throughput, not a
3407 // standalone regression direction (mirrors the per-phase
3408 // `taobench_slow_ops_per_cpu_sec`).
3409 name: TAOBENCH_SLOW_OPS_PER_CPU_SEC_WHOLE,
3410 polarity: crate::test_support::Polarity::Informational,
3411 kind: MetricKind::Rate {
3412 numerator: TOTAL_TAOBENCH_SLOW_OPS,
3413 denominator: TOTAL_TAOBENCH_CPU_SEC,
3414 },
3415 default_abs: 10.0,
3416 default_rel: 0.10,
3417 display_unit: "ops/cpu-s",
3418 accessor: |_| None,
3419 },
3420 MetricDef {
3421 // Whole-run cache hit FRACTION = Σfast ops / Σcompleted ops — the SAME
3422 // response-time hit measurement as the per-phase `taobench_hit_ratio`, at
3423 // whole-run scope (its run-level Σ/Σ pool). The name differs only by axis:
3424 // per-phase `_ratio` vs whole-run `_fraction` — a distinct registry key is
3425 // required because a Rate cannot share a name with the per-phase PerPhase
3426 // entry, and `_fraction` reads as the pooled [0, 1] ratio-of-counters (the
3427 // throughput siblings diverge the same way: per-phase vs whole-run
3428 // `_whole`). DISTINCT from the command-time `taobench_hit_rate`
3429 // (1 - misses/cmds), which is request-time, not response-time — see the
3430 // block comment above. A fraction in [0, 1]. Informational — a hit-rate
3431 // change is a workload-shape signal, not a scheduler regression direction.
3432 // Absent when no ops completed (`total_taobench_ops` is 0 →
3433 // `derive_rate_metrics` skips the zero denominator).
3434 name: TAOBENCH_HIT_FRACTION,
3435 polarity: crate::test_support::Polarity::Informational,
3436 kind: MetricKind::Rate {
3437 numerator: TOTAL_TAOBENCH_FAST_OPS,
3438 denominator: TOTAL_TAOBENCH_OPS,
3439 },
3440 default_abs: 0.02,
3441 default_rel: 0.05,
3442 display_unit: "",
3443 accessor: |_| None,
3444 },
3445 // taobench WHOLE-RUN open-loop serve-latency percentiles (µs, LowerBetter,
3446 // PerRunDistribution): the union of the per-phase per-cgroup serve histograms,
3447 // percentile re-derived over the union by
3448 // `crate::assert::populate_run_pooled_taobench_distribution`. Noise-compared
3449 // per-run, never cross-run folded (is_derived). Thresholds mirror the
3450 // per-phase serve siblings. Absent in closed loop (no serve samples).
3451 MetricDef {
3452 name: TAOBENCH_SERVE_P50_US_WHOLE,
3453 polarity: crate::test_support::Polarity::LowerBetter,
3454 kind: MetricKind::PerRunDistribution,
3455 default_abs: 20.0,
3456 default_rel: 0.25,
3457 display_unit: "\u{00b5}s",
3458 accessor: |_| None,
3459 },
3460 MetricDef {
3461 name: TAOBENCH_SERVE_P90_US_WHOLE,
3462 polarity: crate::test_support::Polarity::LowerBetter,
3463 kind: MetricKind::PerRunDistribution,
3464 default_abs: 20.0,
3465 default_rel: 0.25,
3466 display_unit: "\u{00b5}s",
3467 accessor: |_| None,
3468 },
3469 MetricDef {
3470 name: TAOBENCH_SERVE_P99_US_WHOLE,
3471 polarity: crate::test_support::Polarity::LowerBetter,
3472 kind: MetricKind::PerRunDistribution,
3473 default_abs: 50.0,
3474 default_rel: 0.25,
3475 display_unit: "\u{00b5}s",
3476 accessor: |_| None,
3477 },
3478 MetricDef {
3479 name: TAOBENCH_SERVE_P999_US_WHOLE,
3480 polarity: crate::test_support::Polarity::LowerBetter,
3481 kind: MetricKind::PerRunDistribution,
3482 default_abs: 50.0,
3483 default_rel: 0.25,
3484 display_unit: "\u{00b5}s",
3485 accessor: |_| None,
3486 },
3487 MetricDef {
3488 name: TAOBENCH_SERVE_MIN_US_WHOLE,
3489 polarity: crate::test_support::Polarity::LowerBetter,
3490 kind: MetricKind::PerRunDistribution,
3491 default_abs: 20.0,
3492 default_rel: 0.25,
3493 display_unit: "\u{00b5}s",
3494 accessor: |_| None,
3495 },
3496 MetricDef {
3497 name: TAOBENCH_SERVE_MAX_US_WHOLE,
3498 polarity: crate::test_support::Polarity::LowerBetter,
3499 kind: MetricKind::PerRunDistribution,
3500 default_abs: 50.0,
3501 default_rel: 0.50,
3502 display_unit: "\u{00b5}s",
3503 accessor: |_| None,
3504 },
3505 // taobench WHOLE-RUN command-time hit: get_cmds + get_hits (= cmds − misses)
3506 // Counter components (ext-only, RENDER_SUPPRESSED, `total_` gate) →
3507 // taobench_command_hit_rate = Σhits/Σcmds (the request-time hit, which diverges
3508 // from the response-time taobench_hit_fraction under open-loop). Pooled by
3509 // `crate::assert::populate_run_pooled_taobench`.
3510 MetricDef {
3511 name: TOTAL_TAOBENCH_GET_CMDS,
3512 polarity: crate::test_support::Polarity::Informational,
3513 kind: MetricKind::Counter,
3514 default_abs: 10.0,
3515 default_rel: 0.10,
3516 display_unit: "",
3517 accessor: |_| None,
3518 },
3519 MetricDef {
3520 name: TOTAL_TAOBENCH_GET_HITS,
3521 polarity: crate::test_support::Polarity::Informational,
3522 kind: MetricKind::Counter,
3523 default_abs: 10.0,
3524 default_rel: 0.10,
3525 display_unit: "",
3526 accessor: |_| None,
3527 },
3528 MetricDef {
3529 name: TAOBENCH_COMMAND_HIT_RATE,
3530 polarity: crate::test_support::Polarity::Informational,
3531 kind: MetricKind::Rate {
3532 numerator: TOTAL_TAOBENCH_GET_HITS,
3533 denominator: TOTAL_TAOBENCH_GET_CMDS,
3534 },
3535 default_abs: 0.02,
3536 default_rel: 0.05,
3537 display_unit: "",
3538 accessor: |_| None,
3539 },
3540 // schbench WHOLE-RUN Class-3: role-separate run-delay gate Rates + their
3541 // Counter components + the whole-run loop Counter, re-pooled run-level by
3542 // `crate::assert::populate_run_pooled_schbench` from the per-phase per-cgroup
3543 // SchbenchPhaseStats raw pairs (Σ over phases+cgroups). The four run-delay /
3544 // pcount Counters are ext-only rate components (accessor |_| None;
3545 // RENDER_SUPPRESSED; `total_` prefix → Counter gate). The two Rates are the
3546 // sample-weighted Σrun_delay/Σpcount per-schedule means (the workload-scoped
3547 // siblings of the system-wide `total_run_delay_ns_per_sched`); message and
3548 // worker roles pool separately. The per-phase `sched_delay_msg/worker_us`
3549 // (PerPhase, display-only) is the SAME Σrun_delay_ns/Σpcount per-schedule
3550 // mean at phase scope -- NOT schbench's native mean-of-per-thread-means
3551 // (that is a separate whole-run stat on `SchbenchResult`, see
3552 // workload/schbench). Only these Rates gate, so no double-count.
3553 MetricDef {
3554 name: TOTAL_SCHBENCH_MSG_RUN_DELAY_NS,
3555 polarity: crate::test_support::Polarity::Informational,
3556 kind: MetricKind::Counter,
3557 default_abs: 1000.0,
3558 default_rel: 0.10,
3559 display_unit: "ns",
3560 accessor: |_| None,
3561 },
3562 MetricDef {
3563 name: TOTAL_SCHBENCH_MSG_PCOUNT,
3564 polarity: crate::test_support::Polarity::Informational,
3565 kind: MetricKind::Counter,
3566 default_abs: 1.0,
3567 default_rel: 0.10,
3568 display_unit: "",
3569 accessor: |_| None,
3570 },
3571 MetricDef {
3572 name: TOTAL_SCHBENCH_WORKER_RUN_DELAY_NS,
3573 polarity: crate::test_support::Polarity::Informational,
3574 kind: MetricKind::Counter,
3575 default_abs: 1000.0,
3576 default_rel: 0.10,
3577 display_unit: "ns",
3578 accessor: |_| None,
3579 },
3580 MetricDef {
3581 name: TOTAL_SCHBENCH_WORKER_PCOUNT,
3582 polarity: crate::test_support::Polarity::Informational,
3583 kind: MetricKind::Counter,
3584 default_abs: 1.0,
3585 default_rel: 0.10,
3586 display_unit: "",
3587 accessor: |_| None,
3588 },
3589 MetricDef {
3590 // Raw whole-run completed cycles. Duration and host contention affect
3591 // this total, so keep it diagnostic; use
3592 // schbench_total_loops_per_cpu_sec for directional comparison.
3593 name: TOTAL_SCHBENCH_LOOPS,
3594 polarity: crate::test_support::Polarity::Informational,
3595 kind: MetricKind::Counter,
3596 default_abs: 1.0,
3597 default_rel: 0.10,
3598 display_unit: "",
3599 accessor: |_| None,
3600 },
3601 MetricDef {
3602 // Whole-run Σ worker CLOCK_THREAD_CPUTIME_ID window (s) — the
3603 // CPU-second throughput denominator (rate component; suppressed).
3604 // Message-thread CPU excluded (schbench's Σ worker runtimes analog).
3605 name: TOTAL_SCHBENCH_WORKER_CPU_SEC,
3606 polarity: crate::test_support::Polarity::Informational,
3607 kind: MetricKind::Counter,
3608 default_abs: 1.0,
3609 default_rel: 0.30,
3610 display_unit: "s",
3611 accessor: |_| None,
3612 },
3613 MetricDef {
3614 // Whole-run CPU-SECOND throughput: Σ completed cycles / Σ worker
3615 // CPU-seconds received. Dilation-safe (host preemption inflates wall,
3616 // not CPU); the wall picture reconstructs as `rate / D` via the
3617 // sidecar's `host_dilation`. HigherBetter; shares the throughput
3618 // rel 0.10 of its numerator `total_schbench_loops`.
3619 name: SCHBENCH_TOTAL_LOOPS_PER_CPU_SEC,
3620 polarity: crate::test_support::Polarity::HigherBetter,
3621 kind: MetricKind::Rate {
3622 numerator: TOTAL_SCHBENCH_LOOPS,
3623 denominator: TOTAL_SCHBENCH_WORKER_CPU_SEC,
3624 },
3625 default_abs: 1.0,
3626 default_rel: 0.10,
3627 display_unit: "ops/cpu-s",
3628 accessor: |_| None,
3629 },
3630 MetricDef {
3631 // Per-phase CPU-SECOND throughput: the phase's completed cycles per
3632 // worker CPU-second received (same denomination as the whole-run
3633 // Rate above; PerPhase twin of `schbench_loop_count`'s window, with
3634 // the same small-sample-window rel 0.30 as `schbench_loop_count`).
3635 name: SCHBENCH_LOOPS_PER_CPU_SEC,
3636 polarity: crate::test_support::Polarity::HigherBetter,
3637 kind: MetricKind::PerPhase,
3638 default_abs: 1.0,
3639 default_rel: 0.30,
3640 display_unit: "ops/cpu-s",
3641 accessor: |_| None,
3642 },
3643 MetricDef {
3644 // Message-thread per-schedule run-delay mean = Σrun_delay_ns / Σpcount
3645 // (sample-weighted, NOT mean-of-per-run-means). LowerBetter (higher
3646 // scheduling wait is worse). Absent when no message thread was scheduled
3647 // (Σpcount == 0).
3648 name: SCHBENCH_MSG_RUN_DELAY_NS_PER_SCHED,
3649 polarity: crate::test_support::Polarity::LowerBetter,
3650 kind: MetricKind::Rate {
3651 numerator: TOTAL_SCHBENCH_MSG_RUN_DELAY_NS,
3652 denominator: TOTAL_SCHBENCH_MSG_PCOUNT,
3653 },
3654 default_abs: 100.0,
3655 default_rel: 0.10,
3656 display_unit: "ns",
3657 accessor: |_| None,
3658 },
3659 MetricDef {
3660 // Worker per-schedule run-delay mean = Σrun_delay_ns / Σpcount. LowerBetter.
3661 // Pooled SEPARATELY from the message role (different per-schedule wait
3662 // populations). Absent when no worker was scheduled (Σpcount == 0).
3663 name: SCHBENCH_WORKER_RUN_DELAY_NS_PER_SCHED,
3664 polarity: crate::test_support::Polarity::LowerBetter,
3665 kind: MetricKind::Rate {
3666 numerator: TOTAL_SCHBENCH_WORKER_RUN_DELAY_NS,
3667 denominator: TOTAL_SCHBENCH_WORKER_PCOUNT,
3668 },
3669 default_abs: 100.0,
3670 default_rel: 0.10,
3671 display_unit: "ns",
3672 accessor: |_| None,
3673 },
3674 // Per-phase latency min/max. LowerBetter (a higher min/max latency is worse).
3675 // min is a low-tail value → p50/p90 abs tier (20). max is a PEAK (a single
3676 // extreme sample, the flakiest latency stat) → the peak rel tolerance (0.50,
3677 // matching worst_gap_ms) so one outlier spike does not fabricate a regression.
3678 MetricDef {
3679 name: SCHBENCH_WAKEUP_MIN_US,
3680 polarity: crate::test_support::Polarity::LowerBetter,
3681 kind: MetricKind::PerPhase,
3682 default_abs: 20.0,
3683 default_rel: 0.25,
3684 display_unit: "\u{00b5}s",
3685 accessor: |_| None,
3686 },
3687 MetricDef {
3688 name: SCHBENCH_WAKEUP_MAX_US,
3689 polarity: crate::test_support::Polarity::LowerBetter,
3690 kind: MetricKind::PerPhase,
3691 default_abs: 50.0,
3692 default_rel: 0.50,
3693 display_unit: "\u{00b5}s",
3694 accessor: |_| None,
3695 },
3696 MetricDef {
3697 name: SCHBENCH_REQUEST_MIN_US,
3698 polarity: crate::test_support::Polarity::LowerBetter,
3699 kind: MetricKind::PerPhase,
3700 default_abs: 20.0,
3701 default_rel: 0.25,
3702 display_unit: "\u{00b5}s",
3703 accessor: |_| None,
3704 },
3705 MetricDef {
3706 name: SCHBENCH_REQUEST_MAX_US,
3707 polarity: crate::test_support::Polarity::LowerBetter,
3708 kind: MetricKind::PerPhase,
3709 default_abs: 50.0,
3710 default_rel: 0.50,
3711 display_unit: "\u{00b5}s",
3712 accessor: |_| None,
3713 },
3714 // Per-phase achieved-RPS distribution (PLIST_FOR_RPS = 20/50/90, schbench.c:130)
3715 // + min/max (schbench.c:579 stderr footer + :713-714/:1963 JSON — parity with
3716 // what schbench emits, not an extension). These are wall-throughput
3717 // diagnostics: host preemption dilutes them, so they do not produce
3718 // directional findings. schbench_loops_per_cpu_sec carries that role.
3719 //
3720 // rps min/max keep the percentile-tier rel (0.10), NOT the loosened latency-max
3721 // tier (0.50): each rps sample is a 1-second-AVERAGED rate (cycles completed that
3722 // second), not a single event like a latency sample, so an rps extreme is the
3723 // worst/best SECOND — far less flaky than a latency per-request peak, and the
3724 // worst-second is a meaningful scheduler-tail signal worth a tight gate. (The
3725 // latency-max 0.50 loosening guards single-request spikes that do not exist in the
3726 // 1s-averaged rps series.)
3727 //
3728 // rps_min is UNRELIABLE when any 0-rps (starvation) second occurs: TWO independent
3729 // paths drop a real 0 from the min. (1) Within a histogram, add_lat's min==0
3730 // sentinel (plat.rs `if min==0 || us<min`) treats 0 as "unset" — a 0 sets min=0 but
3731 // the next sample replaces it (e.g. [100,0,200] -> min=200), so min reads 0 only
3732 // when a 0 is the last min-lowering sample. (2) Across cgroups, PlatStats::combine's
3733 // `other.min != 0` guard (plat.rs:230 — correct for latency, where 0 means empty)
3734 // skips a starved cgroup's min=0 when pooling, so a 0-rps cgroup pooled with a
3735 // nonzero one leaves rps_min nonzero. rps_min is thus a trustworthy worst-second
3736 // floor only absent 0-seconds. Sustained starvation (0-seconds >= 20% of the
3737 // window) still shows in rps_p20, which reads the pooled histogram's bucket 0
3738 // (folded unconditionally, plat.rs:223-224) in both cases; a single 0-second in a longer
3739 // window is below p20 and lost from rps_min — invisible to both. Faithful to
3740 // schbench's add_lat min sentinel.
3741 MetricDef {
3742 name: SCHBENCH_RPS_P20,
3743 polarity: crate::test_support::Polarity::Informational,
3744 kind: MetricKind::PerPhase,
3745 default_abs: 10.0,
3746 default_rel: 0.10,
3747 display_unit: "req/s",
3748 accessor: |_| None,
3749 },
3750 MetricDef {
3751 name: SCHBENCH_RPS_P50,
3752 polarity: crate::test_support::Polarity::Informational,
3753 kind: MetricKind::PerPhase,
3754 default_abs: 10.0,
3755 default_rel: 0.10,
3756 display_unit: "req/s",
3757 accessor: |_| None,
3758 },
3759 MetricDef {
3760 name: SCHBENCH_RPS_P90,
3761 polarity: crate::test_support::Polarity::Informational,
3762 kind: MetricKind::PerPhase,
3763 default_abs: 10.0,
3764 default_rel: 0.10,
3765 display_unit: "req/s",
3766 accessor: |_| None,
3767 },
3768 MetricDef {
3769 name: SCHBENCH_RPS_MIN,
3770 polarity: crate::test_support::Polarity::Informational,
3771 kind: MetricKind::PerPhase,
3772 default_abs: 10.0,
3773 default_rel: 0.10,
3774 display_unit: "req/s",
3775 accessor: |_| None,
3776 },
3777 MetricDef {
3778 name: SCHBENCH_RPS_MAX,
3779 polarity: crate::test_support::Polarity::Informational,
3780 kind: MetricKind::PerPhase,
3781 default_abs: 10.0,
3782 default_rel: 0.10,
3783 display_unit: "req/s",
3784 accessor: |_| None,
3785 },
3786 // schbench WHOLE-RUN distributional metrics (MetricKind::
3787 // PerRunDistribution): each per-phase percentile/min/max above, re-pooled
3788 // run-level by populate_run_pooled_schbench_distribution (union of the
3789 // per-phase per-cgroup PlatStats histograms, percentile re-derived over the
3790 // union — the faithful percentile-of-union). Noise-compared per-run (never
3791 // cross-run folded). Thresholds + polarity + unit mirror the per-phase
3792 // sibling. Native wall-RPS siblings remain Informational. accessor |_| None
3793 // (ext-only, written by the union populate).
3794 MetricDef {
3795 name: SCHBENCH_WAKEUP_P50_US_WHOLE,
3796 polarity: crate::test_support::Polarity::LowerBetter,
3797 kind: MetricKind::PerRunDistribution,
3798 default_abs: 20.0,
3799 default_rel: 0.25,
3800 display_unit: "\u{00b5}s",
3801 accessor: |_| None,
3802 },
3803 MetricDef {
3804 name: SCHBENCH_WAKEUP_P90_US_WHOLE,
3805 polarity: crate::test_support::Polarity::LowerBetter,
3806 kind: MetricKind::PerRunDistribution,
3807 default_abs: 20.0,
3808 default_rel: 0.25,
3809 display_unit: "\u{00b5}s",
3810 accessor: |_| None,
3811 },
3812 MetricDef {
3813 name: SCHBENCH_WAKEUP_P99_US_WHOLE,
3814 polarity: crate::test_support::Polarity::LowerBetter,
3815 kind: MetricKind::PerRunDistribution,
3816 default_abs: 50.0,
3817 default_rel: 0.25,
3818 display_unit: "\u{00b5}s",
3819 accessor: |_| None,
3820 },
3821 MetricDef {
3822 name: SCHBENCH_WAKEUP_P999_US_WHOLE,
3823 polarity: crate::test_support::Polarity::LowerBetter,
3824 kind: MetricKind::PerRunDistribution,
3825 default_abs: 50.0,
3826 default_rel: 0.25,
3827 display_unit: "\u{00b5}s",
3828 accessor: |_| None,
3829 },
3830 MetricDef {
3831 name: SCHBENCH_WAKEUP_MIN_US_WHOLE,
3832 polarity: crate::test_support::Polarity::LowerBetter,
3833 kind: MetricKind::PerRunDistribution,
3834 default_abs: 20.0,
3835 default_rel: 0.25,
3836 display_unit: "\u{00b5}s",
3837 accessor: |_| None,
3838 },
3839 MetricDef {
3840 name: SCHBENCH_WAKEUP_MAX_US_WHOLE,
3841 polarity: crate::test_support::Polarity::LowerBetter,
3842 kind: MetricKind::PerRunDistribution,
3843 default_abs: 50.0,
3844 default_rel: 0.50,
3845 display_unit: "\u{00b5}s",
3846 accessor: |_| None,
3847 },
3848 MetricDef {
3849 name: SCHBENCH_REQUEST_P50_US_WHOLE,
3850 polarity: crate::test_support::Polarity::LowerBetter,
3851 kind: MetricKind::PerRunDistribution,
3852 default_abs: 20.0,
3853 default_rel: 0.25,
3854 display_unit: "\u{00b5}s",
3855 accessor: |_| None,
3856 },
3857 MetricDef {
3858 name: SCHBENCH_REQUEST_P90_US_WHOLE,
3859 polarity: crate::test_support::Polarity::LowerBetter,
3860 kind: MetricKind::PerRunDistribution,
3861 default_abs: 20.0,
3862 default_rel: 0.25,
3863 display_unit: "\u{00b5}s",
3864 accessor: |_| None,
3865 },
3866 MetricDef {
3867 name: SCHBENCH_REQUEST_P99_US_WHOLE,
3868 polarity: crate::test_support::Polarity::LowerBetter,
3869 kind: MetricKind::PerRunDistribution,
3870 default_abs: 50.0,
3871 default_rel: 0.25,
3872 display_unit: "\u{00b5}s",
3873 accessor: |_| None,
3874 },
3875 MetricDef {
3876 name: SCHBENCH_REQUEST_P999_US_WHOLE,
3877 polarity: crate::test_support::Polarity::LowerBetter,
3878 kind: MetricKind::PerRunDistribution,
3879 default_abs: 50.0,
3880 default_rel: 0.25,
3881 display_unit: "\u{00b5}s",
3882 accessor: |_| None,
3883 },
3884 MetricDef {
3885 name: SCHBENCH_REQUEST_MIN_US_WHOLE,
3886 polarity: crate::test_support::Polarity::LowerBetter,
3887 kind: MetricKind::PerRunDistribution,
3888 default_abs: 20.0,
3889 default_rel: 0.25,
3890 display_unit: "\u{00b5}s",
3891 accessor: |_| None,
3892 },
3893 MetricDef {
3894 name: SCHBENCH_REQUEST_MAX_US_WHOLE,
3895 polarity: crate::test_support::Polarity::LowerBetter,
3896 kind: MetricKind::PerRunDistribution,
3897 default_abs: 50.0,
3898 default_rel: 0.50,
3899 display_unit: "\u{00b5}s",
3900 accessor: |_| None,
3901 },
3902 MetricDef {
3903 name: SCHBENCH_RPS_P20_WHOLE,
3904 polarity: crate::test_support::Polarity::Informational,
3905 kind: MetricKind::PerRunDistribution,
3906 default_abs: 10.0,
3907 default_rel: 0.10,
3908 display_unit: "req/s",
3909 accessor: |_| None,
3910 },
3911 MetricDef {
3912 name: SCHBENCH_RPS_P50_WHOLE,
3913 polarity: crate::test_support::Polarity::Informational,
3914 kind: MetricKind::PerRunDistribution,
3915 default_abs: 10.0,
3916 default_rel: 0.10,
3917 display_unit: "req/s",
3918 accessor: |_| None,
3919 },
3920 MetricDef {
3921 name: SCHBENCH_RPS_P90_WHOLE,
3922 polarity: crate::test_support::Polarity::Informational,
3923 kind: MetricKind::PerRunDistribution,
3924 default_abs: 10.0,
3925 default_rel: 0.10,
3926 display_unit: "req/s",
3927 accessor: |_| None,
3928 },
3929 MetricDef {
3930 name: SCHBENCH_RPS_MIN_WHOLE,
3931 polarity: crate::test_support::Polarity::Informational,
3932 kind: MetricKind::PerRunDistribution,
3933 default_abs: 10.0,
3934 default_rel: 0.10,
3935 display_unit: "req/s",
3936 accessor: |_| None,
3937 },
3938 MetricDef {
3939 name: SCHBENCH_RPS_MAX_WHOLE,
3940 polarity: crate::test_support::Polarity::Informational,
3941 kind: MetricKind::PerRunDistribution,
3942 default_abs: 10.0,
3943 default_rel: 0.10,
3944 display_unit: "req/s",
3945 accessor: |_| None,
3946 },
3947 // -- Per-cgroup per-phase NON-schbench families. PerPhase, `accessor:
3948 // |_| None`: read from `PhaseCgroupStats::metrics` by name (written by
3949 // `write_carrier_scalars`), never from a `GauntletRow`. BARE per-cgroup
3950 // names (NOT the run-level `worst_*`): a single cgroup's value is not a
3951 // "worst across cgroups", and reusing `worst_*` would collide
3952 // `metric_def` with the run-level selector. Thresholds mirror the
3953 // analogous `worst_*` entries. (`iteration_rate` is intentionally absent —
3954 // it is already a Rate entry above; the per-cgroup value resolves through
3955 // that name without a second registration.)
3956 MetricDef {
3957 name: "p99_wake_latency_us",
3958 polarity: crate::test_support::Polarity::LowerBetter,
3959 kind: MetricKind::PerPhase,
3960 default_abs: 50.0,
3961 default_rel: 0.25,
3962 display_unit: "\u{00b5}s",
3963 accessor: |_| None,
3964 },
3965 MetricDef {
3966 name: "median_wake_latency_us",
3967 polarity: crate::test_support::Polarity::LowerBetter,
3968 kind: MetricKind::PerPhase,
3969 default_abs: 20.0,
3970 default_rel: 0.25,
3971 display_unit: "\u{00b5}s",
3972 accessor: |_| None,
3973 },
3974 MetricDef {
3975 name: "wake_latency_cv",
3976 polarity: crate::test_support::Polarity::LowerBetter,
3977 kind: MetricKind::PerPhase,
3978 default_abs: 0.10,
3979 default_rel: 0.25,
3980 display_unit: "",
3981 accessor: |_| None,
3982 },
3983 MetricDef {
3984 // Per-cgroup per-phase timer-latency (WorkType::TimerLatency). PerPhase,
3985 // accessor |_| None: read from PhaseCgroupStats::metrics by name
3986 // (written by write_carrier_scalars). Bare name (not worst_*) — a single
3987 // cgroup's value, not a worst-across-cgroups.
3988 name: "p99_timer_latency_us",
3989 polarity: crate::test_support::Polarity::LowerBetter,
3990 kind: MetricKind::PerPhase,
3991 default_abs: 50.0,
3992 default_rel: 0.25,
3993 display_unit: "\u{00b5}s",
3994 accessor: |_| None,
3995 },
3996 MetricDef {
3997 name: "median_timer_latency_us",
3998 polarity: crate::test_support::Polarity::LowerBetter,
3999 kind: MetricKind::PerPhase,
4000 default_abs: 20.0,
4001 default_rel: 0.25,
4002 display_unit: "\u{00b5}s",
4003 accessor: |_| None,
4004 },
4005 MetricDef {
4006 name: "p999_timer_latency_us",
4007 polarity: crate::test_support::Polarity::LowerBetter,
4008 kind: MetricKind::PerPhase,
4009 default_abs: 100.0,
4010 default_rel: 0.25,
4011 display_unit: "\u{00b5}s",
4012 accessor: |_| None,
4013 },
4014 MetricDef {
4015 name: "mean_run_delay_us",
4016 polarity: crate::test_support::Polarity::LowerBetter,
4017 kind: MetricKind::PerPhase,
4018 default_abs: 50.0,
4019 default_rel: 0.25,
4020 display_unit: "\u{00b5}s",
4021 accessor: |_| None,
4022 },
4023 MetricDef {
4024 name: "max_run_delay_us",
4025 polarity: crate::test_support::Polarity::LowerBetter,
4026 kind: MetricKind::PerPhase,
4027 default_abs: 100.0,
4028 default_rel: 0.50,
4029 display_unit: "\u{00b5}s",
4030 accessor: |_| None,
4031 },
4032 MetricDef {
4033 name: "avg_off_cpu_pct",
4034 polarity: crate::test_support::Polarity::LowerBetter,
4035 kind: MetricKind::PerPhase,
4036 default_abs: 5.0,
4037 default_rel: 0.25,
4038 display_unit: "%",
4039 accessor: |_| None,
4040 },
4041 MetricDef {
4042 name: "min_off_cpu_pct",
4043 polarity: crate::test_support::Polarity::LowerBetter,
4044 kind: MetricKind::PerPhase,
4045 default_abs: 5.0,
4046 default_rel: 0.25,
4047 display_unit: "%",
4048 accessor: |_| None,
4049 },
4050 MetricDef {
4051 name: "max_off_cpu_pct",
4052 polarity: crate::test_support::Polarity::LowerBetter,
4053 kind: MetricKind::PerPhase,
4054 default_abs: 5.0,
4055 default_rel: 0.25,
4056 display_unit: "%",
4057 accessor: |_| None,
4058 },
4059 MetricDef {
4060 name: "off_cpu_spread_pct",
4061 polarity: crate::test_support::Polarity::LowerBetter,
4062 kind: MetricKind::PerPhase,
4063 default_abs: 5.0,
4064 default_rel: 0.25,
4065 display_unit: "%",
4066 accessor: |_| None,
4067 },
4068 MetricDef {
4069 name: "migration_ratio",
4070 polarity: crate::test_support::Polarity::LowerBetter,
4071 kind: MetricKind::PerPhase,
4072 default_abs: 0.05,
4073 default_rel: 0.20,
4074 display_unit: "",
4075 accessor: |_| None,
4076 },
4077 MetricDef {
4078 name: "iterations_per_worker",
4079 polarity: crate::test_support::Polarity::Informational,
4080 kind: MetricKind::PerPhase,
4081 default_abs: 10.0,
4082 default_rel: 0.10,
4083 display_unit: "",
4084 accessor: |_| None,
4085 },
4086 MetricDef {
4087 name: "page_locality",
4088 polarity: crate::test_support::Polarity::HigherBetter,
4089 kind: MetricKind::PerPhase,
4090 default_abs: 0.05,
4091 default_rel: 0.10,
4092 display_unit: "",
4093 accessor: |_| None,
4094 },
4095 MetricDef {
4096 name: "cross_node_migration_ratio",
4097 polarity: crate::test_support::Polarity::LowerBetter,
4098 kind: MetricKind::PerPhase,
4099 default_abs: 0.05,
4100 default_rel: 0.20,
4101 display_unit: "",
4102 accessor: |_| None,
4103 },
4104 // Per-cgroup carrier counter (read via `cgroup_counter` /
4105 // `cgroup_counter_total`), Counter kind, `accessor: |_| None` (no
4106 // GauntletRow field). Raw delivered CPU is diagnostic; derived CPU-normalized
4107 // rates carry direction.
4108 MetricDef {
4109 name: "total_cpu_time_ns",
4110 polarity: crate::test_support::Polarity::Informational,
4111 kind: MetricKind::Counter,
4112 default_abs: 100.0,
4113 default_rel: 0.10,
4114 display_unit: "ns",
4115 accessor: |_| None,
4116 },
4117];
4118
4119/// Minimum total iterations a run must have accumulated before the
4120/// `worst_wake_latency_tail_ratio` metric participates in regression
4121/// math.
4122///
4123/// Below this threshold the p99 / median ratio is dominated by a
4124/// handful of outlier samples rather than a distributional signal:
4125/// p99 on an N-sample set where `N < 100` collapses to approximately
4126/// `samples.max()` (the empirical p99 sits at the Nth item of a
4127/// sorted set, rounded down, so with N=10 every "p99" is in fact the
4128/// maximum), and the ratio `max/median` swings by order of magnitude
4129/// across runs that differ only in which worker happened to hit a
4130/// scheduling stall. `compare_rows` would report those swings as
4131/// regressions / improvements, burying real signal under low-N noise.
4132///
4133/// 100 is the threshold of interest because percentile estimation
4134/// stabilizes when the sample count crosses `1 / (1 - target_p)` —
4135/// i.e. 100 samples for a p99 — which is the point at which at least
4136/// one sample is expected in the 99th-percentile tail by pigeonhole.
4137/// Below this floor the p99 estimator degenerates to the observed
4138/// maximum (`samples[99]` when N is exactly 100, and a still-sparse
4139/// tail at N just above 100). Above 100 the ratio begins to reflect
4140/// actual tail behavior rather than single-sample extrema.
4141///
4142/// The gate uses `total_iterations` (scenario-wide sum across every
4143/// cgroup in the run) as a coarse floor, not an exact per-cgroup
4144/// sample count. That sum OVERESTIMATES the per-cgroup iteration
4145/// count when the scenario has multiple cgroups sharing load, so a
4146/// scenario whose total just clears the floor may still have
4147/// individual cgroups with fewer than 100 iterations and therefore
4148/// noisy per-cgroup tail ratios. The floor is a minimum-viable
4149/// filter against the lowest-N degeneracy, not a guarantee that
4150/// every cgroup in a passing row has a stable p99.
4151///
4152/// The gate is applied at the PRODUCER, not an accessor:
4153/// `crate::assert::populate_run_distribution_metrics` emits no
4154/// `worst_wake_latency_tail_ratio` ext key for a run with
4155/// `total_iterations < WAKE_LATENCY_TAIL_RATIO_MIN_ITERATIONS`. The absent key
4156/// is excluded from the cross-RUN mean and read as `None` by `compare_rows`,
4157/// where the `(None, None)` arm skips the pair entirely (no verdict, no
4158/// coverage diff) when the key is absent on both sides.
4159pub const WAKE_LATENCY_TAIL_RATIO_MIN_ITERATIONS: u64 = 100;
4160
4161/// Look up a metric definition by name.
4162pub fn metric_def(name: &str) -> Option<&'static MetricDef> {
4163 METRICS.iter().find(|m| m.name == name)
4164}
4165
4166/// Rate-COMPONENT metric names suppressed from compare OUTPUT (scalar findings and the
4167/// noise per-phase spread + coverage rows). These are the internal
4168/// numerator/denominator Counters of derived rates. For `iteration_rate` these
4169/// are `total_iterations_pooled` / `total_cpu_time_sec`; emitting them alongside
4170/// the rate is redundant.
4171///
4172/// They are suppressed ONLY at the compare-render layer. They REMAIN in the
4173/// persisted sidecar, in `GauntletRow::ext_metrics`, and in
4174/// `PhaseBucket::metrics`, because the cross-RUN re-pool
4175/// ([`group_and_average_by`]) re-derives the rates as `Σnum / Σdenom` from these
4176/// components read out of the rows — stripping them from storage would break
4177/// rate aggregation. User-facing rates and the typed `total_iterations`
4178/// are NOT suppressed. (Their `default_abs`/`default_rel` thresholds are inert
4179/// while suppressed — the compare significance gate never reads them — but the
4180/// entries keep their registry slot: `name` is the re-pool component key and
4181/// `kind` drives the fold dispatch.)
4182const RENDER_SUPPRESSED_COMPONENTS: &[&str] = &[
4183 "total_iterations_pooled",
4184 "total_cpu_time_sec",
4185 "observed_task_cpu_time_ns",
4186 // taobench whole-run throughput / hit_fraction Rate components (the raw op counts +
4187 // wall window). Suppressed so compare shows the four `taobench_*` Rates, not
4188 // the redundant raw counts. Remain in the sidecar / row for the cross-RUN
4189 // Σnum/Σdenom re-pool, like the iterations components above.
4190 TOTAL_TAOBENCH_OPS,
4191 TOTAL_TAOBENCH_FAST_OPS,
4192 TOTAL_TAOBENCH_SLOW_OPS,
4193 TOTAL_TAOBENCH_WALL_SEC,
4194 TOTAL_TAOBENCH_CPU_SEC,
4195 // taobench command-time hit Rate components (get_cmds + get_hits): suppressed
4196 // so compare shows `taobench_command_hit_rate`, not the raw get counts; remain
4197 // in the row for the cross-RUN Σhits/Σcmds re-pool.
4198 TOTAL_TAOBENCH_GET_CMDS,
4199 TOTAL_TAOBENCH_GET_HITS,
4200 // schbench role-separate run-delay gate-Rate components (raw run_delay_ns +
4201 // pcount per role). Suppressed so compare shows the two
4202 // `schbench_*_run_delay_ns_per_sched` Rates, not the raw Σ pairs. Remain in
4203 // the row for the cross-RUN Σ/Σ re-pool. (total_schbench_loops is NOT here —
4204 // it is a standalone throughput Counter, not a rate component.)
4205 TOTAL_SCHBENCH_MSG_RUN_DELAY_NS,
4206 TOTAL_SCHBENCH_MSG_PCOUNT,
4207 TOTAL_SCHBENCH_WORKER_RUN_DELAY_NS,
4208 TOTAL_SCHBENCH_WORKER_PCOUNT,
4209 // CPU-second throughput denominator (schbench_total_loops_per_cpu_sec's
4210 // component); suppressed like the wall/cpu windows above.
4211 TOTAL_SCHBENCH_WORKER_CPU_SEC,
4212];
4213
4214/// True when `name` is a Rate component suppressed from compare output (see
4215/// the private `RENDER_SUPPRESSED_COMPONENTS` list).
4216pub fn is_render_suppressed_component(name: &str) -> bool {
4217 RENDER_SUPPRESSED_COMPONENTS.contains(&name)
4218}
4219
4220/// Infer the regression polarity (`higher_is_worse`) of a metric
4221/// not present in [`METRICS`].
4222///
4223/// Used by [`crate::assert::AssertResult::merge`] when it folds an
4224/// `ext_metrics` value whose name is not registered. Returning the
4225/// wrong polarity here surfaces as a silent merge bug: a
4226/// throughput-shaped metric (`*_iops`, `*_throughput`) folded with
4227/// `max` keeps the BETTER value across cgroups instead of the
4228/// worst, masking the cgroup that fell behind. The previous
4229/// fallback (`unwrap_or(true)` — always max) had this exact bug
4230/// for any payload-author metric whose name was not pre-registered
4231/// in the static `METRICS` table.
4232///
4233/// The inference is name-substring based, in the style of the
4234/// `Polarity::Unknown` fallback used by `MetricHint`. The token
4235/// list mirrors the polarity choices in [`METRICS`] for the
4236/// metrics already registered there:
4237///
4238/// - Tokens that signal HigherBetter (returned `false`):
4239/// `iops`, `throughput`, `bandwidth`, `iterations`, `ops_per_sec`,
4240/// `locality`, `_score`, `goodput`. The scheduler-test fixture's
4241/// `total_iterations` and `worst_iterations_per_worker` already
4242/// carry this polarity in the registry; a payload-author metric
4243/// like `jobs.0.read.iops` from the schbench JSON path
4244/// should fold the same way.
4245/// - Tokens that signal LowerBetter (returned `true`):
4246/// `latency`, `delay`, `_gap`, `stall`, `stuck`, `_cv`, `error`,
4247/// `fail`, `drop`, `spread`, `_us`, `_ms`, `_ns`, `migration_ratio`,
4248/// `imbalance`, `_depth`, `dsq`. These are the polarity signals from the existing
4249/// registered LowerBetter entries (`worst_p99_wake_latency_us`,
4250/// `worst_run_delay_us`, `worst_gap_ms`, `stuck_count`,
4251/// `worst_wake_latency_cv`, `worst_spread`, `worst_migration_ratio`,
4252/// `max_imbalance_ratio`). `stall` covers payload-author metrics
4253/// that surface the sched_ext watchdog stall (`SCX_EXIT_ERROR_STALL`)
4254/// while `stuck` covers `stuck_count` (CPU's `rq_clock` not
4255/// advancing) — distinct conditions but both higher-is-worse.
4256///
4257/// When a name matches no token (e.g. `bogo_ops`, `read_kb`,
4258/// `jobs.0.runtime`), returns `true` (LowerBetter). The fallback
4259/// is conservative for regression detection: a payload that emits
4260/// a not-yet-classifiable metric and then folds an unexpectedly
4261/// high value across cgroups is more useful surfaced than silently
4262/// kept at the minimum (which would mask the high reading
4263/// entirely). Authors who need a different default should register
4264/// a [`MetricDef`] in [`METRICS`] or tag the metric via
4265/// [`crate::test_support::MetricHint`].
4266///
4267/// Token order matters when names contain both signals (e.g. the
4268/// hypothetical `low_iops_latency_ms` would match `latency` first
4269/// and be classified as higher-is-worse). The token lists above
4270/// are tested by `infer_higher_is_worse_*` in this module's tests.
4271pub fn infer_higher_is_worse(name: &str) -> bool {
4272 // First-pass: explicit "higher value is the regression" signals
4273 // (latency, delay, error, etc.). Checked first so a name
4274 // carrying both kinds of token (rare; e.g. `*_iops_latency_us`)
4275 // resolves to the latency interpretation, which matches the
4276 // semantics of compound counters/timers.
4277 const HIGHER_IS_WORSE_TOKENS: &[&str] = &[
4278 "latency",
4279 "delay",
4280 "_gap",
4281 "stall",
4282 "stuck",
4283 "_cv",
4284 "error",
4285 "fail",
4286 "drop",
4287 "spread",
4288 "_us",
4289 "_ms",
4290 "_ns",
4291 "migration_ratio",
4292 "imbalance",
4293 // DSQ depth is "lower is better" — a shallower queue
4294 // means the scheduler is keeping up. `_depth` and `dsq`
4295 // are independently meaningful: `_depth` catches names
4296 // like `max_dsq_depth` / `avg_dsq_depth` whose source is
4297 // the scheduler's local dispatch queue; `dsq` is the
4298 // defensive fallback for future DSQ-related metric names
4299 // that don't carry `_depth` (e.g. `dsq_overflow_count`).
4300 // Without these tokens, a future refactor that drops a
4301 // DSQ metric from the METRICS registry would fall through
4302 // to the conservative `true` default — correct by luck
4303 // for DSQ depth (higher = worse) but not by reasoning;
4304 // these tokens make the inference grounded.
4305 //
4306 // False-positive caveat: a future metric named
4307 // `dsq_throughput` / `dsq_iops` / `cache_depth` /
4308 // `tree_depth` would be classified higher-is-worse
4309 // here when the truth is the opposite. The fallback
4310 // path matters only when METRICS doesn't register the
4311 // name explicitly — register every new dsq-or-depth
4312 // metric so the token-based inference never runs.
4313 "_depth",
4314 "dsq",
4315 ];
4316 if HIGHER_IS_WORSE_TOKENS.iter().any(|t| name.contains(t)) {
4317 return true;
4318 }
4319 // Second-pass: "higher value is the improvement" signals
4320 // (throughput, iops, etc.). Matching here returns `false`
4321 // (LowerBetter inverted into HigherBetter, i.e. min is the
4322 // worst-case fold).
4323 const HIGHER_IS_BETTER_TOKENS: &[&str] = &[
4324 "iops",
4325 "throughput",
4326 "bandwidth",
4327 "iterations",
4328 "ops_per_sec",
4329 "locality",
4330 "_score",
4331 "goodput",
4332 ];
4333 if HIGHER_IS_BETTER_TOKENS.iter().any(|t| name.contains(t)) {
4334 return false;
4335 }
4336 // Conservative fallback: treat as higher-is-worse so a folded
4337 // value is the maximum across cgroups. Surfacing a maximum is
4338 // safer than masking it; payload authors who disagree should
4339 // register the metric.
4340 true
4341}
4342
4343/// Render the [`METRICS`] registry for `cargo ktstr stats list-metrics`.
4344///
4345/// `json=false` renders a comfy-table with one row per registered
4346/// metric and columns NAME / POLARITY / DEFAULT_ABS / DEFAULT_REL
4347/// / UNIT. `json=true` emits `serde_json::to_string_pretty`
4348/// on the whole [`METRICS`] slice — the `accessor` fn-pointer is
4349/// `#[serde(skip)]` so the array carries only wire-stable fields.
4350///
4351/// Iteration order equals [`METRICS`] declaration order (the
4352/// canonical surface order for sidecar / CI-gate consumers).
4353///
4354/// The return is owned `String` rather than a print-direct helper so
4355/// callers can pin output via `assert_eq!` in tests; the cargo-ktstr
4356/// dispatch arm at `run_stats` writes it to stdout verbatim.
4357pub fn list_metrics(json: bool) -> anyhow::Result<String> {
4358 if json {
4359 return serde_json::to_string_pretty(METRICS)
4360 .map_err(|e| anyhow::anyhow!("serialize METRICS to JSON: {e}"));
4361 }
4362
4363 let mut table = crate::cli::new_table();
4364 table.set_header(vec![
4365 "NAME",
4366 "POLARITY",
4367 "DEFAULT_ABS",
4368 "DEFAULT_REL",
4369 "UNIT",
4370 ]);
4371 for m in METRICS {
4372 table.add_row(vec![
4373 m.name.to_string(),
4374 polarity_label(m.polarity),
4375 format!("{}", m.default_abs),
4376 format!("{}", m.default_rel),
4377 m.display_unit.to_string(),
4378 ]);
4379 }
4380 Ok(format!("{table}\n"))
4381}
4382
4383/// Short human label for a [`Polarity`](crate::test_support::Polarity)
4384/// variant in the list-metrics table.
4385///
4386/// `HigherBetter` → `higher`, `LowerBetter` → `lower`,
4387/// `TargetValue(t)` → `target(t)`, `Unknown` → `unknown`. Match is
4388/// total; adding a new `Polarity` variant without extending this
4389/// rendering surfaces as a compile error.
4390fn polarity_label(p: crate::test_support::Polarity) -> String {
4391 use crate::test_support::Polarity;
4392 match p {
4393 Polarity::HigherBetter => "higher".to_string(),
4394 Polarity::LowerBetter => "lower".to_string(),
4395 Polarity::TargetValue(t) => format!("target({t})"),
4396 Polarity::Unknown => "unknown".to_string(),
4397 Polarity::Informational => "informational".to_string(),
4398 }
4399}