监控、日志与告警
Sub2API 自带 Ops 页面，路径为 /admin/ops。它适合从请求、账号和应用三个层面做第一轮定位，但仍应配合主机、容器、PostgreSQL、Redis 和反向代理监控。
先开启两层开关
运维模块有两层控制：
- 部署硬开关：
OPS_ENABLED=true或 YAMLops.enabled: true，修改后需要重启。 - 后台软开关：系统设置中的 Ops Monitoring，可运行时启停。
实时 QPS WebSocket 还有独立软开关。Ops 接口被关闭时不应影响网关主链路。
Ops 页面能看什么
| 区域 | 主要用途 |
|---|---|
| 健康分 | 快速发现业务或基础设施退化，不作为唯一判断 |
| QPS/TPS | 当前、峰值和平均吞吐 |
| 吞吐/切换趋势 | 请求量、Token、账号切换是否异常 |
| 延迟 | duration 与 TTFT 分位数 |
| 错误趋势/分布 | 请求错误、业务限制、上游 429/529 等 |
| 并发/排队 | 平台、Group、Account、User 的 in-use 和 queue |
| 账号可用性 | 可用、限流、过载、错误和临时摘除 |
| 请求明细 | 按 Request ID、用户、Key、账号、模型定位 |
| 系统日志 | 按 component、level 和上下文检索 |
| Job heartbeat | 聚合、清理、刷新、告警等后台任务状态 |
健康分的实现侧重业务 70%、基础设施 30%；无流量时可能显示健康，不能据此证明真实模型请求可用。
/health 的边界
当前 /health 只返回进程存活：
{"status":"ok"}它不主动 Ping PostgreSQL、Redis、上游 API，也不验证调度是否有账号。因此应拆分探针：
- Liveness：
GET /health，用于判断进程能否响应。 - 外部可达性：通过公网域名访问
/health，验证 DNS/TLS/Proxy。 - 依赖健康：看 Ops system metrics 或独立检查 DB/Redis。
- 业务合成监控：用低额度专用 Key 定时请求低成本模型。
不要让合成监控使用生产用户 Key，也不要高频调用昂贵模型。
错误归因字段
排障优先看这些字段：
| 字段 | 回答的问题 |
|---|---|
| request_id / client_request_id | 是否是同一个请求 |
| phase | auth、routing、upstream、billing 等哪一阶段失败 |
| error_owner | client、provider 还是 platform |
| error_source | client_request、upstream_http 还是 gateway |
| user_id / api_key_id | 影响哪个用户和凭证 |
| group_id / account_id | 最终路由到哪里 |
| inbound/upstream endpoint | 入口与真实上游端点是否一致 |
| requested/upstream model | 模型映射是否符合预期 |
| upstream status/message | 上游真实错误是什么 |
| auth/routing/upstream/response latency | 慢在哪一段 |
先按 Request ID 查单请求，再按 account/group/platform 扩大时间范围。不要直接用错误消息全文作为唯一筛选条件。
建议的告警基线
按业务量调整，以下只作为起点：
| 告警 | 建议条件 | 级别 |
|---|---|---|
| 分组可用账号数 | < 1 持续 1 分钟 | P0/P1 |
| 分组可用比例 | < 50% 持续 5 分钟 | P1 |
| 请求错误率 | > 5% 持续 5 分钟 | P1 |
| 上游错误率 | > 10% 持续 5 分钟 | P1 |
| 限流账号比例 | > 50% 持续 5 分钟 | P1/P2 |
| 并发队列深度 | > 0 持续 5 分钟 | P2 |
| CPU | > 85% 持续 10 分钟 | P2 |
| 内存 | > 90% 持续 10 分钟 | P1/P2 |
| 错误账号数 | 超过冗余容量 | P1 |
| 临时不可调度账号 | 持续增长 | P2 |
Group 级可用账号告警必须指定 group_id。全局有账号不代表某个生产 Group 有账号。
告警运行设置
规则支持窗口、持续时间、冷却时间、严重级别、平台/Group 过滤和邮件通知。多实例环境中告警评估使用 Redis 分布式锁，避免每个副本重复发信。
运维要求：
- 配置真实收件人并发一次测试告警。
- 冷却时间不应长到掩盖持续故障。
- 维护窗口使用有截止时间和原因的 silence。
- 维护结束后检查 silence 已失效。
- resolved 通知与 firing 通知都应可追溯。
日志等级和采样
运行时可以调整日志 level、采样、caller、stacktrace 和保留期。故障调试建议：
- 先按 Request ID 使用现有 info/error 日志。
- 只对必要时间窗口提高日志等级。
- 记录开始和恢复时间。
- 结束后恢复默认，避免日志量和敏感信息风险。
系统日志写入也有自己的队列健康指标：queue depth、dropped count、write failed count、平均写入延迟。应用正常但日志 dropped 持续增长时，应处理写入压力或采样，而不是假设“没有错误”。
数据保留
Ops 默认提供错误日志、分钟指标、小时指标的清理和预聚合。保留时间要结合：
- 故障回溯周期。
- 财务和用户投诉周期。
- PostgreSQL 容量。
- 隐私与合规要求。
清理 Ops 错误日志不等于清理全部 usage 或审计数据。修改前确认具体数据集，并先备份。