---
title: "Session Replay"
description: "Inspect session flow, open span payloads, compare runs, and replay tool calls against live MCP servers"
---

## Session detail page

Open the **Sessions** page and click any session row. LangSight opens a dedicated session detail page at `/sessions/<id>`.

The page has two tabs:

- **Details** — session timeline, lineage graph, and a right-side inspector for selected agents, servers, edges, and tool calls
- **Trace** — nested span tree reconstructed from `parent_span_id`

No separate tree is stored. LangSight rebuilds the hierarchy at read time from the flat span data.

## Details tab

The **Details** tab is the visual debugging surface. It has three sub-regions:

### Timeline bar

A row of colored horizontal segments above the graph — one segment per `tool_call` span, positioned proportionally to when in the session it occurred. Colors: green = success, red = error, yellow = timeout. Click a segment to select the corresponding node in the graph. Hover for a tooltip showing tool name, status, and latency.

### Graph toolbar

Overlaid on the top-left of the graph:

| Control | Keyboard shortcut | What it does |
|---|---|---|
| Search bar | `/` to focus | Highlights matching nodes; non-matching nodes are dimmed |
| Zoom slider | `+` / `-` | Adjusts zoom 25–250% |
| Expand All / Collapse All | — | Controls server node expansion globally |
| Failures toggle | `e` | Isolates the error chain, dims all non-failing nodes |
| Fit view | `f` | Fits all nodes into the viewport |
| Esc | `Esc` | Clears the current selection |

### Lineage graph

Interactive SVG graph showing agents, MCP servers, handoffs, and per-call breakdowns:

- **Per-tool expansion**: Each edge between an agent and a server shows a circular `+` button with the call count (e.g. `5×`). Click it to split the server node into per-tool sub-nodes, one per distinct tool called.
- **Minimap**: A 150×90px overview appears in the bottom-right corner. It shows the full graph and a viewport rectangle. Drag the rectangle to pan.
- **Right-side inspector**: Select any node, edge, or per-tool sub-node to see call counts, error rate, avg/p99 latency, tools, and token usage. Agent and server nodes also show a "View in Catalog" link.
- **Payload slideout**: Click a payload cell in the inspector to open a full-width slide-over showing the JSON with line numbers, a copy button, and a word-wrap toggle. Tabs show Input, Output, Prompt, and Completion. Press `Esc` to close.

Use this view when you want to answer questions like:

- Which agent called this MCP server in this session?
- Where did the error path branch?
- Which server edge carried the most latency?

## Trace tab

The **Trace** tab is the span-by-span view. Click any row to expand inline details:

- Tool name, status, latency, timestamps
- **Input** — the full `input_args` payload (JSON, formatted)
- **Output** — the full `output_result` payload (JSON, formatted)
- For LLM spans: **Prompt** (`gen_ai.prompt`) and **Completion** (`gen_ai.completion`)
- For failed spans: the recorded error text

Payloads are captured automatically by the SDK. No extra instrumentation is required.

## PII protection with redact_payloads

If tool arguments or results contain PII (names, emails, keys), enable payload redaction. When active, `input_args` and `output_result` are set to `null` before storage — they never reach the database.

In `.langsight.yaml`:

```yaml
redact_payloads: true
```

Or per SDK client:

```python
client = LangSightClient(
    url="http://localhost:8000",
    project_id="production",
    redact_payloads=True,
)
```

<Warning>
  When `redact_payloads` is enabled, payload panels in the Trace tab are empty. Playground Replay is also disabled because LangSight does not persist tool inputs.
</Warning>

## Side-by-side session comparison

Compare two sessions to find regressions, prompt drift, or routing differences:

1. Open a session detail page
2. Go to the **Trace** tab
3. Click **Compare**
4. Pick another recent session
5. LangSight renders an aligned diff table showing:
   - Matching tool calls in the same row
   - Latency delta
   - Status changes (success vs failure)
   - Tool calls present in only one session

This is useful for comparing a failed session against a known-good session with the same task.

## Playground Replay

Replay re-executes a session's tool calls against your live MCP servers. Use it to reproduce bugs, test fixes, or verify that a corrected prompt produces the expected tool sequence.

1. Open a session detail page
2. Click **Replay** in the page header
3. LangSight replays each tool call in order against the live MCP servers defined in your config
4. The replay is stored as a new session so it can be inspected and compared with the original

<Note>
  Playground Replay requires:
  - `redact_payloads: false` (payloads must be stored to replay them)
  - The MCP servers from the original session must be reachable
  - An `admin` role (viewers cannot trigger replays)
</Note>

Replay spans are linked back to their originals via `replay_of`. Replay sessions appear in the session list and can be compared directly against the source run.
