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}