Skills-SI市场
skills-si.com
提交技能
/
界面已本地化；技能介绍与说明文档按所选语言由 AI 自动翻译，代码、命令、路径和专业术语保留原文，以原作者文档为准。
探索技能
效率与协作 · SKILL.md

write-incident-runbook

write-incident-runbook

【效率与协作】创建包含诊断步骤、解决流程、升级路径和通信模板的结构化事故运行手册， 用于有效的事故响应。适用于为反复出现的告警记录响应流程、 在值班轮换中标准化事故响应、通过清晰的诊断步骤缩短 MTTR、 为新团队成员创建培训材料，或将告警注解直接链接到解决流程。

独立 GitHub 快照 · 自动分类 · 以原作者文档为准

Ppjt222 / agent-almanacMIT

技能说明

GitHub

name: write-incident-runbook description: > 创建包含诊断步骤、解决流程、升级路径和通信模板的结构化事故运行手册， 用于有效的事故响应。适用于为反复出现的告警记录响应流程、 在值班轮换中标准化事故响应、通过清晰的诊断步骤缩短 MTTR、 为新团队成员创建培训材料，或将告警注解直接链接到解决流程。 locale: zh-CN source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: observability complexity: basic language: multi tags: runbook, incident-response, diagnostics, escalation, documentation

Write Incident Runbook

创建可操作的运行手册，引导响应人员完成事故诊断和解决。

适用场景

  • 为反复出现的告警或事故记录响应流程
  • 在值班轮换成员中标准化事故响应
  • 通过清晰的诊断步骤缩短平均修复时间（MTTR）
  • 为新团队成员创建事故处理培训材料
  • 建立升级路径和通信协议
  • 将部落知识迁移到书面文档
  • 将告警链接到解决流程（告警注解）

输入

  • 必填：事故或告警名称/描述
  • 必填：历史事故数据和解决模式
  • 可选：诊断查询（Prometheus、日志、追踪）
  • 可选：升级联系人和通信渠道
  • 可选：以前的事故复盘

步骤

第 1 步：选择运行手册模板结构

完整模板文件请参阅 Extended Examples。

根据事故类型和复杂程度选择合适的模板。

基础运行手册模板结构：

# [Alert/Incident Name] Runbook
## Overview | Severity | Symptoms
## Diagnostic Steps | Resolution Steps
## Escalation | Communication | Prevention | Related

高级 SRE 运行手册模板（摘录）：

# [Service Name] - [Incident Type] Runbook

## Metadata
- Service, Owner, Severity, On-Call, Last Updated

## Diagnostic Phase
### Quick Health Check (< 5 min): Dashboard, error rate, deployments
### Detailed Investigation (5-20 min): Metrics, logs, traces, failure patterns
# ... (see EXAMPLES.md for complete template)

关键模板组件：

  • 元数据：服务所有权、严重程度、值班轮换
  • 诊断阶段：快速检查 → 详细调查 → 故障模式
  • 解决阶段：立即缓解 → 根因修复 → 验证
  • 升级：标准和联系路径
  • 通信：内部/外部模板
  • 预防：短期/长期行动

预期结果： 所选模板与事故复杂程度匹配，章节适合服务类型。

失败处理：

  • 从基础模板开始，根据事故模式迭代
  • 查阅行业示例（Google SRE 书籍、供应商运行手册）
  • 根据首次使用后的团队反馈调整模板

第 2 步：记录诊断流程

完整的诊断查询和决策树请参阅 Extended Examples。

创建带有具体查询的逐步调查流程。

六步诊断清单：

  1. 验证服务健康状态：健康端点检查和正常运行时间指标

    curl -I https://api.example.com/health  # Expected: HTTP 200 OK

    up{job="api-service"}  # Expected: 1 for all instances

  2. 检查错误率：当前错误百分比及按端点分解

    sum(rate(http_requests_total{status=~"5.."}[5m]))
/ sum(rate(http_requests_total[5m])) * 100  # Expected: < 1%

  3. 分析日志：来自 Loki 的近期错误和主要错误消息

    {job="api-service"} |= "error" | json | level="error"

  4. 检查资源利用率：CPU、内存和连接池状态

    avg(rate(container_cpu_usage_seconds_total{pod=~"api-service.*"}[5m])) * 100
