> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugger

> Trace a run from its session to its events: what ran, in what order and, when the run's tracing kept it, with what data.

export const Scope = ({type, href}) => {
  const scopes = {
    workflow: ['the ', 'Workflow', ' blob type', '/blob-types/introduction#workflow'],
    scheduler: ['the ', 'Scheduler', ' blob type', '/blob-types/scheduler/overview'],
    onnx: ['the ', 'ONNX Model', ' blob type', '/blob-types/introduction#onnx'],
    worker: ['', 'blobhub-worker', ', which runs on your machines', '/worker/introduction']
  };
  const scope = scopes[type];
  if (!scope) {
    return <p>Unknown scope: {type}</p>;
  }
  return <p className="text-sm text-gray-600 dark:text-gray-400">
      Provided by {scope[0]}<strong>{scope[1]}</strong>{scope[2]}. · <a href={href || scope[3]}>Reference</a>
    </p>;
};

export const Shot = ({src, alt, caption}) => <Frame caption={caption}>
    <img className="block dark:hidden" src={src} alt={alt} />
    <img className="hidden dark:block" src={src.replace(/\.(png|svg)$/, '.dark.$1')} alt={alt} />
  </Frame>;

<Scope type="workflow" href="/blob-types/workflow/workflows/execution-events" />

The debugger is the web app's view of the record for a workflow. It lists the workflow's sessions, the runs in each
one and every event a run wrote, so you can see what ran, in what order and, when the run's tracing kept it, with
what data. It is a tab on every workflow at blobhub.io, beside the editor and the playground, and everything it shows
is read from the same recorded logs any client can page through the API.

## Sessions

The debugger opens on the sessions of the revision on screen, each with its id, alias, description, status and
creation time. Opening a session lists its runs. On a draft you can write to, **New Session** creates another, and a
session offers **Edit Session** for its alias, description and tracing, **Close Session**, **Reopen Session** once it
is closed, and **Delete Session**.

Closing and deleting finish in the background. The tab you clicked in rereads the session's status for up to a
minute, until it settles; another tab, or another person watching the same session, sees the new status only after
reloading the page.
[Sessions](/general/sessions) covers what each status means.

## Executions

A session's runs are listed newest first, each with its id, when it started, how long it took, its definition, its
caller, its description and its status. On a draft you can write to, **New Execution** starts another in an open
session, from a definition of the revision on screen.

Each run is labelled from its own record, not from the definitions as they stand today. The Definition column shows
the alias the definition had when the run resolved it, and a run whose definition came from another revision or
another workflow is marked with that source, as text to read rather than a link the debugger follows. The Caller is
whoever started the run, and for a scheduled run, whoever created the schedule.
[List Executions](/blob-types/workflow/operations/list-executions) returns the same records.

<Shot src="/general/images/debugger/executions.png" alt="A session's executions in the debugger" caption="Every run in a session, with what it ran and how it ended." />

## Timeline and event data

Opening a run shows it in three panes. The first holds the run's record and the graph it ran, drawn from the run's own
[snapshot](/blob-types/workflow/workflows/execution-snapshot): the copy of the definition taken when the run was
created, so later edits never change what you see. Beside the graph are the reference as the run asked for it, the
definition it resolved to, and where the snapshot came from: taken at creation; marked backfilled, copied after the
run, for a few older runs; or none, for older runs whose graph is the definition as it stands now.

The second pane lists the run's events in order: the flow entering and exiting, each component entering and exiting
with the route it took and how long it ran, and any output, warning or error a component reported. Selecting an event
highlights its component on the graph and opens the event in the third pane, with its details and, under
**Event Data**, the data it carries. [Execution Events](/blob-types/workflow/workflows/execution-events) defines each
event.

Some components attach data to their events, such as a model call's request and response, with the secrets of the
credentials it used masked. That data is kept only when the run's tracing sets `log_data`, which is off by default. A
run takes its session's tracing, set in **Tracing** when the session is created or edited, and a run started through
the API can set its own. [List Execution Events](/blob-types/workflow/operations/list-execution-events) and
[Download Event Data](/blob-types/workflow/operations/download-execution-event-data) read the events and their data
through the API.

<Shot src="/general/images/debugger/timeline.png" alt="One execution's graph, timeline and an event's details" caption="The graph is drawn from the definition the run actually used, not today's." />

## Following a run

While a run has not ended, its event list rereads the log about once a second and adds the events written since the
last one it holds. The **Auto refresh until terminal status** switch turns that off, and **Load Older Events** and
**Load Newer Events** page by hand. Nothing is pushed to the debugger: what you see is the log as of its last read.
On a draft you can write to, **Stop Execution** stops a running run, leaving its flow unfinished.

The SDK reads the same record. `run.events()` returns a run's whole event log, `run.wait()` can hand each new event to
a callback, `run.stop()` stops the run, and `run.url` opens it here, in the debugger.
[Workflow](/sdk/workflow) covers the module.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.