Snapshots & Gated Routes
Exact Top, Debug, and Bench routes, switches, and authentication boundaries.
Top snapshot
GET /top/v1/snapshot returns node-local JSON with version=top/v1 and scope=local_node. It neither depends on Prometheus nor fans out across the cluster.
| Query | Default | Constraint |
|---|---|---|
window | 10s | Go duration, minimum 2s |
view | overview | overview, runtime, traffic, channel, storage, delivery, or all |
limit | 20 | Positive integer; values above 100 clamp to 100 |
A missing provider returns 404, collector warm-up returns 503, and an invalid query returns 400. There is no built-in authentication, and the contract is unstable.
/top/v1/snapshotReturns a bounded local-node observation. It is not a cluster-wide consistent snapshot.
Query Parameters
Go duration; minimum 2s.
"10s"Snapshot section selector.
"overview"Value in
- "overview"
- "runtime"
- "traffic"
- "channel"
- "storage"
- "delivery"
- "all"
Pressure-item limit; values above 100 are clamped.
1 <= value20Response Body
application/json
application/json
application/json
application/json
application/json
{ "version": "top/v1", "scope": "local_node", "generated_at": "2019-08-24T14:15:22Z", "window_seconds": 2, "node": { "id": 0, "name": "string", "ready": true, "ready_parts": { "property1": true, "property2": true }, "state_revision": 0, "controller_leader": 0, "slot_count": 0, "hash_slot_count": 0 }, "verdict": { "level": "ok", "summary": "string", "reasons": [ "string" ] }, "traffic": { "send_per_sec": 0, "sendack_per_sec": 0, "sendack_error_per_sec": 0, "sendack_error_rate": 0, "append_per_sec": 0, "append_p50_ms": 0, "append_p99_ms": 0, "deliver_per_sec": 0, "fanout_rate": 0 }, "clients": { "connections": 0, "connections_by_protocol": { "property1": 0, "property2": 0 }, "auth_fail_per_sec": 0, "close_per_sec": 0 }, "resources": { "cpu_percent": 0, "memory_rss_bytes": 0, "memory_vms_bytes": 0, "goroutines": 0, "threads": 0 }, "alerts": { "counts": { "active": 0, "recent": 0, "warning": 0, "error": 0, "critical": 0 }, "active": [ { "id": "string", "fingerprint": "string", "node_id": 0, "node_name": "string", "severity": "warn", "component": "string", "kind": "string", "message": "string", "hint": "string", "evidence": { "property1": "string", "property2": "string" }, "first_seen": "2019-08-24T14:15:22Z", "last_seen": "2019-08-24T14:15:22Z", "resolved_at": "2019-08-24T14:15:22Z", "count": 0, "active": true } ], "recent": [ { "id": "string", "fingerprint": "string", "node_id": 0, "node_name": "string", "severity": "warn", "component": "string", "kind": "string", "message": "string", "hint": "string", "evidence": { "property1": "string", "property2": "string" }, "first_seen": "2019-08-24T14:15:22Z", "last_seen": "2019-08-24T14:15:22Z", "resolved_at": "2019-08-24T14:15:22Z", "count": 0, "active": true } ] }, "pressure": { "overall_level": "string", "component_scores": { "property1": 0, "property2": 0 }, "top": [ { "component": "string", "pool": "string", "queue": "string", "priority": "string", "level": "string", "score": 0, "depth": 0, "capacity": 0, "inflight": 0, "workers": 0, "wait_p99_ms": 0, "task_p99_ms": 0, "admission_error_per_sec": 0, "hint": "string" } ] }, "channelv2": { "active_total": 0, "active_leader": 0, "active_follower": 0, "follower_parked": 0, "reactor_mailbox_depth_max": 0, "reactor_mailbox_capacity_max": 0, "worker_queue_depth_by_pool": { "property1": 0, "property2": 0 }, "worker_queue_capacity_by_pool": { "property1": 0, "property2": 0 }, "worker_inflight_by_pool": { "property1": 0, "property2": 0 }, "worker_capacity_by_pool": { "property1": 0, "property2": 0 }, "append_p99_ms": 0, "hot_stage": "string", "stage_p99_ms": { "property1": 0, "property2": 0 } }, "storage": { "commit_queues": [ { "store": "string", "depth": 0, "capacity": 0, "request_p99_ms_by_lane": { "property1": 0, "property2": 0 }, "batch_records_p50": 0, "batch_commit_p99_ms": 0 } ] }, "delivery": { "push_per_sec": 0, "routes_per_sec": 0, "push_p99_ms": 0, "retry_queue_depth": 0, "ack_bindings": 0, "recipient_queue_depth": 0, "recipient_queue_capacity": 0, "error_rate": 0 }, "sources": { "collector": { "available": true, "sample_count": 0, "warming_up": true }, "cluster_snapshot": { "available": true, "sample_count": 0, "warming_up": true }, "metrics": { "enabled": true, "required": false }, "notes": [ "string" ] }}Debug: 9 registrations
All require observability.debug_api_enable=true. When bench.api_token is configured, every /debug/* request also needs that exact Bearer; with an empty token there is no built-in authentication.
| Method | Path | Extra condition |
|---|---|---|
GET | /debug/config | Config provider required |
GET | /debug/cluster | Cluster provider required |
GET | /debug/diagnostics/trace/:trace_id | Diagnostics store required |
GET | /debug/diagnostics/message | Diagnostics store required |
GET | /debug/diagnostics/events | Diagnostics store required |
GET | /debug/goroutines | None |
GET | /debug/goroutines/summary | Returns 404 without a registry provider |
ANY | /debug/pprof | None |
ANY | /debug/pprof/*name | Standard CPU, heap, goroutine, and other pprof subroutes |
Bench: 12 registrations
All require bench.api_enable=true. A non-empty bench.api_token protects every route with an exact Bearer; an empty token preserves unauthenticated compatibility. Restore maintenance rejects Bench requests.
| Method | Path |
|---|---|
GET | /bench/v1/capabilities |
GET | /bench/v1/capacity-target |
GET | /bench/v1/snapshot |
GET | /bench/v1/presence/snapshot |
POST | /bench/v1/terminal-fence/prepare |
GET | /bench/v1/channel-runtime/snapshot |
POST | /bench/v1/channel-runtime/probe |
POST | /bench/v1/channel-runtime/evict |
POST | /bench/v1/users/tokens |
POST | /bench/v1/channels |
POST | /bench/v1/channels/subscribers |
POST | /bench/v1/channels/subscribers/remove |
terminal-fence/prepare additionally requires a Terminal Fence Controller and a non-empty token. Bench performs data preparation, runtime eviction, and terminal fencing; it is neither read-only nor a public integration contract.