Skip to content

Process Tracker

Jump to bottom
Yousef Ghadiri edited this page Jun 16, 2026 · 4 revisions

Process Tracker

When enabled with --pid, Knightwatch tracks a root process and its entire child tree in real time, exposing snapshots via the /process family of endpoints. It also emits lifecycle events to the Telegram bot and webhook dispatcher.

knightwatch --pid <PID>

Pass --pid multiple times to track more than one root process simultaneously:

knightwatch --pid <PID1> --pid <PID2>

Endpoints

Endpoint Description
GET /api/root_pids List of all PIDs currently being tracked
GET /api/process/<PID> Full snapshot — root info, child processes, and work_done flag
GET /api/process/trees All process trees currently being tracked
GET /api/process/root/<PID> Root process snapshot only, or 404 if it has exited
GET /api/process/children/<PID> Snapshots of all currently live child processes
GET /api/process/status/<PID> Lightweight summary — alive/dead, child count, and work_done flag
GET /api/process/is-done/<PID> Returns true if all children have exited, or 404 if the PID is not tracked
GET /api/top-processes Top N processes sorted by CPU, memory, or disk (requires --top-processes)
GET /api/supported-signals Signals supported on the current platform

Process Commands

When the server is started with --allow-process-commands, the following write endpoints become available. These endpoints are not read-only — they actively affect running processes.

Authentication required. All process command endpoints always require authentication, regardless of whether --enable-auth is set. The auth session endpoints are automatically enabled alongside --allow-process-commands.

knightwatch --pid <PID> --allow-process-commands

Command Endpoints

Endpoint Description
POST /api/process/kill/<PID> Send a signal to a specific process
POST /api/process/kill-tree/<PID> SIGKILL a root process and its entire descendant subtree
POST /api/process/track/<PID> Begin tracking a new root PID
POST /api/process/untrack/<PID> Stop tracking a root PID and discard its state
POST /api/process/poll/pause Pause the polling loop
POST /api/process/poll/resume Resume the polling loop
POST /api/process/poll/interval Change the polling interval

Killing a Process

Send a signal to a single process by PID:

POST /api/process/kill/1234
Content-Type: application/json
 
{ "signal": "term" }

Available signals depend on the platform (see /api/supported-signals):

Signal Value Description
Kill kill Forceful termination (supported on all platforms)
Interrupt int Interrupt (Unix only)
Stop stop Pause execution (Unix only)
Continue cont Resume a stopped process (Unix only)
Terminate term Graceful termination request (Unix only)

On Windows, only kill is supported. Sending any other signal returns 400.

Killing a Process Tree

Sends SIGKILL to a root process and every process in its descendant subtree. Returns the list of PIDs that were successfully signalled:

POST /api/process/kill-tree/1234
[1234, 1235, 1236]

Tracking and Untracking

Track a new root PID at runtime without restarting the server:

POST /api/process/track/5678

Stop tracking a root PID and discard its accumulated state:

POST /api/process/untrack/5678

Both return 200 OK. Tracking an already-tracked PID is a no-op.

Controlling the Poll Loop

Pause snapshot collection (the tracker still responds to queries and commands):

POST /api/process/poll/pause

Resume at the current interval:

POST /api/process/poll/resume

Change the polling interval (takes effect immediately):

POST /api/process/poll/interval
Content-Type: application/json
 
{ "interval_ms": 2000 }

Process States

The state field on a process snapshot can be running, sleeping, gone, or any other platform string. Unknown states are rendered as a warning-colored pill in the dashboard.

Work-Done Detection

The work_done flag is set to true when all child processes of a tracked root have exited. The dashboard shows a completion banner at this point. The root process itself may still be running.

Use GET /api/process/is-done/<PID> for a lightweight boolean check without fetching the full snapshot.

Webhook Events

Event Description Key data fields
process.initial_snapshot First capture after startup root, children, child_count
process.children_appeared New child processes detected pids, children
process.children_exited One or more children exited pids
process.all_children_gone All children have exited root_pid, root_name
process.root_exited Root process exited pid, name
process.work_complete Work-done condition met root_pid, root_name
process.process_killed A process was killed via a kill or kill-tree command pid, success

Telegram Notifications and Commands

  • 🟢 Initial snapshot — root and child count when tracking begins
  • 🆕 Children appeared — new child PIDs detected
  • 🔴 Children exited — specific child PIDs exited
  • ✅ All children gone — all child processes have exited
  • 💀 Root process exited — the root process itself has stopped When --allow-process-commands is enabled, the Telegram bot also supports process commands (kill, track, untrack, poll control). Authentication is always required for these commands, even via Telegram.

Clone this wiki locally