Struct CtprofSnapshot 

#[non_exhaustive]
pub struct CtprofSnapshot {
    pub captured_at_unix_ns: u64,
    pub host: Option<HostContext>,
    pub threads: Vec<ThreadState>,
    pub cgroup_stats: BTreeMap<String, CgroupStats>,
    pub probe_summary: Option<CtprofProbeSummary>,
    pub parse_summary: Option<CtprofParseSummary>,
    pub taskstats_summary: Option<TaskstatsSummary>,
    pub psi: Psi,
    pub sched_ext: Option<SchedExtSysfs>,
}

Top-level serialized artifact produced by ktstr ctprof.

The file layout on disk is zstd-compressed JSON of this struct. Extension .ctprof.zst is conventional; nothing in the loader depends on the extension beyond being passed a path that resolves to a readable file.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

captured_at_unix_ns: u64

Wall-clock time at capture, nanoseconds since the Unix epoch. Useful as a tie-breaker when comparing two snapshots that originate from the same host — the newer one is candidate by default — but carries no load-bearing role in any grouping axis.

host: Option<HostContext>

Host context snapshot (kernel, CPU, memory, tunables). Optional because older tools or synthetic fixtures may omit it; comparison degrades to a “host context unavailable” line rather than failing the whole compare when either side is missing.

threads: Vec<ThreadState>

One entry per observed thread on the host at capture time. Order is not load-bearing; the comparison pipeline groups by pcomm / cgroup / comm depending on --group-by.

cgroup_stats: BTreeMap<String, CgroupStats>

Enrichment metadata for every cgroup that at least one sampled thread resides in. Keyed by the cgroup path relative to the v2 mount (e.g. /kubepods/burstable/pod-<id>/container). Populated from the cgroup filesystem, not the per-thread sample, because cpu.stat / memory.current describe the cgroup’s aggregate state, not per-thread contribution.

probe_summary: Option<CtprofProbeSummary>

Probe outcome statistics for the snapshot, when the probe pass ran. None indicates the snapshot was assembled without the per-tgid jemalloc probe walk (synthetic-tree tests pass use_syscall_affinity=false to skip it). Some(_) carries the per-snapshot tally — see CtprofProbeSummary for the curated field set.

parse_summary: Option<CtprofParseSummary>

Procfs-read failure statistics for the snapshot, when the capture pass ran in production mode. Mirrors the probe_summary discipline: None indicates synthetic-tree tests skipped it (use_syscall_affinity=false); Some(_) carries the per-snapshot read-level failure tally — see CtprofParseSummary.

taskstats_summary: Option<TaskstatsSummary>

Per-snapshot taskstats genetlink query outcome tally, populated when the capture pass ran in production mode. None mirrors probe_summary / parse_summary: synthetic-tree tests pass use_syscall_affinity=false which skips the netlink path entirely. Some(_) carries the per-snapshot ok/eperm/esrch/other counts so an operator can distinguish “no taskstats data because every tid raced exit” (high esrch_count) from “no taskstats data because the kernel was built without CONFIG_TASKSTATS” (the netlink open failed up-front so every counter is zero) from “no taskstats data because CAP_NET_ADMIN is missing” (high eperm_count). See crate::taskstats::TaskstatsSummary for the per-counter semantics and remediation guidance.

psi: Psi

Host-level Pressure Stall Information, populated from <proc_root>/pressure/{cpu,memory,io,irq}. Captures system-wide stall pressure across the four kernel-exposed resources. Defaults to all-zero when the kernel has CONFIG_PSI off or when individual resource files are absent. See Psi for the per-resource shape and the system-level cpu.full / irq.some caveats.

sched_ext: Option<SchedExtSysfs>

Global sched_ext sysfs state from /sys/kernel/sched_ext/. None when CONFIG_SCHED_CLASS_EXT is not built (no sched_ext sysfs directory exists), or when the directory itself is unreadable. See SchedExtSysfs for the per-field shape and kernel cites. Populated during the same capture pass as PSI.

Implementations

impl CtprofSnapshot

pub fn load(path: &Path) -> Result<Self>

Load a snapshot from a zstd-compressed JSON file.

Errors propagate via anyhow with the source path in the context chain so a malformed file surfaces an actionable message rather than a generic deserialize error. The loader does not validate that threads is non-empty — an empty snapshot is a legitimate edge case (host idle, capture filter excluded every thread) and the comparison engine handles it by emitting an empty diff.

The decompression step is bounded by MAX_DECOMPRESSED_SNAPSHOT_BYTES — a payload that decompresses past that ceiling surfaces an error rather than allocating unbounded memory, guarding against a hostile zstd payload (zstd compresses pathologically well on repeated bytes).

pub fn write(&self, path: &Path) -> Result<()>

Write a snapshot as zstd-compressed JSON.

Used by the capture layer; exposed from this module so that both compare-side tests and the capture binary share one on-disk shape. Compression level 3 mirrors the ktstr remote-cache convention — adequate ratio at fast speed — and is not tunable because ctprof captures are small enough that further compression produces diminishing returns on I/O.

Trait Implementations

impl Clone for CtprofSnapshot

fn clone(&self) -> CtprofSnapshot

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CtprofSnapshot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CtprofSnapshot

fn default() -> CtprofSnapshot

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CtprofSnapshot

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for CtprofSnapshot

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.