68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# Event Bridge 开发阶段可观测性与 SLO 合同
|
||
|
||
## 状态与边界
|
||
|
||
本文冻结代码侧指标、SLI/SLO 和告警表达式模板。它不表示任何环境已经部署、接入或启用了
|
||
Prometheus、Alertmanager 或 Grafana，也不授权部署、访问环境或修改环境配置。
|
||
|
||
指标标签只允许 `target_region`、`event_type`、`result`：
|
||
|
||
- `target_region` 仅为 `CN`、`OVERSEAS`、`OTHER`。
|
||
- `event_type` 仅为 `EventTypes` 已登记类型或 `OTHER`。
|
||
- `result` 仅为代码中冻结的接收或传输结果枚举。
|
||
- 严禁把 `eventId`、`customerId`、聚合 ID、错误消息、请求 URL 或操作人写入指标标签。
|
||
|
||
## 指标合同
|
||
|
||
| Prometheus 指标 | 含义 |
|
||
|---|---|
|
||
| `baiyue_event_bridge_receive_total` | 接收结果；`result=RECEIVED|DUPLICATE|CONFLICT` |
|
||
| `baiyue_event_bridge_transport_total` | 传输结果；`result=DELIVERED|RETRY|DEAD|ACKNOWLEDGED_LEASE_LOST|FAILED_LEASE_LOST|MANUAL_REPLAY` |
|
||
| `baiyue_event_bridge_delivery_latency_seconds_bucket` | 从 Event Bridge `received_at` 到下游首次成功确认；固定包含 60 秒和 900 秒 SLO 桶 |
|
||
| `baiyue_event_bridge_inbox_backlog` | 当前 `RECEIVED`、`RETRY`、`PROCESSING` 数量 |
|
||
| `baiyue_event_bridge_inbox_oldest_age_seconds` | 当前最老待处理事件自 `received_at` 起的年龄 |
|
||
| `baiyue_event_bridge_inbox_dead` | 当前 `DEAD` 数量 |
|
||
|
||
`DELIVERED` 与 `ACKNOWLEDGED_LEASE_LOST` 都表示下游已经确认，因此均记录确认延迟；后者仍单独计数，
|
||
不得冒充本地 Inbox 已成功更新。`RETRY`、`DEAD`、`FAILED_LEASE_LOST` 不记录成功延迟。
|
||
|
||
Inbox Gauge 由服务每 30 秒执行一次受控聚合查询并缓存；Prometheus scrape 只读取 Micrometer Gauge，
|
||
不得触发数据库查询。查询仅处理 `RECEIVED`、`RETRY`、`PROCESSING`、`DEAD`，状态过滤以现有
|
||
`idx_bridge_inbox_consume(status, next_retry_at, lease_until)` 为索引依据；本合同不新增或修改 SQL 结构。
|
||
|
||
## 开发阶段 SLI 与 SLO
|
||
|
||
SLI 从事件首次得到 `result=RECEIVED` 开始，到下游首次成功确认结束；`DUPLICATE` 和 `CONFLICT`
|
||
不重复进入分母。滚动 30 天目标：
|
||
|
||
- 99% 的新接收跨区事件在 60 秒内得到下游确认。
|
||
- 99.9% 的新接收跨区事件在 15 分钟内得到下游确认。
|
||
|
||
代码暴露固定延迟桶，目标查询模板如下；按 `target_region` 汇总，必要时可保留有限 `event_type` 分组：
|
||
|
||
```promql
|
||
sum(rate(baiyue_event_bridge_delivery_latency_seconds_bucket{le="60.0"}[30d]))
|
||
/
|
||
sum(rate(baiyue_event_bridge_receive_total{result="RECEIVED"}[30d])) >= 0.99
|
||
```
|
||
|
||
```promql
|
||
sum(rate(baiyue_event_bridge_delivery_latency_seconds_bucket{le="900.0"}[30d]))
|
||
/
|
||
sum(rate(baiyue_event_bridge_receive_total{result="RECEIVED"}[30d])) >= 0.999
|
||
```
|
||
|
||
## 告警合同
|
||
|
||
规则由实际监控平台按 30 秒或更短评估周期配置；以下只是表达式合同：
|
||
|
||
- 新增 DEAD：下一次评估立即告警，不设置持续等待。
|
||
`sum(increase(baiyue_event_bridge_transport_total{result="DEAD"}[1m])) > 0`
|
||
- 最老待处理年龄预警：任一有限标签序列超过 120 秒。
|
||
`max(baiyue_event_bridge_inbox_oldest_age_seconds) > 120`
|
||
- 最老待处理年龄严重：任一有限标签序列超过 900 秒。
|
||
`max(baiyue_event_bridge_inbox_oldest_age_seconds) > 900`
|
||
- 当前 DEAD 存量用于持续可见性：`sum(baiyue_event_bridge_inbox_dead) > 0`；它不替代“新增 DEAD”告警。
|
||
|
||
告警通知中可通过日志和业务查询再定位 event ID；禁止为了通知便利把高基数标识加入指标标签。
|