Crate faultbox 

faultbox — a production black-box recorder.

One report format for every failure class — Rust panics, native crashes, detected data corruption, and invariant violations — each carrying a flight-recorder breadcrumb trail of the operations that led up to it, a build-id for offline symbolication (no debug symbols shipped to users), and, for corruption, a preserved snapshot of the bad artifact. The goal: debug a production failure from its report, without reproduction.

Corruption and invariant violations are usually returned errors, not crashes, so a panic-only crash reporter never sees them — capturing those, with rich per-project DomainContext, is the reason this crate exists.

Shape

• init once at startup: names the project, sizes the flight recorder, installs the panic hook, and sets the redactor + reports directory.
• Sprinkle breadcrumb! at significant operations (commits, allocs, frees, reopens). It is a no-op until init runs, so libraries may emit crumbs unconditionally.
• At a detection site, Capture a report with a DomainContext and, optionally, Capture::preserve the offending artifact.

The crate is synchronous and std-only so it is safe to call from a panic hook and usable by any project regardless of async runtime.

Re-exports

pub use context::Adhoc;

pub use context::DomainContext;

pub use redact::BasicRedactor;

pub use redact::NoopRedactor;

pub use redact::Redactor;

pub use report::Artifact;

pub use report::Env;

pub use report::EventKind;

pub use report::Frame;

pub use report::Meta;

pub use report::Report;

pub use report::SCHEMA_VERSION;

pub use tracing_layer::BreadcrumbLayer;

pub use writer::Retention;

pub use serde_json;

Modules

breadcrumbs

The flight recorder: a bounded, always-on, in-memory ring of recent significant events, dumped into every report.

build_id

Read the running binary’s GNU build-id — the key that lets a report be symbolicated server-side against the release’s stored debug info, without ever shipping debug symbols to users.

context

Extension points every adopting project implements.

digest

SHA-256, for the digests that travel on a report.

native

Out-of-process native-crash capture (SIGSEGV, SIGABRT, SIGBUS, SIGILL, SIGFPE, and stack overflow) as a minidump.

panic

Panic → report bridge.

reader

Reading back what the recorder wrote.

redact

Removing user data from every string that enters a report.

report

The portable report schema.

secure_fs

Creating report files and directories that only their owner can read, and refusing artifact names that could escape the report directory.

shared_ring

A breadcrumb ring in shared memory, keyed to the artifact instead of the process.

tracing_layer

Feed the flight recorder from tracing events.

writer

Persisting reports to disk and preserving the artifacts that travel with them.

Macros

breadcrumb

Emit a breadcrumb ergonomically.

Structs

Capture

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

Config

Process-wide configuration, set once via init.

Functions

config

The active config, if init has run.

error_chain_of

Walk an std::error::Error’s source chain into Display strings, outer-to-inner — a convenience for Capture::error_chain.

init

Initialize the recorder for this process. Idempotent: the first call wins; later calls are ignored (returns false).

now_ms

Unix-epoch milliseconds now. Infallible: falls back to 0 if the clock is before the epoch (never in practice).

run_crash_monitor_if_env

Divert to the native-crash monitor loop when this process was spawned as one (the native-crash feature’s monitor). Returns false in a normal process; in the monitor it runs to completion and exits without returning.