告警 runbook

BitzOrcas 模板定义告警阈值但不自动触发告警。一个外部监控系统——Prometheus、Datadog、Azure Monitor 或 Grafana——抓取 OpenTelemetry 指标并按这些阈值触发告警。本页是参考阈值表与逐信号 runbook；监控与告警覆盖通用可观测性设置。

告警阈值

逐信号诊断 runbook

通用形态：读 Operations 适配器/配置端点，检查具名子系统，检查依赖基础设施（SQL/RabbitMQ/Redis），修正配置，重启或滚动重新部署，并通过健康探针确认恢复。

/health/ready 连续失败

1. GET /api/operations/adapters——识别哪个 readiness 标记的健康检查失败。
2. GET /api/operations/config——确认连接串与 RabbitMQ 配置。
3. 连接 SQL Server 并运行 SELECT 1 确认可达。
4. 检查 RabbitMQ 管理 UI 的连接数与队列状态。
5. 若依赖恢复，Kubernetes 自动恢复流量分发。

HTTP 5xx 错误率激增

1. GET /api/audit?Category=Exception&From=<5min-ago>——读取受限 Envelope，并用 CorrelationId 关联日志与 Trace 详情。
2. 检查 OTel trace 找到错误最多的端点。
3. 对 EF Core/SqlSugar 异常，检查 DB 连接池与死锁。
4. 对 OOM，检查 dotnet-counters 的 GC 与堆大小。

CAP outbox 积压

1. RabbitMQ 管理 UI——确认 bitzorcas.* exchange 有消费者。
2. SELECT COUNT(*) FROM Cap.Published WHERE Retries < 50——查看积压量。
3. 若消费者未注册，检查 API/JobHost 是否正确启动。
4. 若 RabbitMQ 不可达，CAP 自动重试；恢复后积压排空。

作业连续失败

1. GET /api/audit?Category=BackgroundJob&Module=Auditing——读取作业结果与稳定错误码，再关联日志查看异常详情。
2. 若 IAuditRetentionPort 未注册，确认调用了 AddBitzOrcasSqlSugarAuditStore。
3. 对 SQL 执行超时，检查审计表索引与数据量。
4. 通过 scripts/database/seed-demo.sh（seed 问题）手动重跑或重启 JobHost。

生产中 InMemory/Null 适配器

1. GET /api/operations/adapters——确认哪些端口是 Default/Unavailable。
2. GET /api/operations/config——确认 ConnectionStrings:Default 与 RabbitMq:Host 已配置。
3. 若配置缺失，通过环境变量注入并滚动重启。
4. 若配置正确但适配器仍为 Default，检查 PersistenceRegistration 中的分支逻辑。

缺失/弱 key 配置

1. GET /api/operations/config——找到缺失或过短的 key。
2. 通过 K8s Secret / Key Vault 注入正确值。
3. 滚动重启。

修复前后的证据采集

先保存基础健康、适配器和配置诊断。三个响应要来自同一实例、同一时间窗，Secret 字段不得进入事件附件：

# 基础 readiness 与运行时组合快照。
curl -fsS https://<HOST>/health/ready > ready.json
curl -fsS -H "Authorization: Bearer <TOKEN>" \
  https://<HOST>/api/operations/adapters > adapters.json
curl -fsS -H "Authorization: Bearer <TOKEN>" \
  https://<HOST>/api/operations/config > config-diagnostics.json

恢复后使用相同查询窗口重新采集审计 Envelope。查询端没有 Result 参数，应按返回的 Success 与 ErrorCode 统计，不要把未识别 Query 当成服务端过滤：

# 保留时间边界，便于比较修复前后作业和异常证据。
curl -fsS --get -H "Authorization: Bearer <TOKEN>" \
  --data-urlencode "category=BackgroundJob" --data-urlencode "module=Auditing" \
  --data-urlencode "from=<INCIDENT-START-UTC>" --data-urlencode "pageSize=200" \
  https://<HOST>/api/audit > background-jobs.json

监控系统接入

另见

• 监控与告警
• 可观测性
• GA 切换 runbook