investigate-incident

调查事故技能

使用 Port 的服务目录数据进行系统性根因分析。

使用时机

• 事故已完成分诊，需要进一步调查
• 查找生产问题的根本原因
• 将部署与事故进行关联分析

调查流程

步骤 1：构建时间线

查询 Port，构建时间线：

1. 近期部署（过去 24 小时）：

   list_entities(blueprint="deployment", query={
     service: "affected-service",
     deployed_at: ">24h ago"
   })
   

2. 近期合并的 PR：

   list_entities(blueprint="pull_request", query={
     service: "affected-service",
     merged_at: ">24h ago"
   })
   

3. 配置变更（如有跟踪）：

   list_entities(blueprint="config_change", query={
     service: "affected-service"
   })
   

步骤 2：关联分析

检查事故发生时间是否与以下情况相关：

• 部署时间（最常见的原因）
• 流量激增
• 依赖项故障
• 配置变更

步骤 3：依赖项检查

查询服务依赖项：

get_entity(blueprint="service", identifier="affected-service", include=["depends_on"])

对于每个依赖项，检查：

• 健康状态
• 近期事故
• 错误率

步骤 4：历史模式匹配

查找过去的类似事故：

list_entities(blueprint="incident", query={
  primary_service: "affected-service",
  created_at: "<30d"
})

查找：

• 相同的错误模式
• 相同的时段
• 相同的触发条件

步骤 5：确定根本原因

记录：

1. 发生了什么变更：导致问题的具体变更
2. 为何失败：故障发生的机制
3. 为何未被发现：测试或审查中的缺口

步骤 6：更新事故

调用 update_incident_investigation 并传入：

• root_cause_summary
• related_deployment（如适用）
• related_pr（如适用）
• timeline_markdown
• investigation_notes

输出格式

# Root Cause Analysis: [Incident ID]

## Summary
[One paragraph explanation]

## Timeline
| Time | Event |
|------|-------|
| 14:15 | PR #123 merged |
| 14:20 | Deployment v2.3.4 completed |
| 14:23 | First error alerts |

## Root Cause
[Detailed technical explanation]

## Related Changes
- PR: #123 - "Add currency field"
- Deployment: v2.3.4

## Recommendations
1. [Specific actionable item]
2. [Specific actionable item]

质量检查清单

• 已构建完整时间线
• 已检查所有近期部署
• 已分析依赖项
• 已找到相关变更
• 已清晰记录根本原因