Runbook 发现

为什么

何时使用

如何做

1. 从告警链接 runbook（告警 → runbook）
   - 告警注解：runbook_url: "https://rb/checkout-slo-burn"
   - paging 系统（PagerDuty/Opsgenie）在 page 载荷中展示此
   - 这是主路径；值班首行动是开 runbook

2. 从仪表盘链接 runbook（仪表盘 → runbook）
   - Grafana 仪表盘头部："Runbook: checkout-slo-burn" 链接
   - 值班常从仪表盘开始非告警；在彼处迎它

3. 在服务目录列 runbook（目录 → runbook）
   - Backstage/内部目录：每服务页列其 runbook
   - 这是浏览路径 — 游戏日、审计和入职有用

4. 用稳定 URL 方案
   - https://rb/<告警名> 或 https://rb/<服务>/<场景>
   - URL 应可猜；链接缺时值班可构造它

5. 使 runbook 按症状可搜，非仅告警名
   - "结账错误率高" 应找到 SLO 燃烧 runbook
   - 用用户可见症状标签 runbook，非仅内部告警名

示例

# 告警规则（Prometheus）— runbook_url 注解
- alert: CheckoutSLOBurnRateFast
  expr: ...
  annotations:
    runbook_url: "https://rb/checkout-slo-burn"
    dashboard: "https://grafana/d/checkout"

# Grafana 仪表盘 — 头部 runbook 链接
# （仪表盘 JSON）：
"links": [
  { "title": "Runbook: SLO burn", "url": "https://rb/checkout-slo-burn", "type": "link" },
  { "title": "Alert: CheckoutSLOBurnRateFast", "url": "...", "type": "link" }
]

# 服务目录（Backstage）— 每服务 runbook
# catalog-info.yaml：
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout
  links:
    - url: https://rb/checkout-slo-burn
      title: "Runbook: SLO burn"
    - url: https://rb/checkout-db-failover
      title: "Runbook: DB failover"

# 值班体验：告警触发 → page 含 runbook_url → 一击 → runbook 开。
# 若从仪表盘开始 → 头部"Runbook"链接 → 同 URL。
# 若浏览目录 → checkout 页 → 列 runbook。

常见问题

• ⚠runbook 仅从告警链接 — 若值班从仪表盘开始（常见），找不到且重发明响应。
• ⚠runbook URL 是页移动即变的 Confluence 深链 — 告警链接静默 404 无人注意。
• ⚠runbook 仅按告警名标签 — 搜"结账错误率高"找不到因 runbook 标"CheckoutSLOBurnRateFast"。
• ⚠无服务目录 — runbook 散布仓和 wiki 故浏览路径（游戏日和审计有用）不存在。

最佳实践

• ✓接全三发现路径：告警注解（runbook_url）、仪表盘头部链接、服务目录列 — 在值班所在处迎它。
• ✓用稳定可猜 URL 方案（https://rb/<告警名>）存 git 非 Confluence 移即腐的链接。
• ✓用用户可见症状（"结账错误率高"）标签 runbook 非仅告警名使搜从值班心智模型工作。
• ✓在服务目录（Backstage）按服务列 runbook 使浏览路径存在供游戏日、审计和入职。