Inspect the supervision tree

Use agent-data-plane debug runtime show-processes to see which processes Agent Data Plane (ADP) is running, how they are nested, which have restarted, and how much memory and CPU each accounts for.

Understand what the tree reports

ADP's runtime is a supervision tree: every unit of work is a process supervised by a supervisor, and supervisors nest to form the tree. That structure is the most complete description of what ADP is doing, so reporting it answers questions that logs answer only indirectly: whether a subsystem is running, whether it has been restarting in a loop, and which part of the tree is accumulating memory.

A worker can also have children. If a process starts work as its own, the tree shows that work under the process, not next to it. For example, a listener starts a handler for each connection that it accepts. A process does not stop until all of its children stop.

Each node reports:

Field	Meaning
name	The process's name, as registered with its supervisor.
kind	Whether the node is a supervisor or a worker.
state	running, exited (ran and was not restarted), or registered (declared but not currently running).
process_id	The identifier of the node's most recent process. A restart produces a new one.
process_name	The fully qualified, dot-scoped process name.
restart	The restart policy of the node: permanent (restarted after any stop that nobody requested), transient (restarted only after a failure), or temporary (never restarted). Two facts set the policy: whether the node can start again, and whether its owner can work without it.
significant	Whether the owner of the node also stops when the node stops and is not restarted.
created_at	When the node first became part of the tree. Constant across restarts.
started_at, uptime_ms	When the node's most recent process started, and how long it has been running.
restart_count	Restarts since the node was created, including those caused by its supervisor restarting.
resources	Allocation and CPU accounting, for supervisors and topology components.
supervision	Restart strategy and runtime placement, for supervisors.

Two details are worth knowing before reading the numbers.

NOTE

The tree reports resource figures for each resource group, not for each worker. Most workers do not own a resource group. They use the resource group of the supervisor or component above them. Thus, the figures of the node named in their resource_group field already include their allocations, and these workers show no figures of their own. Each supervisor and each topology component owns a resource group and shows its figures.

NOTE

Allocation figures require the tracking allocator, and CPU figures require per-thread CPU accounting. When either is unavailable, the counts read zero. Check the resource_tracking_enabled field, or the resource tracking off line in the tree output, to tell nothing allocated from nothing measuring.

The difference between created_at and started_at is the time a node has spent not running since it was created, which is the figure worth looking at when something is restarting repeatedly.

A statically declared process that exits without being restarted stays in the tree as exited, because it remains part of ADP's declared shape. Dynamically spawned processes, such as one per connection, are removed once they finish, so the tree does not grow without bound.

A node that has run keeps process_id, process_name, and started_at after it stops, so a stopped process still says what it ran as. Read state to tell whether that process is the current one, and uptime_ms, which is present only while a node is running. These three fields are absent only for a node that has never run.

Show the tree

$ agent-data-plane debug runtime show-processes
Supervision tree for 'adp-root', captured 2026-09-03T12:00:00Z
  54 processes (8 supervisors, 46 workers): 53 running, 1 exited, 0 registered
  3 restarts across the tree, max depth 6
  resource tracking on: 24.1 MiB live, 12.3s CPU

adp-root  [sup] running  pid=1  up=2h15m  one_for_one(0/5s)  live=1.2 MiB
|-- app-bootstrap  [sup] running  pid=3  up=2h15m  one_for_one(1/5s)  live=104.0 KiB
|   |-- logging  [sup] running  pid=4  up=2h15m  one_for_one(1/5s)  live=12.0 KiB
|   |   `-- level-override-processor  [worker] running  pid=5  up=2h15m
|   `-- metrics  [sup] running  pid=6  up=2h15m  one_for_one(1/5s)  live=92.0 KiB
|       |-- flusher  [worker] running  pid=7  up=2h15m
|       `-- reflector  [worker] running  pid=8  up=2h15m
|-- internal-sup  [sup] running  pid=10  up=2h15m  one_for_one(1/5s)  live=890.0 KiB
|   `-- ctrl-pln  [sup] running  pid=11  up=2h15m  restarts=1  one_for_one(1/5s)  rt=1thr  live=612.0 KiB
`-- primary  [worker] running  pid=20  up=2h15m  significant
    `-- topology.primary  [sup] running  pid=21  up=2h15m  one_for_one(0/5s)  live=2.1 MiB
        |-- sources.dsd_in  [worker] running  pid=22  up=2h15m  significant  live=9.8 MiB
        |   |-- datagram_decoder_0  [worker] running  pid=24  up=2h15m
        |   `-- listener_udp  [worker] running  pid=25  up=2h15m  significant
        |       `-- conn_udp  [worker] running  pid=26  up=2h15m
        `-- forwarders.dd_out  [worker] running  pid=23  up=2h15m  significant  live=6.5 MiB

Indentation and branch glyphs show the nesting. A supervisor's line also carries its restart strategy as mode(intensity/period), and rt=Nthr when it runs on its own runtime rather than its parent's. significant marks a node that stops its owner if it stops and is not restarted. For example, each topology component is significant, because the topology cannot run without it.

Nodes that need attention stand out without needing color: restarts= appears only when a node has actually restarted, and a stopped process is marked EXITED in capitals.

Change the output format

Use --format (-f) to select the output format. The default is tree.

Pass --json (-j), or --format json, to get the endpoint's payload unchanged. The payload is passed through verbatim rather than re-serialized, so fields the CLI does not yet know about still reach whatever consumes it:

$ agent-data-plane debug runtime show-processes --json | jq '.totals'
$ agent-data-plane debug runtime show-processes --json | jq '.. | objects | select(.restart_count > 0) | .process_name'

Pass --format dot to emit a Graphviz graph. Supervisors are drawn with a bold border, stopped processes are filled, and processes that are declared but not running are dashed:

$ agent-data-plane debug runtime show-processes --format dot | dot -Tsvg > tree.svg

Endpoint

Route	Method	Description
/runtime/processes	GET	A snapshot of the supervision tree, as JSON.

The route is served on the privileged API endpoint (data_plane.secure_api_listen_address, tcp://0.0.0.0:5101 by default), which requires the IPC client certificate. A snapshot names every process and reports its resource accounting, so it is authenticated the same way as the other state dumps such as /config and /config/runtime.

The same snapshot is collected into support flares as supervision_tree.json.

TIP

Process names are shared across ADP's registries, so a snapshot joins against /memory/status, /ready, and resources.json on the process_name field with no translation.

NOTE

A supervisor running on its own runtime, such as ctrl-pln, reports an unscoped process name (ctrl_pln rather than adp_root.internal_sup.ctrl_pln), because it re-roots its name when it starts. /memory/status additionally lists a scoped entry for such a supervisor that always reads zero. Both are known defects; the tree reports the name that the supervisor's allocations are actually attributed to.