Crate rootle_trace 

rootle’s opt-in diagnostic session sink: one private, bounded JSONL file per session, written by a dedicated thread.

Producers never perform file I/O, never wait for the writer, and never wait for queue capacity — a full queue, an oversize record, a cap or a writer failure is an explicit capture failure surfaced through take_failure and TraceSession::finish, never a silent drop. Only the writer thread touches the file, flushing every batch it receives, and every file it closes ends with a terminal trace_end marker stating whether the capture is complete and why. A capped, failed, panicked or abandoned capture can never look complete, and a crash that prevents the marker leaves its absence as the verdict.

Envelopes carry schema_version, the writer-owned seq, elapsed_us, a thread label, the thread’s optional operation_id correlation, the event kind and producer fields; sequence and timestamps agree with admission order under concurrent producers.

Metadata capture is diagnostic, not anonymous: paths, repository identities, revisions and timing can still be sensitive — inspect files before sharing. Nothing here ever prints to stdout/stderr; the only outputs are the file and explicit Results.

Structs

Limits

Bounded capture: total bytes, total events, per-record bytes.

OperationId

Correlation identity linking a job’s lifecycle records across threads. Serializes as its bare number inside envelopes and producer payloads.

TraceOptions

Startup controls for crate::start.

TraceSession

The owning lifetime of a trace. TraceSession::finish is the explicit reporting boundary; Drop still finalizes the file durably, but as an abandoned capture, never a complete one.

Enums

ContentPolicy

What producer payloads may carry.

EventKind

The closed event vocabulary. Payloads are producer-defined fields; the kind only fixes the category so files stay joinable across crates.

TraceError

Constants

MAX_CAPTURE_BYTES

Hard upper bounds a capture may use. They exist so a runaway producer cannot fill the disk; start refuses anything outside them.

MAX_CAPTURE_EVENTS

MAX_RECORD_BYTES

SCHEMA_VERSION

Envelope schema version for every rootle session trace.

TERMINAL_RESERVE

The writer always reserves this much of the byte budget for the terminal marker, so a capture that hits its cap still ends legibly.

Functions

capture_content

Whether ContentPolicy::Full was selected: producers gate sensitive input/UI text and provider stderr on this.

enabled

in_operation

Run work with id as this thread’s correlation identity, restoring whatever was installed before — including on panic unwind, so a panicking worker cannot leak its identity into unrelated records.

mark_incomplete

A producer could not observe an explicitly requested surface. Preserve the failure verdict and stop admission rather than writing a complete-looking log.

operation_id

Allocate a fresh correlation identity, but only while a trace is enabled. Returns None (and allocates nothing) for disabled capture; pass the Option straight through to in_operation.

panic_record

Best-effort panic capture, safe to call from a panic hook.

record

record_with

Lazy producer: no payload construction or allocation when disabled.

start

Start the process’s single trace session, creating path exclusively.

take_failure

Report a capture failure once (for a status line); TraceSession::finish still returns it as an error.