# 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；禁止为了通知便利把高基数标识加入指标标签。