Struct Capture 

pub struct Capture { /* private fields */ }

Builder for a single report. Construct at a failure site, attach context, then emit.

Implementations

impl Capture

pub fn new(kind: EventKind, message: impl Into<String>) -> Self

Begin a capture of kind with a one-line message.

pub fn error_chain<I, S>(self, chain: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Record the outer-to-inner Display chain of an error (e.g. by walking std::error::Error::source).

pub fn domain(self, ctx: &dyn DomainContext) -> Self

Attach project-specific forensic context and adopt its grouping key.

Panics

Never — including when the DomainContext implementation itself panics. Serializing forensic context is exactly the code most likely to misbehave while a system is already failing: it reaches into the very structures whose corruption is being reported, and an index or unwrap that holds in a healthy process need not hold in this one. Losing the context is a worse report; taking the process down at the detection site is a worse outcome.

A panicking implementation therefore leaves the payload empty and the capture usable, so the report still records that the site fired.

pub fn with_backtrace(self) -> Self

Capture a backtrace at this point.

pub fn backtrace_frames(self, frames: Vec<Frame>) -> Self

Attach pre-built backtrace frames (used by the panic hook).

pub fn preserve( self, artifact_kind: impl Into<String>, src: impl Into<PathBuf>, name: impl Into<String>, note: Option<String>, ) -> Self

Preserve a file or directory alongside the report (copied in on emit) — e.g. a snapshot of a corrupt store for offline fsck.

pub fn emit(self) -> Option<PathBuf>

Build, persist, and return the report directory. Returns None if the recorder was never initialized or the write failed — never panics, so it is safe inside a panic hook.

Reports coalesce by fingerprint: repeated captures of one bug land in the same directory, bumping Report::occurrences and refreshing latest.json, rather than writing a directory per occurrence.

Panics

Never. That is a guarantee, not an aspiration: this runs at a detection site in a process that is already in trouble, and often from inside the panic hook, where a second panic is an abort that destroys the report.

Making it true takes more than avoiding unwrap in this crate, because the capture path calls adopter code — Redactor::redact on every string, and Redactor::redact_json over the domain payload. A panicking redactor would otherwise take the application down from a logging-shaped call, so the whole capture is unwind-guarded and a panic simply yields None.

Note the direction of that failure: a panic part-way through redaction abandons the report entirely rather than writing what had been redacted so far. A missing report costs a debugging session; a half-redacted one costs the secret.

Nothing can be done about a build using panic = "abort", where no unwind is catchable — there, an adopter’s redactor must not panic.