Session and Trace Debugging

Use this recipe when you already have one bad conversation, one failing sample, or one suspicious run. The reliable order is session first, traces second, Agents third.

When to use this workflow

• you need to answer “what actually happened in this conversation?”
• you need to identify which tool call, span, or runtime action caused the outcome
• you need to decide whether the failure is isolated or systemic

What you need before you start

• the session ID, evaluation sample, or run you care about
• the correct workspace and project
• a decision about whether you are debugging the current local TUI process or a remote runtime

Start here	Use it for
Ctrl+B or /sessions	transcript and narrative context
Ctrl+T or /traces	remote OTEL-backed execution detail
/spans	local TUI JSONL span output for the current process
Agents Data	exact queries against otel_traces after the target run is known

Recipe

1. Reopen the session first

dreadnode
# inside the TUI:
# 1. press Ctrl+B or run /sessions
# 2. reopen the thread you want to inspect
# 3. use /rename <title> or /compact [guidance] if the thread needs cleanup before continuing

This gives you the narrative record: what the user asked, what the assistant said, and whether the conversation itself became confused.

2. Move to remote traces for execution detail

Use Ctrl+T or /traces when the question becomes execution behavior:

• which tools ran
• which spans were slow or failed
• whether retries or branches explain the bad output
• whether runtime state points to a missing secret, bad environment, or tool mismatch

Note

A session transcript and a trace are related but not interchangeable. One session can produce many traces, and not every trace maps neatly to one assistant message.

3. Use /spans only for the current local TUI session

Use /spans when the bug is in the TUI process itself and you want the raw local event stream before it reaches the remote trace store.

This is most useful for:

• confirming spans are being emitted at all
• checking local ordering of task and tool events
• debugging exporter behavior

4. Widen into Agents after you know the target run

Move into Agents only after you know which run or span matters:

• Charts for broad trend questions
• Data for exact queries and exports from otel_traces
• Notebook when you need traces, runs, and evaluation context together

Carry the same workspace and project context forward so you do not compare unrelated work.

5. Decide the next action

Once the failure mode is clear:

• continue the session after /compact [guidance]
• reprovision or reset the runtime if the problem is environmental
• update secrets, capability config, or task selection if configuration is wrong
• promote the issue into a wider evaluation or optimization workflow if the pattern is systemic

What to keep

• the session ID
• the trace or span IDs that explain the failure
• the exact prompt or assistant turn that anchors the investigation
• the saved Agents query or export if the issue widened beyond one run

Branches and decisions

• if the failure starts from one conversation, use traces before Agents
• if the issue only exists in the local TUI process, stay in /spans and local debugging longer
• if the same pattern appears across multiple sessions or evaluations, switch from debugging to regression or ops workflow design

Sessions & Traces

Sessions Concept

Agents

Runtimes