Traces

A trace records what a run did: one span per Predict call, carrying the rendered prompt, the parsed output, and a request fingerprint. Replay serves a later run back from that recording instead of a live provider. The dsrs CLI that checks, formats, and serves .dsrs artifacts has its own page: CLI.

Recording and replaying a run

Wrap any call in capture to get the run back as a value, then persist it as JSONL:

use dspy_rs::trace::capture;

let (result, trace) = capture(|| pipeline(input.clone())).await;
let result = result?;
std::fs::write("run.jsonl", trace.to_jsonl()?)?;

ReplayMode::Strict proves the pipeline still behaves exactly as recorded: every call is served from the log, with zero provider calls.

use dspy_rs::{ReplayMode, Trace, replay};

let trace = Trace::from_jsonl(&std::fs::read_to_string("run.jsonl")?)?;
let (replayed, report) = replay(&trace, ReplayMode::Strict, || {
    pipeline(input.clone())
})
.await;
let replayed = replayed?;
assert_eq!(report.live, 0, "strict replay never calls a provider");

ReplayMode::UntilDivergence replays the unchanged prefix free and goes live only from the first call your change actually touches:

let (out, report) = replay(&trace, ReplayMode::UntilDivergence, || {
    pipeline(input.clone())
})
.await;
println!("served {} free, {} live", report.served, report.live);

Each span’s fingerprint covers the full rendered prompt and the model settings; divergence is detected at the first call whose fingerprint differs from its recording, and only calls from there run live.

Capture

capture records every Predict call on the current task into a Trace while the scope is active.

let (result, trace) = dspy_rs::trace::capture(|| module.call(input)).await;

capture(f) runs the closure and returns its result plus the recorded Trace.
capture_with_meta(meta, f) is the same with caller-provided rollout metadata (TraceMeta: rollout input, candidate hash, free-form tags). A missing trace_id or start time is minted at scope start.

Scoping is task-local: spawned subtasks do not inherit the scope, and nested scopes are exclusive (the innermost records). With no scope active the cost is one task-local probe per call. Traces serialize to JSONL via Trace::to_jsonl and Trace::from_jsonl.

What a span records

One span is one Predict invocation. At a high level it records:

Who ran: the component name (the same name the params system uses, so spans join back to tunable slots) plus a per-component sequence number; (component, seq) is unique per trace and is what replay keys on.
What went in: the rendered prompt (an interned system-and-demos prefix plus the live suffix), the typed input fields as JSON, and the redacted model config.
What happened inside: ordered events, one Exchange per provider round-trip and one ToolRun per tool execution.
What came out: the raw assistant text, the parsed output fields, aggregated token usage, and any error (kinds: lm, parse, tool, cancelled).
What it was worth (optional): a span-level Eval, present only when a metric assigned per-span credit through TypedMetric::evaluate_spans (see Evaluation). Demo harvesting prefers it over the whole-rollout score; the field is omitted from the JSONL entirely when absent, so eval-free traces serialize exactly as before.
A request fingerprint: request_hash, a stable hash over the redacted model config plus the full rendered prompt. This is the replay key and the determinism check.
Timing and completeness: start time, duration, and a complete flag (false when the span was truncated or redacted; replay refuses incomplete spans).

Replay

replay serves Predict calls from a recorded trace instead of a live provider: each call’s request_hash is compared against the next recorded span for its component, and on a match the recorded output is served with zero API calls and no tool execution.

let (out, report) = dspy_rs::trace::replay(&trace, ReplayMode::Strict, || pipeline(input)).await;

Modes

`ReplayMode`	Plain words
`Strict`	Every call must match its recording; any mismatch is a typed error. For fixtures and CI (`report.live` stays 0).
`UntilDivergence`	Serve while hashes match; the first mismatching call and every call after it go to the live LM. For counterfactual replay: a mutated parameter changes only the prompts it affects, so the unchanged prefix replays free and only the changed suffix spends tokens. Once diverged, the session stays live even if a later hash happens to match again.

`ReplayReport` fields

Field	Meaning
`served`	Calls served from the recording (zero provider calls).
`live`	Calls that went to the live LM (always 0 in `Strict` mode).
`diverged_at`	The recorded span at which divergence was first detected, when the mismatch could be pinned to one.
`divergence`	The first mismatch, verbatim: the error `Strict` mode surfaced, or the reason `UntilDivergence` switched live.

Replay error kinds

`ReplayError`	Plain words
`Divergence`	The live request’s hash differs from the recorded span’s; the prompt or model config changed relative to the recording.
`Incomplete`	The recorded span is unusable: truncated or redacted, or it has no parsed output because the recorded call failed.
`Exhausted`	The trace has no recorded span for this component and sequence; the live run makes more calls than the recording.
`OutputDecode`	The recorded span matched but its stored output no longer deserializes into the signature’s output type (schema drift since recording).

Replay scoping mirrors capture: task-local, not inherited by spawned subtasks, innermost scope wins. Compose replay outside with capture inside to record a counterfactual rollout while serving its unchanged prefix from the base trace.

Traces serialize after a run finishes (Trace::to_jsonl). For live, human-readable console output while a program runs, call init_tracing (documented on Utils): it installs a process-global pretty tracing subscriber (respecting RUST_LOG, defaulting to dspy_rs=debug) and is independent of trace capture. There are no built-in exporters — the JSONL trace format is stable and self-describing, so external projections (observability, RL datasets) are serialization-side work on top of it.

Get Started

Building Blocks

Programs as Data

Tools & Agents

Evaluation & Optimization

Utilities

Recording and replaying a run

Capture

What a span records

Replay

Modes

`ReplayReport` fields

Replay error kinds

See also

​Recording and replaying a run

​Capture

​What a span records

​Replay

​Modes

​ReplayReport fields

​Replay error kinds

​See also

Recording and replaying a run

Capture

What a span records

Replay

Modes

`ReplayReport` fields

Replay error kinds

See also