# Expected: < 70%

  5. 审查近期变更：部署、git 提交、基础设施变更

  6. 检查依赖项：下游服务健康状态、数据库/API 延迟

故障模式决策树（摘录）：

  • 服务下线？→ 检查所有 Pod/实例
  • 错误率升高？→ 检查特定错误类型（5xx、网关、数据库、超时）
  • 何时开始？→ 部署后（回滚）、逐渐增加（资源泄漏）、突然发生（流量/依赖）

预期结果： 诊断流程具体，包含预期值与实际值对比，引导响应人员完成调查。

失败处理：

  • 在记录前在实际监控系统中测试查询
  • 为视觉参考添加仪表板截图
  • 为频繁遗漏的步骤添加"常见错误"部分
  • 根据事故响应人员的反馈迭代

第 3 步：定义解决流程

完整命令和回滚流程的所有 5 个解决选项请参阅 Extended Examples。

记录带有回滚选项的逐步修复流程。

五种解决选项（简要摘要）：

  1. 回滚部署（最快）：针对部署后的错误

    kubectl rollout undo deployment/api-service

    验证 → 监控 → 确认解决（错误率 < 1%、延迟正常、无告警）

  2. 扩容资源：针对高 CPU/内存、连接池耗尽

    kubectl scale deployment/api-service --replicas=$((current * 3/2))

  3. 重启服务：针对内存泄漏、连接卡死、缓存损坏

    kubectl rollout restart deployment/api-service

  4. 功能标志/熔断器：针对特定功能错误或外部依赖故障

    kubectl set env deployment/api-service FEATURE_NAME=false

  5. 数据库修复：针对数据库连接、慢查询、连接池耗尽

    -- Kill long-running queries, restart connection pool, increase pool size

通用验证清单：

  • 错误率 < 1%
  • 延迟 P99 < 阈值
  • 吞吐量达到基准
  • 资源使用健康（CPU < 70%，内存 < 80%）
  • 依赖项健康
  • 面向用户的测试通过
  • 无活跃告警

回滚流程：如果解决措施使情况恶化 → 暂停/取消 → 还原 → 重新评估

预期结果： 解决步骤清晰，包含验证检查，为每个操作提供回滚选项。

失败处理：

  • 为复杂流程添加更细粒度的步骤
  • 为多步骤流程添加截图或图表
  • 记录命令输出（预期值与实际值）
  • 为复杂解决流程创建单独的运行手册

第 4 步：建立升级路径

完整升级级别和联系目录模板请参阅 Extended Examples。

定义何时以及如何升级事故。

立即升级的情况：

  • 面向客户的中断超过 15 分钟
  • SLO 错误预算消耗 > 10%
  • 疑似数据丢失/损坏或安全漏洞
  • 20 分钟内无法识别根因
  • 缓解尝试失败或使情况恶化

五个升级级别：

  1. 主要值班人员（5 分钟响应）：部署修复、回滚、扩容（单独处理最多 30 分钟）
  2. 次要值班人员（15 分钟后自动）：额外的调查支持
  3. 团队负责人（架构决策）：数据库变更、供应商升级、超过 1 小时的事故
  4. 事故指挥官（跨团队协调）：多团队、客户沟通、超过 2 小时的事故
  5. 高管（C 级）：重大影响（>50% 用户）、SLA 违约、媒体/PR、超过 4 小时的中断

升级流程：

  1. 通知目标并提供：当前状态、影响、已采取的行动、需要的帮助、仪表板链接
  2. 如有需要交接：共享时间线、行动、访问权限、保持可用
  3. 不要沉默：每 15 分钟更新一次，提问，提供反馈

联系目录：维护包含角色、Slack、电话、PagerDuty 的表格，涵盖：

  • 平台/数据库/安全/网络团队
  • 事故指挥官
  • 外部供应商（AWS、数据库供应商、CDN 提供商）

预期结果： 升级标准清晰，联系信息易于获取，升级路径与组织结构一致。

失败处理：

  • 验证联系信息是最新的（每季度测试）
  • 为何时升级添加决策树
  • 包含升级消息示例
  • 记录每个级别的响应时间期望

第 5 步：创建通信模板

包含完整格式的所有内部和外部模板请参阅 Extended Examples。

提供预先编写的事故更新消息。

内部模板（Slack #incident-response）：

  1. 初始声明：

    🚨 INCIDENT: [Title] | Severity: [Critical/High/Medium]
