Struct TraceOptions 

pub struct TraceOptions {
    pub snapshots: bool,
    pub mapping_contexts: bool,
    pub changes: bool,
    pub max_snapshot_bytes: usize,
    pub redact_paths: Vec<String>,
    pub snapshot_audit_trail: AuditTrailScope,
}

What a trace-mode run records for each executed step.

TraceOptions::default reproduces the historical capture behaviour: a full Message snapshot and per-mapping contexts on every executed step, no budget, no redaction, and the whole accumulated audit trail.

Trace mode reads the clock twice per executed task to populate ExecutionStep::duration_us. The non-trace path (crate::Engine::process_message) is unaffected and still takes a single Utc::now() per message.

Fields

snapshots: bool

Full Message snapshot per executed step. true (default) is the historical behaviour and is what the dataflow-ui step debugger requires. With false, ExecutionTrace::final_message returns None and ExecutionTrace::is_success degenerates to true — inspect Message::errors on the message you passed in instead.

mapping_contexts: bool

Per-mapping context snapshots for map tasks. true (default). These are whole-context clones, one per mapping, so a multi-mapping map task can snapshot more than the step’s own Message does.

changes: bool

Per-step diff: the changes produced by this task and nothing else. false (default) preserves the historical payload byte for byte.

Prefer this over reading audit_trail.last(), which mis-attributes on a TaskOutcome::Skip step — no audit entry is recorded for a skip, so the last entry belongs to a different task.

Empty when the message was built with MessageBuilder::capture_changes(false): this flag reports the diff, it does not turn capture on.

max_snapshot_bytes: usize

Soft budget over the approximate accumulated in-memory size of the snapshots taken so far — container and scalar nodes counted as one machine word, String contents by str::len(). This is not serialized JSON length; measuring that would mean serializing every step, which defeats the purpose of a pre-capture budget.

Once exceeded, later executed steps are still recorded — ids, result, timing, and changes if enabled — with message: None, and ExecutionTrace::truncated returns true. 0 (default) is unbounded.

redact_paths: Vec<String>

Dot-paths under the message context whose subtrees are replaced with OwnedDataValue::Null as the snapshot is built, via a pruning clone: the redacted subtree is never cloned, so this bounds the snapshot’s memory as well as its content. The live message is untouched, so later tasks still read the real values.

Also applied to mapping_contexts, which are whole-context clones and would otherwise carry the redacted subtree through unchanged.

Path syntax is the crate::engine::utils::get_nested_value vocabulary: dot segments, numeric segments index arrays, one leading # escapes a numerically-named object key. Unlike set_nested_value, a path that does not resolve creates nothing and is a no-op, and an empty path is ignored.

This is a literal path list and nothing more — no value scanning, no pattern matching, no credential heuristics. It is not a masking engine.

snapshot_audit_trail: AuditTrailScope

How much of the accumulated audit trail each snapshot carries. See AuditTrailScope; this is the lever for trace size in task count.

Implementations

impl TraceOptions

pub fn timings_only() -> Self

Ids, result, timing and the per-task diff; no message snapshots and no mapping contexts. A step costs a few hundred bytes plus its diff, regardless of message size or task count.

Note this is UI-incompatible: the dataflow-ui step debugger needs snapshots to render the step view.

Trait Implementations

impl Clone for TraceOptions

fn clone(&self) -> TraceOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TraceOptions

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

Formats the value using the given formatter.

impl Default for TraceOptions

fn default() -> Self

Returns the “default value” for a type.