Debugging a run¶
You started a test run and something went wrong. This page is the loop for finding out why — not just that it failed.
Everything here is served today. What is not built yet is named at the end, with the two operations that are still missing, followed by how the board behaves when a run finishes and how deep it can page into a very long one.
Open the run¶
The Debug page is reached from a run on the Test run page — its Debug this
run link, offered once the run has reached the platform — or directly at
/projects/{project}/debug/{run_id}, where run_id is Studio's run id, not the
platform's. It has three panels, and they answer different questions:
| Panel | The question it answers |
|---|---|
| Graph | Where did the run get to, and which steps did it visit? |
| Trace | What happened, in order, with the messages each step emitted |
| Checkpoints | What did the state look like between two steps — and what changed |
A platform answer about a different run from the one asked about is refused as
502 platform_protocol_error, never shown as this run's record. Since 0.9.0,
that check covers the graph, the checkpoint diff, the
trace's run status and Stop; 0.8.0 and earlier make it only on the run's own
status read.
Walk the graph¶
The graph shows your spec's steps with the ones the run visited marked, and, while the run is live, the step it is on marked running. A step that was never entered stays plain — which is usually the first thing worth noticing, because a run that stopped early stopped somewhere, and that somewhere is the step to read first.
The header carries the run's own status as the platform reports it — running,
completed, failed, cancelled — and whether the board is still following
the run or it has finished. The node highlight and the header read the same
answer, so they agree; When the run finishes, below, says what a finished run
looks like.
Read the trace¶
The trace is the ordered record of what each step did. It pages, newest window last, and it is the panel to read when the graph tells you where and you need what.
Each page says which events it holds, whether the platform calls the page complete, and how many events the collector lost, when the platform says. While the run is live the trace re-reads the page on screen; it does not follow the tail, so events past that page need Later.
Compare two checkpoints¶
A checkpoint is the run's state as it stood between two steps. Selecting one shows the full state it held. Selecting two of them shows a diff — which is the fastest way to find the step that put the wrong value into the state, as opposed to the step that later failed because of it. Those are rarely the same step, and the diff is what separates them.
Stop a run¶
A run that is going nowhere can be stopped from the Debug page. Stopping is final: it is not a pause, and there is no resume (see below).
Stop needs the editor role. The button is on the page for every role, and a viewer who presses it is refused. It is a cooperative request: the run stops at its next safe point, and effects that already ran stay done — a tool call that already ran, already ran. The board shows what the platform answered: that the stop was requested, that the run had already finished, or that it was already cancelled.
What is not built yet¶
Two operations from the original debug design are not here, and nothing on the page pretends otherwise:
- Replay — a read-only, deterministic replay view of a finished run
(
GET /v1/runs/{id}/replay); it re-executes nothing. - Resume — continuing a run that stopped at a human-approval step.
Neither is scheduled to a cut. See the roadmap.
When the run finishes¶
While a run is live the board re-reads the trace, the graph and the checkpoint strip every two seconds. When the trace reports the run finished, all three stop polling — a finished run's record does not change.
They also stop if the trace cannot be read at all — a stale or pasted run id that
answers 404, say. A single failed re-read during a live run is shown as an error,
and the board keeps following.
The board takes one final read at the end¶
The moment the trace reports the run finished, the board reads the graph and the checkpoint page on screen once more. So the header's finished is never shown beside a graph or a strip from before the end: the last step and the final checkpoint are on screen without a reload. A read that was still in flight from before completion is replaced by that final one, so it cannot land after it.
A finished run has nothing marked running¶
A step is marked running only while the run is live. Once the run has finished, the step it stopped on reads visited, like every other step it entered. The canvas, the header and the Stop button all take "is this run still going" from the same answer, so they cannot disagree about it. The step the run stopped on is still the one to read first.
How deep the board can page¶
The checkpoint strip stops at the platform's paging depth¶
The platform accepts a checkpoint offset of at most 10,000, and the strip shows checkpoints a hundred at a time, so the deepest page it can show ends at checkpoint 10,100. At that depth Later is disabled and the strip says it has reached as far as the platform pages. When the platform gave a total, it also says how many later checkpoints exist and cannot be read. The trace has the same bound on its events and says so the same way.
If a page fails to load, Earlier stays on screen, so a failed page does not strand you.
What to do: nothing on the board reaches past this depth — the bound is the
platform's, and Studio refuses a deeper request itself, before asking the
platform: an offset past it answers 422 invalid_checkpoint_window for
checkpoints and 422 invalid_trace_window for the trace. That matters only to a
script calling the routes directly; the board never asks. Both ceiling checks
are new in 0.9.0. On 0.8.0 and earlier neither route
checks the ceiling: a deeper offset is passed to the platform, which refuses it
with its own validation error.
Read the strip's message: it tells you whether what you are comparing is the end
of the run or only as far as the platform pages.
Earlier releases listed three rough edges of the Debug board here: the board freezing before the run's last update, a finished run's last node labelled "running", and a checkpoint page past the ceiling that failed to load. The label was fixed in 0.8.0, and the final read and the paging ceiling in 0.9.0. What remains is the platform's own paging depth, described above.