只读快照与受限入口
Top、Debug 和 Bench 的精确路由、开关与认证边界。
Top 快照
GET /top/v1/snapshot 返回节点本地 JSON，version=top/v1、scope=local_node。它不依赖 Prometheus，也不做集群 Fan-out。
| Query | 默认值 | 约束 |
|---|---|---|
window | 10s | Go duration，最小 2s |
view | overview | overview、runtime、traffic、channel、storage、delivery、all |
limit | 20 | 正整数；超过 100 时收敛为 100 |
无 Provider 返回 404，采集器预热返回 503，非法 Query 返回 400。入口没有内建认证，合同不稳定。
GET
/top/v1/snapshot返回有界的节点本地观测；它不是集群全局一致快照。
查询参数
window?string
Go duration，最小 2s。
默认
"10s"view?string
快照分区选择器。
默认
"overview"值于
- "overview"
- "runtime"
- "traffic"
- "channel"
- "storage"
- "delivery"
- "all"
limit?integer
压力项上限；超过 100 会被截断。
范围
1 <= value默认
20响应主体
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 条注册
全部要求 observability.debug_api_enable=true。配置了 bench.api_token 时，所有 /debug/* 还要求精确 Bearer；未配置时没有内建认证。
| Method | Path | 附加条件 |
|---|---|---|
GET | /debug/config | 需要 Config Provider |
GET | /debug/cluster | 需要 Cluster Provider |
GET | /debug/diagnostics/trace/:trace_id | 需要 Diagnostics Store |
GET | /debug/diagnostics/message | 需要 Diagnostics Store |
GET | /debug/diagnostics/events | 需要 Diagnostics Store |
GET | /debug/goroutines | 无 |
GET | /debug/goroutines/summary | 无 Registry Provider 时返回 404 |
ANY | /debug/pprof | 无 |
ANY | /debug/pprof/*name | CPU、heap、goroutine 等标准 pprof 子路由 |
Bench：12 条注册
全部要求 bench.api_enable=true。bench.api_token 非空时全部要求精确 Bearer；空值保留无认证兼容行为。恢复维护会拒绝 Bench 请求。
| 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 还要求 Terminal Fence Controller 和非空 Token。Bench 包含数据准备、运行时驱逐和终止栅栏，不是只读接口，也不是公共集成合同。