Skip to content
Opswald Docs

Replay Sessions

You’ll learn how to use session replay to step through an agent run one span at a time, seeing exactly what happened at each step.

What is Session Replay?

Session Replay lets you walk through a completed trace span by span, like stepping through code in a debugger. For each step, you see:

  • The span’s input — what data went in
  • The span’s output — what came out
  • Token counts and duration
  • The full context of parent and sibling spans

How to Replay a Session

  1. Open a trace in the dashboard
  2. Click Replay in the trace header
  3. Use the controls to step through:
    • Next — Move to the next span
    • Previous — Go back one span
    • Play — Auto advance through spans with a configurable delay
    • Jump to — Click any span in the timeline to jump directly to it

What You See at Each Step

Input Panel

The data that was available when this span started. For LLM calls, this includes the full prompt or message array. For tool calls, this shows the function arguments.

Output Panel

What the span produced. For LLM calls, the model response. For tool calls, the return value. For errors, the exception details.

Timeline

A horizontal bar showing where you are in the trace. Spans are color coded by kind and sized by duration. The current span is highlighted.

Context Sidebar

Shows the parent span, sibling spans, and any metadata attached to the trace. This helps you understand not just what happened at this step, but why it happened.

Debugging with Replay

Find the Breaking Point

When a trace ends in an error:

  1. Start replay from the beginning
  2. Step forward until you see the first unexpected output
  3. Examine the input — was the data correct?
  4. Check the parent span — did it provide bad context?

Understand Slow Traces

  1. Look at the timeline for the longest spans
  2. Jump to them directly
  3. Check if the delay was in the LLM response, tool execution, or your code

Compare Good vs Bad

Open two traces side by side — one that worked and one that didn’t. Step through them in parallel to find where they diverge.

Next Steps