Struct CtprofProbeSummary 

#[non_exhaustive]
pub struct CtprofProbeSummary {
    pub tgids_walked: u64,
    pub jemalloc_detected: u64,
    pub probed_ok: u64,
    pub failed: u64,
    pub dominant_failure: Option<String>,
    pub privilege_dominant: bool,
}

Per-snapshot probe outcome statistics. Curated projection of the capture pipeline’s internal probe tally — exposes the counters, the dominant failure tag, and a privilege_dominant boolean a downstream consumer needs to decide whether the snapshot’s allocated_bytes / deallocated_bytes fields are trustworthy on a given host without parsing the operator- facing tracing line.

The internal probe taxonomy (the per-variant host_thread_probe::AttachError and ProbeError enums) is deliberately NOT mirrored here — it is implementation detail that may change shape without breaking this contract. dominant_failure carries the operator-facing tag string (e.g. "ptrace-seize", "dwarf-parse-failure") that the capture pipeline already surfaces in its tracing summary; the stable token format is documented in the ktstr ctprof capture CLI help. privilege_dominant mirrors the same gate that prints the EPERM remediation hint — true when ≥ 50% of failed is ptrace-seize or ptrace-interrupt.

The four counters are zero when the probe pass reached zero tgids (e.g. an empty proc_root); dominant_failure is None when no actionable failures landed; privilege_dominant is false when there are no failures or when ptrace failures are strictly less than half of failed (the >= 50% gate accepts equality at the boundary).

Examples

let snap = ktstr::ctprof::capture();
if let Some(ps) = &snap.probe_summary {
    if let Some(hint) = ps.remediation_hint() {
        eprintln!("{hint}");
    }
    if let Some(tag) = &ps.dominant_failure {
        eprintln!("dominant failure: {tag}");
    }
}

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.

tgids_walked: u64

Total tgids the probe pass walked. Equals the number of /proc/<pid> directories the capture saw, minus the calling process’s own tgid (which is skipped because PTRACE_SEIZE rejects self-attach).

jemalloc_detected: u64

Tgids whose attach_jemalloc_at call succeeded — i.e. the target was identified as jemalloc-linked, the TSD symbol resolved, and the per-tsd_s field offsets came out of the DWARF walk. A subset of tgids_walked.

probed_ok: u64

Per-thread probe reads that returned a counter pair. Bounded above by the sum of thread counts across all jemalloc_detected tgids; per-thread failures (target thread exited mid-attach, EPERM, etc.) reduce this count below the upper bound.

failed: u64

Attach-or-probe failures whose tag is classified ACTIONABLE — see the ktstr ctprof capture CLI help for the full filter rule and tag taxonomy. Routine non-actionable outcomes (target not jemalloc-linked, readlink race-with-exit) do NOT contribute to this count.

dominant_failure: Option<String>

Tag string for the most-frequent actionable failure across all attach-and-probe failures. None when failed == 0. Stable single-word identifiers — the wire contract that downstream consumers match against. The full taxonomy is documented in the ktstr ctprof capture CLI help. Examples: "ptrace-seize", "dwarf-parse-failure", "jemalloc-in-dso".

privilege_dominant: bool

true when the ptrace failure share crosses the hint-trigger threshold (≥ 50% of failed is ptrace-seize or ptrace-interrupt). Mirrors the same gate that prints the EPERM remediation hint in the operator-facing tracing summary, so a downstream consumer can reproduce that signal without parsing the log line. When true, rerunning the capture binary with CAP_SYS_PTRACE (e.g. sudo setcap cap_sys_ptrace+eip $(which ktstr), or run as root, or sysctl kernel.yama.ptrace_scope=0) resolves most attach failures so jemalloc TSD attach succeeds across foreign tgids. false when failed == 0 (no failures to dominate) or when ptrace failures are strictly less than half of failed (the >= 50% gate accepts equality at the boundary).

Independent of Self::dominant_failure: ptrace failures are tallied across both ptrace-seize and ptrace-interrupt for the threshold, while dominant_failure reports a single per-tag plurality. When ptrace counts split across the two tags, privilege_dominant may be true while dominant_failure names a non-ptrace tag that won the single-tag plurality. Conversely, dominant_failure may name a ptrace tag while privilege_dominant is false when ptrace failures are below the 50% threshold.

Implementations

impl CtprofProbeSummary

pub fn remediation_hint(&self) -> Option<&'static str>

Operator-facing remediation hint when ptrace failures dominate the snapshot. Returns Some(&'static str) — the same PTRACE_EPERM_HINT constant the capture pipeline embeds in its tracing summary line (a one-liner naming cap_sys_ptrace — the setcap-form spelling of the capability — and kernel.yama.ptrace_scope), or None when Self::privilege_dominant is false. Lets a downstream consumer surface the same fix-it message without parsing the log line or hand-rolling the gate.

Trait Implementations

impl Clone for CtprofProbeSummary

fn clone(&self) -> CtprofProbeSummary

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CtprofProbeSummary

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

Formats the value using the given formatter.

impl Default for CtprofProbeSummary

fn default() -> CtprofProbeSummary

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CtprofProbeSummary

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for CtprofProbeSummary

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

where __S: Serializer,

Serialize this value into the given Serde serializer.