Impact: [users/services] | Owner: @username | Dashboard: [link]
Quick Summary: [1-2 sentences] | Next update: 15 min

  2. 进展更新（每 15-30 分钟）：

    📊 UPDATE #N | Status: [Investigating/Mitigating/Monitoring]
Actions: [what we tried and outcomes]
Theory: [what we think is happening]
Next: [planned actions]

  3. 缓解完成：

    ✅ MITIGATION | Metrics: Error [before→after], Latency [before→after]
Root Cause: [brief or "investigating"] | Monitoring 30min before resolved

  4. 解决：

    🎉 RESOLVED | Duration: [time] | Root Cause + Impact + Follow-up actions

  5. 误报：无影响，无需跟进

外部模板（状态页面）：

  • 初始：正在调查，开始时间，15 分钟后下次更新
  • 进展：已识别原因（面向客户的语言），正在实施修复，预计解决时间
  • 解决：解决时间、根因（简单语言）、持续时间、预防措施

客户邮件模板：时间线、影响描述、解决方案、预防措施、赔偿（如适用）

预期结果： 模板在事故期间节省时间，确保通信一致，减少响应人员的认知负担。

失败处理：

  • 根据公司通信风格定制模板
  • 用常见事故类型预填充模板
  • 创建 Slack 工作流/机器人自动填充模板
  • 在事故回顾期间审查模板

第 6 步：将运行手册链接到监控

完整的 Prometheus 告警配置和 Grafana 仪表板 JSON 请参阅 Extended Examples。

将运行手册与告警和仪表板集成。

向 Prometheus 告警添加运行手册链接：

- alert: HighErrorRate
  annotations:
    runbook_url: "https://wiki.example.com/runbooks/high-error-rate"
    dashboard_url: "https://grafana.example.com/d/service-overview"
    incident_channel: "#incident-platform"

在运行手册中嵌入快速诊断链接：

  • 服务概览仪表板
  • 过去 1 小时错误率（Prometheus 直接链接）
  • 近期错误日志（Loki/Grafana Explore）
  • 近期部署（GitHub/CI）
  • PagerDuty 事故

创建 Grafana 仪表板面板，包含运行手册链接（markdown 面板，列出所有事故运行手册及值班和升级信息）

预期结果： 响应人员可直接从告警或仪表板访问运行手册，诊断查询预填充，一键访问相关工具。

失败处理：

  • 验证运行手册 URL 无需 VPN/登录即可访问
  • 为复杂的 Grafana/Prometheus 链接使用短链接
  • 每季度测试链接确保不失效
  • 为常用运行手册创建浏览器书签

验证清单

  • 运行手册遵循一致的模板结构
  • 诊断流程包含具体查询和预期值
  • 解决步骤可操作，包含清晰的命令
  • 升级标准和联系信息是最新的
  • 为内部和外部受众提供通信模板
  • 运行手册从监控告警和仪表板链接
  • 运行手册在事故演练或实际事故中测试过
  • 响应人员的反馈已纳入运行手册
  • 修订历史以日期和作者追踪
  • 运行手册无需身份验证即可访问（或离线缓存）

常见问题

  • 过于笼统：包含"检查日志"等模糊步骤但没有具体查询的运行手册不可操作。要具体。
  • 信息过时：引用旧系统或命令的运行手册变得无用。每季度审查。
  • 没有验证步骤：没有验证的解决方案会导致误报。始终包含"如何确认已修复"。
  • 缺少回滚流程：每个操作都应有回滚计划。不要让响应人员陷入更糟糕的状态。
  • 假设知识：只面向专家的运行手册排除了初级工程师。为轮换中经验最少的人编写。
  • 没有所有者：没有所有者的运行手册会变得陈旧。分配负责更新的团队/人员。
  • 隐藏在认证后面：在 VPN/SSO 问题期间无法访问的运行手册在危机期间无用。缓存副本或使用公共 wiki。

相关技能

  • configure-alerting-rules - 将运行手册链接到告警注解以在事故期间立即访问
  • build-grafana-dashboards - 在仪表板和诊断面板中嵌入运行手册链接
  • setup-prometheus-monitoring - 在运行手册流程中包含来自 Prometheus 的诊断查询
  • define-slo-sli-sla - 在事故严重程度分类中引用 SLO 影响

发现更多相关技能

查看全部技能
我的收藏