Expand description
Re-exports for writing #[ktstr_test] functions.
use ktstr::prelude::*;
#[ktstr_test(llcs = 1, cores = 2, threads = 1)]
fn my_test(ctx: &Ctx) -> Result<AssertResult> {
Ok(AssertResult::pass())
}For curated canned scenarios, see scenario::scenarios.
Re-exports§
pub use crate::assert::AbsoluteThresholds;pub use crate::assert::Assert;pub use crate::assert::AssertDetail;pub use crate::assert::AssertResult;pub use crate::assert::COMPARATOR_VOCABULARY;pub use crate::assert::CgroupStats;pub use crate::assert::CgroupStatsClaim;pub use crate::assert::ClaimBuilder;pub use crate::assert::DetailKind;pub use crate::assert::EachClaim;pub use crate::assert::FracPair;pub use crate::assert::InfoNote;pub use crate::assert::MAX_RECORDED_PASSES;pub use crate::assert::NoteValue;pub use crate::assert::Outcome;pub use crate::assert::OutcomeRef;pub use crate::assert::PASSES_TRUNCATION_SENTINEL_COMPARATOR;pub use crate::assert::PASSES_TRUNCATION_SENTINEL_NAME;pub use crate::assert::PassDetail;pub use crate::assert::PhaseBucket;pub use crate::assert::PhaseBucketClaim;pub use crate::assert::PhaseCgroupStats;pub use crate::assert::PhaseCgroupStatsClaim;pub use crate::assert::PhaseMapExt;pub use crate::assert::ScenarioStats;pub use crate::assert::ScenarioStatsClaim;pub use crate::assert::SeqClaim;pub use crate::assert::SeriesField;pub use crate::assert::SetClaim;pub use crate::assert::Verdict;pub use crate::assert::assert_scx_events_clean;pub use crate::assert::assert_thresholds;pub use crate::assert::build_phase_buckets_with_stimulus;pub use crate::cgroup::CgroupManager;pub use crate::host_context::HostContext;pub use crate::host_heap::HostHeapState;pub use crate::scenario::backdrop::Backdrop;pub use crate::scenario::ops::CgroupDef;pub use crate::scenario::ops::CpusetSpec;pub use crate::scenario::ops::HoldSpec;pub use crate::scenario::ops::IrqSelector;pub use crate::scenario::ops::KernelTarget;pub use crate::scenario::ops::KernelValue;pub use crate::scenario::ops::KernelValueWidth;pub use crate::scenario::ops::Op;pub use crate::scenario::ops::Setup;pub use crate::scenario::ops::SpawnPlacement;pub use crate::scenario::ops::Step;pub use crate::scenario::ops::execute_defs;pub use crate::scenario::ops::execute_scenario;pub use crate::scenario::ops::execute_scenario_with;pub use crate::scenario::ops::execute_steps;pub use crate::scenario::ops::execute_steps_with;pub use crate::scenario::payload_run::PayloadHandle;pub use crate::scenario::payload_run::PayloadRun;pub use crate::scenario::scenarios;pub use crate::test_support::capture_starvation_witness;pub use crate::test_support::periodic_starvation_gate;pub use crate::test_support::post_vm_skip;pub use crate::test_support::stall_ejection_skip;pub use crate::test_support::starved_below_minimum_skip;pub use crate::timeline::StimulusEvent;pub use crate::scenario::sample::BpfMapCpuProjector;pub use crate::scenario::sample::BpfMapProjector;pub use crate::scenario::sample::Sample;pub use crate::scenario::sample::SampleSeries;pub use crate::scenario::sample::StatsPathProjector;pub use crate::scenario::sample::StatsValue;pub use crate::scenario::snapshot::BridgeGuard;pub use crate::scenario::snapshot::CaptureCallback;pub use crate::scenario::snapshot::CgroupProcsSnapshot;pub use crate::scenario::snapshot::JsonField;pub use crate::scenario::snapshot::MAX_WATCH_SNAPSHOTS;pub use crate::scenario::snapshot::Snapshot;pub use crate::scenario::snapshot::SnapshotBridge;pub use crate::scenario::snapshot::SnapshotEntry;pub use crate::scenario::snapshot::SnapshotError;pub use crate::scenario::snapshot::SnapshotField;pub use crate::scenario::snapshot::SnapshotMap;pub use crate::scenario::snapshot::SnapshotResult;pub use crate::scenario::snapshot::WatchRegisterCallback;pub use crate::scenario::snapshot::pickers;pub use crate::scenario::snapshot::stats_path;pub use crate::scenario::CgroupGroup;pub use crate::scenario::Ctx;pub use crate::scenario::collect_all;pub use crate::scenario::spawn_diverse;pub use crate::test_support::BpfMapAgg;pub use crate::test_support::BpfMapWrite;pub use crate::test_support::CgroupPath;pub use crate::test_support::EXIT_FAIL;pub use crate::test_support::EXIT_INCONCLUSIVE;pub use crate::test_support::EXIT_PASS;pub use crate::test_support::KTSTR_SCHEDULERS;pub use crate::test_support::KTSTR_TESTS;pub use crate::test_support::KtstrTestEntry;pub use crate::test_support::MemSideCache;pub use crate::test_support::Metric;pub use crate::test_support::MetricCheck;pub use crate::test_support::MetricHint;pub use crate::test_support::MetricStream;pub use crate::test_support::NumaDistance;pub use crate::test_support::NumaNode;pub use crate::test_support::OutputFormat;pub use crate::test_support::Payload;pub use crate::test_support::PayloadKind;pub use crate::test_support::PayloadMetrics;pub use crate::test_support::PerfDeltaAssertion;pub use crate::test_support::Polarity;pub use crate::test_support::Scheduler;pub use crate::test_support::SchedulerSpec;pub use crate::test_support::SidecarResult;pub use crate::test_support::Sysctl;pub use crate::test_support::Topology;pub use crate::test_support::TopologyConstraints;pub use crate::test_support::WatchBpfMap;pub use crate::test_support::extract_metrics;pub use crate::test_support::find_scheduler;pub use crate::test_support::find_test;pub use crate::test_support::sidecar_dir;pub use crate::topology::LlcInfo;pub use crate::topology::NodeMemInfo;pub use crate::topology::TestTopology;pub use crate::scenario::host_stuck::StuckDiagnostic;pub use crate::scenario::host_stuck::StuckReport;pub use crate::workload::AffinityIntent;pub use crate::workload::AluWidth;pub use crate::workload::CloneMode;pub use crate::workload::CustomCfg;pub use crate::workload::CustomFn;pub use crate::workload::FutexLockMode;pub use crate::workload::MemPolicy;pub use crate::workload::Migration;pub use crate::workload::MpolFlags;pub use crate::workload::ReapMode;pub use crate::workload::ResolvedAffinity;pub use crate::workload::SchbenchConfig;pub use crate::workload::SchedClass;pub use crate::workload::SchedPolicy;pub use crate::workload::TaobenchConfig;pub use crate::workload::TaobenchStats;pub use crate::workload::WakeMechanism;pub use crate::workload::WorkPhase;pub use crate::workload::WorkSpec;pub use crate::workload::WorkType;pub use crate::workload::WorkTypeValidationError;pub use crate::workload::WorkerCtx;pub use crate::workload::WorkerReport;pub use crate::workload::WorkerReportClaim;pub use crate::workload::WorkloadConfig;pub use crate::workload::WorkloadHandle;pub use crate::assert::Phase;
Macros§
- claim
- Open a
Verdictclaim from a local binding or expression. The label isstringify!(<expr-tokens>)so a regression that renames the binding or alters the expression updates the rendered failure message in lock-step. - claim_
present - Presence-checked sibling of
claim!for a possibly-absent metric. - declare_
scheduler - Function-style macro that registers a
Schedulerconst.
Structs§
- Arena
Page - One mapped arena page captured from guest memory.
- Arena
Snapshot - Snapshot of one arena map’s mapped pages.
- Body
Contention Window - Body-phase peak-window contamination series. New witnesses store deltas of
the ktstr runner cgroup’s CPU PSI
some totalclock: time during which at least one runnable task in that cgroup was stalled for CPU. This includes a delayed vCPU even when its competitor is outside the cgroup, without charging pressure in unrelated host cgroups. Each entry has its real observation width inSelf::tick_widths_ns, allowing the window calculation to remain sound when the monitor is starved and wakes much later than its nominal cadence. - Contention
Witness - The event-anchored host-contention witness: per-phase vCPU schedstat
dilation plus the Body-phase CPU-pressure interval series. The monitor
contributes constant-cost samples on its existing timer wakes; lifecycle
dispatch anchors the stage boundaries. Carried on
VmResult::contention_witnessso a later seam pass can calllatency_verdictto turn a latency threshold into a tri-state, contention-aware verdict. - Degraded
Failure Dump Report - Top-level degraded failure-dump report. Emitted by the freeze
coordinator when a real error-class trigger fires but the dump
path aborts before a full
FailureDumpReportcan be captured — today only the vCPU rendezvous-timeout path produces this shape. - Disk
Config - Per-disk config.
Defaultis raw 256 MiB device on/dev/vda; formatting and auto-mount are deferred. - Disk
Throttle - IO throttle for one disk. Each field caps a separate dimension;
Nonedisables that dimension’s throttle. AllNone= unthrottled (the device runs at host-pread/pwrite speed). - DsqState
- Snapshot of one DSQ’s state — built-in (per-CPU local, per-CPU bypass, per-node global) or user-allocated.
- Dual
Failure Dump Report - Pair of failure-dump snapshots captured at two points in a stall.
- Event
Counter Sample - One per-monitor-tick snapshot of the 13 SCX_EV_* event counters summed across every CPU at that tick.
- Failure
Dump Array Entry - One entry of a multi-entry
BPF_MAP_TYPE_ARRAYmap: the array key (u32) and its rendered value. MirrorsFailureDumpPercpuEntry’s typedu32key (ARRAY keys are kernel-imposed indices, not user-typed bytes) but carries a single value rather than a per-CPU vector. - Failure
Dump Entry - One (key, value) pair from a hash map. Both sides are rendered via
BTF when key/value type ids are available; a
Nonerendering preserves the raw bytes. - Failure
Dump FdArray - Per-FD-array snapshot of populated indices.
- Failure
Dump Map - Rendering of one BPF map’s contents.
- Failure
Dump Percpu Entry - One key from a per-CPU array, with one rendered value per CPU (None for CPUs whose per-CPU page was unmapped or out-of-range).
- Failure
Dump Percpu Hash Entry - One key from a
PERCPU_HASH/LRU_PERCPU_HASHmap, with one rendered value per CPU. MirrorsFailureDumpEntryfor the key side (rendered + hex) andFailureDumpPercpuEntryfor the per-CPU value vector. - Failure
Dump Report - Top-level failure-dump report. One per freeze trigger.
- Failure
Dump Ringbuf - Ringbuf occupancy snapshot read from
struct bpf_ringbufat the freeze instant. - Failure
Dump Stack Trace - Per-bucket summary of populated stack traces in a STACK_TRACE map.
- Failure
Dump Stack Trace Entry - One populated stack trace from a STACK_TRACE map.
- Host
Vcpu Schedstat - Host-side vCPU scheduling-dilation sample, summed over the run’s vCPU host threads.
- Kernel
OpReply Payload - Postcard-encoded payload for
MsgType::KernelOpReply. - NetConfig
- Configuration for the virtio-net device attached to the VM.
- PerCpu
Time Stats - Per-CPU CPU-time / softirq / IRQ snapshot captured at freeze time. One entry per CPU index visible to the host walker.
- PerNode
Numa Stats - Per-node NUMA event counters captured from
pglist_data->node_zones[]->vm_numa_event[]at freeze time. - PerPhase
Schedstat - Per-lifecycle-phase host-dilation witness: normally one
HostVcpuSchedstatDELTA per stage, covering the schedstat accrued between lifecycle-event boundary snapshots. If the guest-reported scenario duration proves queued lifecycle frames did not bracket Body, Body instead carries the complete enclosing vCPU-thread lifetime. That conservative fallback can overstate Body contention but cannot hide it. Indexed byLifecycleStageas usize. - Probe
BssCounters - Cross-CPU sum of every per-CPU diagnostic counter slot in the
probe BPF program’s
.bssktstr_pcpu_countersarray. - Prog
Runtime Stats - Per-program runtime stats summed across all CPUs.
- Rendered
Member - One member of a
RenderedValue::Struct.nameis the BTF name; for anonymous union members it is empty.valueis the recursive rendering of the member’s bytes. - RqScx
State - Snapshot of one CPU’s
struct rq.scxstate at freeze time. - ScxSched
State - Top-level scheduler state captured from
*scx_root. - Task
Enrichment - Per-task enrichment captured at freeze time.
- Virtio
BlkCounters Snapshot - Plain-u64 snapshot of
VirtioBlkCounterstaken at VM-result construction time. Mirrors every atomic field by name. - Virtio
NetCounters Snapshot - Plain-u64 snapshot of
VirtioNetCounterstaken at VM-result construction time. Mirrors every atomic field by name. - VmResult
- Result of a VM execution.
Enums§
- Builtin
Metric - One variant per
super::METRICSentry — the discoverable built-in metric vocabulary.Self::wire_nameis the stable registry / sidecar / CI string;Self::defresolves the fullMetricDef. Pinned 1:1 toMETRICS. - Disk
Throttle Validation Error - Validation failure for
DiskThrottle::validate. - Failure
Dump Report Any - Either-or wrapper that owns a parsed
FailureDumpReport,DualFailureDumpReport, orDegradedFailureDumpReport. Lets a consumer hold and render a failure-dump file without prematurely committing to one schema — the discriminant lives in the JSON’sschemafield, not in the type the consumer holds. - Filesystem
- Filesystem to format the backing file with.
- Guest
Lifecycle Phase - Final guest lifecycle stage as tracked by the progress ledger —
the public mirror of
monitor::LifecycleStage(same forward-only ordinal order, soOrdcompares boot progress). Snapshotted at run teardown ontoVmResult::final_guest_phase. - Kernel
OpValue - Wire-encoded
crate::scenario::ops::KernelValuevariant tag. Mirrors the fourKernelValueenum variants 1:1. - Metric
Id - A metric identifier accepted by every metric accessor via
impl Into<MetricId>: a typedBuiltinMetric(the common, discoverable, typo-proof case) or a dynamic scheduler-runtime / payload string (the open keyspace). One call shape for both —phase_metric(BuiltinMetric::X)andphase_metric("runtime_key"). - Rendered
Value - Structured rendering of one BTF-typed value.
- Throttle
Dimension - Throttle dimension a
DiskThrottleValidationErrorapplies to. - Watchdog
Kill Reason - Which watchdog rule (if any) killed the VM — the public mirror of
the watchdog-internal
freeze_coord::KillReasonTag, rendered ascause=in the deadline-expired stderr dump.NoneonVmResult::watchdog_kill_reasonmeans no watchdog kill was recorded (clean exit, crash, or a timeout path that never stamped a reason).
Constants§
- REASON_
DEGRADED_ RENDEZVOUS_ TIMEOUT - Reason string written into
DegradedFailureDumpReport::reasonwhen the freeze coordinator’s vCPU rendezvous timed out before every parked acknowledgement arrived. Wire-format-stable: matches the operator-grep contract used by every otherREASON_*constant in this module. The dynamic detail appended at emit time (<timeout_ms>/<parked>/<expected>) lets an operator see which vCPUs stalled without a separate field. - SCHEMA_
DEGRADED - Schema discriminant value emitted in
DegradedFailureDumpReport.schema. - SCHEMA_
DUAL - Schema discriminant value emitted in
DualFailureDumpReport.schema. SeeSCHEMA_SINGLEfor the discriminant contract. - SCHEMA_
SINGLE - Schema discriminant value emitted in
FailureDumpReport.schema. - SNAPSHOT_
TAG_ EARLY_ DEGRADED - Snapshot tag used when the early-snapshot trigger fires but
freeze_and_dispatch(FreezeMode::Capture { gate_on_exit_kind: false })returnsDegraded(early-half rendezvous timeout). The freeze coordinator writes the degraded JSON to a sibling path named viasuper::super::vmm::freeze_coord::snapshot_tagged_pathusing this tag — main{stem}.failure-dump.jsonis preserved for the subsequent late-trigger emission. Operator-readable wire-format constant: kebab-case, stable across releases. - SNAPSHOT_
TAG_ EARLY_ ONLY_ LATE_ NEVER_ FIRED - Snapshot tag used when dual-snapshot mode held a Captured early
snapshot AND the late-trigger path NEVER FIRED for the run (no
err_exit_detectedBPF latch flip; the scheduler never reached an error-class late event). Distinct fromSNAPSHOT_TAG_EARLY_ONLY_LATE_SUPPRESSED: this tag means the late trigger never ran at all, NOT that it ran and decided clean. Operator triage: scheduler crossed the half-watchdog runnable-age threshold (early-trigger fired) but then either recovered or terminated before reaching the late-trigger path —freeze_statestayed atIdleorTookEarlythrough coord exit. The end-of-coord drain emits the early observation to the tagged sibling rather than letting it drop with the closure. - SNAPSHOT_
TAG_ EARLY_ ONLY_ LATE_ SUPPRESSED - Snapshot tag used when dual-snapshot mode held a Captured early
snapshot AND the late-trigger path ran AND returned
Suppressed(the gate examined*scx_root->exit_kind, found it below SCX_EXIT_ERROR, and decided no failure dump warranted). Distinct fromSNAPSHOT_TAG_EARLY_ONLY_LATE_NEVER_FIRED: this tag means the late trigger DID fire and the gate explicitly decided clean exit. Operator triage: scheduler recovered from the early stall and reached a clean shutdown via the SCX_EXIT_NONE / SCX_EXIT_DONE path. The early observation (runnable-age spike) is independently meaningful and reaches disk at the tagged sibling. Symmetric withSNAPSHOT_TAG_EARLY_PRE_LATE_DEGRADED— tagged sibling rather than main path so the main{stem}.failure-dump.jsonkeeps the “scheduler had a failure-class exit” semantic. - SNAPSHOT_
TAG_ EARLY_ PRE_ LATE_ DEGRADED - Snapshot tag used when dual-snapshot mode held a Captured early
snapshot AND the late-trigger path returned
Degraded. The early snapshot is written to a sibling path with this tag while the late degraded JSON occupies the main dump path. Distinguishes “early itself degraded” (SNAPSHOT_TAG_EARLY_DEGRADED) from “early captured, late degraded” (this tag) so an operator browsing the dump directory knows which case produced which file. Every captured snapshot reaches disk.
Type Aliases§
- Result
Result<T, Error>
Attribute Macros§
- distributed_
slice linkme::distributed_slicere-exported as part of ktstr’s public surface. Combined withcrate::linkmefor the#[linkme(crate = ...)]annotation, this lets a downstream crate register entries intoKTSTR_TESTSorKTSTR_SCHEDULERSwithout addinglinkmeas a direct Cargo dependency:- ktstr_
test - Attribute macro that registers a function as a ktstr integration test.
- ktstr_
test_ entry - Register a manually constructed
KtstrTestEntry.
Derive Macros§
- Payload
- Derive macro that generates a
Payloadconst from an annotated struct for a userspace binary workload (stress-ng, fio, and similar tools test authors compose under a scheduler).