Advanced Tools

Advanced Tools

Theia ships three observe-and-control tools. All three speak to the same control surface (the supervisor's gen_server node) — they differ only in transport. tdb goes local over TIPC; rtdb and the GUI go remote over com's gRPC on :7700. See Architecture for the control surface and Tutorial for bringing the stack up.

Tool	Where	Transport	Language
tdb	tools/tdb/	local probe over TIPC	Python
rtdb	tools/rtdb/	gRPC → com → supervisor (:7700)	Python
supervisor GUI	tools/supervisor-gui/	gRPC → com (:7700)	C++ / wxWidgets

tdb — the Theia Debug Bridge (adb for Theia)

tdb is a .art-driven Python debug CLI. All its transport is probe-backed (tools/tdb/system/tdb.art via artheia.probe) — never raw TIPC. It works two ways, like adb: a one-shot command from argv (tdb ps), or an interactive prompt_toolkit REPL (bare tdb). -i <n>[,<n>...] targets a specific supervisor by TIPC instance (central=0, compute=1).

Verbs (from tools/tdb/tdb.py / tdb_commands.py):

verb	what it does
ps	list nodes from the supervisor tree
supervisor	supervisor host facts (GetSystemInfo)
info	host facts + running build (git sha/ts) + start time
trace [off] <node> [msgtype]	ConfigureTrace a node on/off (msgtype "" = all kinds)
trace off	stop all active traces
trace-config	show the stored trace config (GetTraceConfig)
loglevel [<node> [lvl]]	show all / one node's log level; with lvl, set it live
tracecat (alias logcat)	follow the trace firehose (Subscribe to log[trace]); --json = NDJSON header + decoded inner proto per line
restart <name>	RestartChild
terminate <name>	TerminateChild (stop-and-hold: no_restart=true)
get-snapshot <label>	trigger a per Snapshot and decode the .persnap into JSON (tdb-only — the per path is TIPC/artheia, no gRPC surface)

tdb ps
tdb trace sm SmStateMsg
tdb logcat --json
tdb -i 0,1 ps              # run against both supervisors with a per-instance header

tracecat/logcat follows traces, not logs — the firehose carries the Tracer records from log[trace]. A real log-tailing logcat is a separate, unimplemented feature.

rtdb — Remote Theia Debug Bridge (tdb over gRPC)

rtdb is tdb's twin for remote operation. It shares the exact command + render layer (tools/tdb/tdb_commands), so rtdb ps and tdb ps print byte-for-byte identically — only the transport client differs. Instead of local TIPC it drives gRPC to services/com's SupervisorView, so an operator outside the DMZ can observe and control the system over IP.

+--------+  gRPC :7700     +---------------+   AF_TIPC      +------------+
|  rtdb  | ──────────────▶ │  services/com │ ─────────────▶ │ supervisor │
| python │                 │  (C++ proxy)  │   localhost    │  (C++)     │
+--------+                 +---------------+                +------------+

rtdb ps                          # live tree against 127.0.0.1:7700
rtdb --target 10.0.0.5:7700 ps   # a remote machine's com
rtdb ps --follow                 # poll-stream the tree (Subscribe)
rtdb loglevel sm debug
rtdb trace sm CAST_OUT
rtdb restart p3

It exposes the same verbs as tdb minus get-snapshot. --target host:port selects the com endpoint (default 127.0.0.1:7700).

Notes:

• The live tree (ps --follow) is a poll, not a push — the supervisor's event firehose is in-process only, so com's Subscribe polls GetTree and streams each TreeSnapshot.
• tracecat/logcat subscribes to the collector's own TraceStream gRPC (default :7710, services/log egress-direct).
• Stubs are generated once with ./tools/rtdb/gen_protos.sh; re-run after any .proto change.

supervisor GUI — the wxWidgets observer

tools/supervisor-gui/ is a wxWidgets desktop application (C++17, built with CMake) that speaks com's gRPC. It is the operator's live dashboard: it connects to services/com and, by default, runs unconfigured against 127.0.0.1:7700. The SupervisorView stream is on :7700; the trace stream (com's TraceForwarder) is on :7710.

It is a multi-panel aui frame (src/panels/):

panel	shows
system_panel	supervisor host facts
processes_panel	the live process/supervisor tree
applications_panel	software components / applications
machines_panel	per-machine endpoints (from machines.yaml)
trace_panel	the live trace stream (decoded via the trace-decoder lib)
persistency_panel	services/per's typed view, via com's PerView gRPC
etcd_panel	the etcd-backed config store
load_charts_panel	per-node load charts

Build it standalone with CMake (it needs wxWidgets core/base/aui, grpc++, protobuf, and the vendored nlohmann/json):

cd tools/supervisor-gui && cmake -S . -B build && cmake --build build -j

Because all three tools talk to com (or the supervisor directly), they are interchangeable for observation; reach for tdb locally, rtdb for scripted remote control, and the GUI for live operator visibility.