Runbook 结构

用固定模板结构化 runbook：症状、诊断、步骤、验证、升级。

为什么

凌晨 3 点无人读一墙散文的 runbook — 值班工程师扫 30 秒若找不到"我做什么"就瞎来。固定模板（症状 → 诊断 → 步骤 → 验证 → 升级）使 runbook 可扫：症状确认"是这是我的告警"、步骤编号可复制粘贴、验证告诉何时停、升级告诉何时放弃。这结构也使 runbook 20 分钟可写而非 2 小时，因作者填表而非写散文。采用模板的团队报一周内 80% runbook 写于告警后，无模板则 20% — 结构去写摩擦。

何时使用

创建任何告警前或立即后。每告警须链接此结构 runbook。

如何做

1. 每 runbook 用固定模板
   ## <告警名>
   **症状：** 用户术语下告警意味什么
   **诊断：** 如何确认这是对的 runbook（查询、仪表盘链接）
   **步骤：** 编号、可复制粘贴命令、每步带预期输出
   **验证：** 如何确认问题解决
   **升级：** 步骤不工作时 page 谁

2. 症状用用户术语非指标术语
   - "结账错误率 >1%" → "用户无法完成购买"
   - 值班需知用户影响非仅指标

3. 步骤编号且可复制粘贴
   - "1. 跑：kubectl get pods -n checkout | grep Crash"
   - "2. 若 pod 崩，跑：kubectl logs <pod> --tail=50"
   - 每步有命令和预期输出 — 无散文

4. 含验证
   - "确认：结账仪表盘错误率 <0.1% 持续 5m"
   - 这告诉值班何时停并宣布解决

5. 从告警链接 runbook
   - 告警注解：runbook_url；paging 系统在 page 中展示它
   - runbook 在稳定 URL（git 版本化，非会腐的 Confluence 页）

示例

# runbook/checkout-slo-burn.md
## CheckoutSLOBurnRateFast
**症状：** 用户无法完成购买；结账错误率 >1%。
**严重性：** SEV1（影响收入）— 立即 page。

**诊断：**
1. 开结账仪表盘：https://grafana/d/checkout
2. 确认过去 5m 错误率 >1%（若 <1%，告警过期 — 关它）
3. 按路由查错误分解：哪个端点在失败？

**步骤：**
1. 查最近部署：
   ```bash
   kubectl rollout history deploy/checkout -n checkout | head -5
   ```
   若最近 30m 有部署 → 可能是因。到步 2。
2. 回滚上次部署：
   ```bash
   kubectl rollout undo deploy/checkout -n checkout
   ```
   预期："deployment rolled back"
3. 若无最近部署 → 在服务图查下游依赖：
   https://grafana/d/servicemap?focus=checkout
   若依赖挂 → page 那队值班。

**验证：**
- 确认结账仪表盘错误率 <0.1% 持续 5m
- 确认 SLO 燃烧率 <1x

**升级：**
- 若回滚失败 → page payments-platform 副值班
- 若依赖健康且错误持续 → page @checkout-sme

常见问题

⚠散文墙非编号步骤 — 值班凌晨 3 点无法扫且瞎响应，更慢更险。
⚠无验证步 — 值班跑修复但不知何时停，故事件多留"调查中"20 分钟。
⚠runbook 在 Confluence 非 git — 静默腐、链接断、无人注意直到真实事件撞 404。
⚠症状用指标术语（"错误率 >1%"）非用户术语（"用户无法买"）— 值班不懂紧急度且欠响应。

最佳实践

✓每 runbook 用固定模板（症状、诊断、步骤、验证、升级）— 凌晨 3 点可扫且 20 分钟可写。
✓症状用用户术语（"用户无法买"）非指标术语；值班需影响非查询。
✓步骤编号带可复制粘贴命令和预期输出；无散文 — 值班执行非读散文。
✓runbook 存 git 稳定 URL 非 Confluence；从告警注解链接使 paging 系统在 page 中展示它。