Observability HTTP API

Observability HTTP API

An opt-in, read-only HTTP surface served on the same port as the socket server (default 17352) — no second port to firewall. Off by default: without the option, no HTTP endpoint exists at all.

{ "http_api": { "enabled": true } }

(or http_api: { enabled: true } in new Server(...).)

Endpoints

Endpoint	Auth	Returns
GET /health (also /healthz)	none	{ status, version, uptime_seconds, node_id } — for load balancers and k8s probes
GET /api/metrics	Bearer admin token¹	Prometheus text format
GET /api/stats	Bearer admin token	per-realm producer/consumer totals + online counts, subscription counts, current connections, cluster node id
GET /api/realms/{realm}/dlq	Bearer admin token	{ realm, entries: [...] } dead-letter contents
POST /api/realms	Bearer management token (prefix-scoped)	create a realm under the token's realm_prefix (or rotate its manager_key); accepts {realm, manager_key, ephemeral?, ttl?}; tokens marked ephemeral_only always create ephemeral realms with TTL capped at their max_ttl (0.16.1) and returns {ok, realm, created, manager_key_configured, ephemeral, expires_at} — see Ephemeral Realms

¹ When server auth is disabled, no token is required anywhere. Set http_api.metrics_auth: false to open /api/metrics for scrapers that cannot send headers (Prometheus itself can: use authorization: { credentials: <admin-token> } in the scrape config). Individual endpoints can be disabled with health: false, metrics: false, stats: false.

curl -s localhost:17352/health
curl -s -H "Authorization: Bearer $TYO_MQ_ADMIN_TOKEN" localhost:17352/api/metrics

Metrics

tyo_mq_connections_total                                  counter
tyo_mq_connections_current                                gauge
tyo_mq_messages_produced_total{realm,event}               counter
tyo_mq_messages_delivered_total{realm,event}              counter
tyo_mq_messages_queued_total{realm}                       counter (durable enqueues)
tyo_mq_messages_dlq_total{realm}                          counter (moves to DLQ)
tyo_mq_ack_timeout_total{realm}                           counter

Counters are in-memory and reset on restart — normal for Prometheus counters (use rate()/increase()).

Design notes

• The surface is read-only by design, with one deliberate exception: POST /api/realms for automated realm provisioning, gated by prefix-scoped management bearer tokens (auth.management_tokens) that can only touch realms under their own prefix. All other writes (realm config, token revocation, DLQ replay/discard) stay on the signed socket command channel, where the admin credential never crosses the wire. See Management Commands.
• Works when socket.io is attached to an external HTTP server too — the handler answers only its own paths and leaves everything else to the host.
• Per-node in a cluster: scrape each node; /health exposes the cluster node_id.