Supervisor API

Introspect the Erlang/OTP supervisor tree at runtime. View child processes, their states, and restart counts for debugging and operations.

Overview

The supervisor tree is the backbone of ZERG's fault tolerance. This API exposes the runtime supervision hierarchy, allowing operators to inspect which supervisors are running, their child specifications, restart strategies, and process states without accessing the Erlang shell.

Authentication

Requires Authorization: Bearer <token> with admin role.

Endpoints

List Supervisor Children

GET /api/v1/supervisor/:name/children

Returns children of a named supervisor (e.g., sol_sup, sol_infra_sup, sol_owners_sup).

Response:

{
  "ok": true,
  "supervisor": "sol_sup",
  "strategy": "rest_for_one",
  "max_restarts": 3,
  "max_seconds": 5,
  "children": [
    {
      "id": "sol_zmq_gateway",
      "type": "worker",
      "pid": "<0.123.0>",
      "status": "running",
      "module": "sol_zmq_gateway",
      "restart_count": 0
    },
    {
      "id": "sol_http_chat",
      "type": "worker",
      "pid": "<0.124.0>",
      "status": "running",
      "module": "sol_http_chat",
      "restart_count": 0
    },
    {
      "id": "sol_owners_sup",
      "type": "supervisor",
      "pid": "<0.100.0>",
      "status": "running",
      "module": "sol_owners_sup",
      "restart_count": 0
    }
  ]
}

Get Supervisor Tree

GET /api/v1/supervisor/:name/tree

Recursive tree of all children (including nested supervisors). Returns the full hierarchy as nested JSON:

{
  "ok": true,
  "supervisor": "sol_sup",
  "children": [
    {
      "id": "sol_infra_sup",
      "children": [
        { "id": "sol_autoscaler", "pid": "<0.110.0>", "restart_count": 0 },
        { "id": "sol_event_compactor", "pid": "<0.111.0>", "restart_count": 0 }
      ]
    }
  ]
}

List All Supervisors

GET /api/v1/supervisors

Returns all registered supervisors and their restart strategies:

{
  "ok": true,
  "supervisors": [
    { "name": "sol_sup", "strategy": "rest_for_one", "children": 12 },
    { "name": "sol_infra_sup", "strategy": "rest_for_one", "children": 5 },
    { "name": "sol_owners_sup", "strategy": "one_for_one", "children": 24 },
    { "name": "sol_zmq_pipeline_sup", "strategy": "simple_one_for_one", "children": 3 }
  ]
}

Available Supervisors:

Name	Strategy	Purpose
sol_sup	rest_for_one	Top-level supervisor
sol_infra_sup	rest_for_one	Infrastructure (compactor, autoscaler)
sol_owners_sup	one_for_one	ETS heir owners (24 child processes)
sol_zmq_pipeline_sup	simple_one_for_one	ZMQ pipeline workers
sol_inference_sup	simple_one_for_one	llama.cpp inference instances
sol_workflow_sup	simple_one_for_one	Workflow instances

Error Codes:

Code	Description
401	Authentication required
403	Admin role required
404	Supervisor not found

Examples:

curl http://127.0.0.1:11434/api/v1/supervisor/sol_sup/children \
  -H "Authorization: Bearer $TOKEN"

curl http://127.0.0.1:11434/api/v1/supervisors \
  -H "Authorization: Bearer $TOKEN"