Module dump 

Available on crate features dial9 and pipeline only.

On-demand pipeline runs: trigger, request channel, and dump receipts. On-trigger pipeline runs.

By default the background worker processes sealed trace segments continuously. Wiring a trigger flips the same pipeline into on-demand operation: segments keep accumulating in the ring (memory or disk), and the pipeline only runs when the application explicitly requests a dump.

A runtime wires a trigger at build time and reaches it through the ambient handle. See with_dump_trigger on the runtime builder for a worked example.

DumpTrigger::dump_current_data and DumpTrigger::dump_time_range build a DumpRun; the request is dispatched when that run is awaited or dropped, whichever comes first (so .with_metadata(...) can mutate it before it is sent). In the common temporary-statement form (trigger.dump_current_data();) the run drops at the end of the statement and dispatches right there; if you bind it to a variable, dispatch waits until that binding is awaited or goes out of scope. Awaiting is optional and only retrieves the DumpReceipt. Dumps are strictly best-effort: a window wider than what the ring retained captures whatever survived, with no error and no effect on the live stream.

Concurrent dumps

Dumps are independent: triggering two at once registers two dumps, each with its own DumpId and (off S3) its own manifest. A segment whose span overlaps both windows is captured by both. There is no coordination by default - this is intentional, so unrelated subsystems can dump without stepping on each other.

When a single source fires repeatedly (a watcher that re-trips every poll, a hot path that dumps on every slow request), configure DumpTriggerConfig::debounce to coalesce a burst into one dump: triggers within the debounce window after a dump dispatched resolve DumpError::Coalesced, naming the dump they folded into instead of starting a new one. The gate lives on the trigger stored on the recorder, so every dump_trigger clone shares it. (A cooldown that rejects extra triggers outright, rather than folding them, is a possible future addition.)

Structs

DumpCompletion

Worker → pipeline-stage signal that a dump finished; passed to SegmentProcessor::finalize_dump so stages can flush per-dump state (the S3 stage writes the dump’s manifest from it).

DumpFuture

Future resolving to the dump’s DumpReceipt.

DumpId

Identifier minted for each dump request.

DumpReceipt

What a completed dump produced.

DumpRun

In-flight dump request.

DumpRx

Receiving half of the trigger channel; the builder wires it into the worker.

DumpTrigger

Sending half of the trigger channel.

DumpTriggerConfig

On-demand dump configuration, passed to with_dump_trigger.

Enums

DumpError

Why a dump failed.

Functions

channel

Mint a dump trigger + receiver pair. The builder wires the receiver into the worker and stashes the trigger in the recorder so it can be reached via Dial9Handle::dump_trigger.