GreenerPlatform/incident-triage
GitHub: GreenerPlatform/incident-triage
一款基于 Python 标准库的确定性 Kubernetes 故障分诊工具，通过分析集群快照与告警自动生成因果链和修复方案。
Stars: 0 | Forks: 0
## 为什么故障分诊耗时如此之长
当你的值班告警触发时——无论是 PagerDuty、Alertmanager、Opsgenie、Grafana 还是
普通的 webhook——你得到的往往只是表象，而非原因。你打开 dashboard，接着是
kubectl，然后是聊天记录和 runbooks。等你大致理清头绪时，20
分钟已经过去了。
```
incident-triage \
--sentinel-json snap.json \
--alert "payments API 503 since 14:30"
```
```
{
"confidence": "high",
"what_changed": {
"detected": true,
"summary": "Likely trigger: deploy/rollout change — a new build is crashing on startup; first seen 2 min before the alert (Pod payments/api-gateway).",
"trigger": { "change_type": "deploy/rollout change", "reason": "BackOff", "seconds_before_alert": 135 }
},
"causation_chain": [
{ "label": "root_cause", "description": "Pod payments/api-gateway CrashLoopBackOff (restarts: 47)" },
{ "label": "intermediate", "description": "Deployment payments/api-gateway — 0/3 replicas available" },
{ "label": "symptom", "description": "payments API 503 since 14:30" },
{ "label": "alert", "description": "Alert triggered: payments API 503 since 14:30" }
],
"fix_plan": {
"p1": {
"action": "Restart the crashing deployment",
"command": "kubectl rollout restart deploy/api-gateway -n payments"
},
"p2": {
"action": "Watch pods return to Running state",
"command": "kubectl get pods -n payments -w"
},
"p3": { "action": "Investigate why CrashLoopBackOff is recurring" }
}
}
```
## 安装
```
# pipx（推荐 — 隔离，在您的 PATH 上）
pipx install incident-triage
# 或 pip
pip install incident-triage
# 或从源码安装，无需打包
git clone https://github.com/GreenerPlatform/incident-triage
cd incident-triage && bash install.sh /usr/local/bin
```
**要求：** Python 3.10+ · 仅需标准库 · 零运行时依赖
## 用法
```
# 从文件进行完整 triage
incident-triage --sentinel-json report.json --alert alert.json
# 自由文本 alert
incident-triage --sentinel-json report.json --alert "payments API 503 since 14:30"
# 快照模式（无需集群访问）
incident-triage --sentinel-json snap.json --alert pd-alert.json
# 当无法从 alert 确定时覆盖 namespace
incident-triage --sentinel-json report.json --alert "service down" --namespace payments
# HTML 报告
incident-triage --sentinel-json snap.json --alert alert.json --output-format html > report.html
```
## Flags
| Flag | 描述 |
|------|-------------|
| `--sentinel-json
` | sentinel JSON 快照的路径（kubectl-sentinel --json 输出） |
| `--alert ` | 告警：自由文本或告警描述符 JSON 的路径 |
| `--namespace ` | 当无法从告警中确定 namespace 时，覆盖默认 namespace |
| `--output-format json\|html` | 输出格式（默认：json） |
## 告警描述符 JSON
当 `--alert` 指向某个 JSON 文件时，它将被解析为告警描述符：
```
{
"alert_source": "pagerduty | alertmanager | opsgenie | grafana | webhook | freetext",
"alert_name": "payments SLO breach — availability < 99.5%",
"service": "api-gateway",
"namespace": "payments",
"severity": "critical",
"start_time": "2026-04-11T14:30:00Z"
}
```
也支持自由文本——服务名称、namespace 和时间戳将通过 regex 提取。
## 退出码
| 代码 | 何时触发 |
|------|------|
| `0` | 分诊完成——有效输出 |
| `1` | 未知 namespace |
| `2` | sentinel 快照缺失或无效 |
| `3` | 没有匹配告警的 sentinel 发现——生成了低置信度输出 |
## 工作原理
1. **分类 (Classify)** — 告警文本将匹配到 12 种告警类型之一（SLO burn、CrashLoop、OOMKill 等）
2. **优先级排序 (Prioritise)** — sentinel 部分根据与告警类型的相关性进行排名
3. **评分 (Score)** — 每个发现被归类为 `direct`、`contributing`、`parallel` 或 `background`。长期存在的隐患（缺少 limits/probes、node 内存 %）始终归为 background。
4. **串联成链 (Chain)** — 主要的直接发现（优先级最高的部分）即为根本原因；只有具有共享资源沿袭的下游发现才会成为中间步骤。不相关的 CRITICAL 问题会进入 `parallel_findings`。
5. **变更分析 (What changed)** — 将事件时间戳与告警开始时间进行关联，以揭示*可能的触发因素*（例如：“在告警发生前 2 分钟，一个新的构建开始崩溃”），并对变更类型进行分类——配置、镜像、rollout、资源、调度、配额或探针/健康检查
6. **方案 (Plan)** — 修复命令来自 sentinel 的 `recommendation` 字段（一条完整的 kubectl 命令）
不涉及 LLM 调用。不需要网络访问。相同的输入会生成确定性的输出——包括 `what_changed`，这纯粹是对快照数据进行的纯时间相关性分析。
分类是**容忍词干变化且基于评分的**，而不是简单的字面首次匹配：“restart” 也能匹配
“restarts”/“restarting”，数字代码作为整个单词进行匹配，最终得分最高的类型胜出。如果
类型无法确定，分诊工具会如实退回到“根本原因不明”的状态，而不是盲目猜测——
它绝不会仅仅基于 namespace 巧合就断定根本原因。
### 扩展告警分类（无需修改代码）
不同团队和工具的告警词汇表各不相同。无需 fork 代码即可教授分类器你自己的词汇表：
```
export INCIDENT_TRIAGE_ALERT_TYPES=~/my-alert-types.json # or ~/.config/incident-triage/alert-types.json
```
```
{ "crash_loop": ["flapping", "bouncing"], "high_error_rate": ["sev1 5xx", "edge errors"] }
```
你的 keywords 将被**追加**到内置映射中（默认设置永远不会被移除）。要引导*新*
告警类型的相关性分析，还需将其添加到 `SECTION_PRIORITY` 中；否则它将使用 `unknown` 优先级。
## 冒烟测试
```
python3 incident_triage.py \
--sentinel-json tests/fixtures/sample-report.json \
--alert tests/fixtures/sample-alert.json \
| python3 -m json.tool
```
`tests/fixtures/` 包含了一个最小化的 sentinel 快照（CRITICAL：payments namespace 中的 CrashLoopBackOff）以及一个匹配的告警描述符。
## 输出 schema
有关完整的分诊输出 JSON schema，请参见 [schema.md](schema.md)。
## 获取集群状态
`incident-triage` 读取 sentinel JSON 快照。使用
[kubectl-sentinel](https://github.com/GreenerPlatform/kubectl-sentinel) 来收集快照：
```
# 安装 kubectl-sentinel（需要 kubectl + jq）
git clone https://github.com/GreenerPlatform/kubectl-sentinel
cd kubectl-sentinel && bash install.sh ~/bin && cd -
# 在一个 pipeline 中收集集群状态并进行 triage
kubectl sentinel --json -n payments > snap.json
incident-triage --sentinel-json snap.json --alert "payments API 503 since 14:30"
```
kubectl-sentinel 运行 15 个健康维度并输出结构化的 JSON。
其 `recommendation` 字段直接作为分诊输出中的修复命令。
## 从 AI agent 使用（任何 runtime）
该工具是一个简单的 CLI，采用 JSON 输入/输出，因此任何 agent 都可以驱动它。有两种途径：
**1. MCP server（推荐，与供应商无关）。** [GreenerPlatform MCP server](https://github.com/GreenerPlatform)
将 `sentinel` 和 `triage` 作为工具暴露给任何支持 MCP 的客户端——Cursor、Claude Desktop、
VS Code、Windsurf 或自定义 agent。只需安装一次；即可在任何地方使用。
**2. 参考 agent 技能。** [`skills/SKILL.md`](skills/SKILL.md) 是一个参考推理层
集成（Claude Code 命令 + 可选的 PagerDuty 富化阶段）。将其复制到你的
agent 的命令目录中，并根据你的技术栈调整告警/通知提供商：
```
cp skills/SKILL.md /path/to/your-project/.claude/commands/triage.md
```
```
/triage payments API returning 503 since 14:30
/triage --sentinel-json snap.json --alert "payments API 503"
```
## 双层模式
incident-triage 是确定性层：告警 → 集群状态 → 因果链，在单次
过程中完成。agent（通过 MCP 或参考技能）则是推理层：它运行 sentinel，
将输出输入到该工具，然后添加来自你的故障历史记录和 playbook 的上下文。
agent 受限于证据——它是基于 CLI 所确立的事实进行推理，而非盲目猜测。
## 贡献
欢迎提交 Issues 和 pull requests。请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
设计原则：在提出建议之前先进行分类。OOMKill 并不总是意味着“提高 limit”——
根本原因（limit 太低 vs. 内存泄漏 vs. 输入激增）才能决定正确的修复方案。标签：Pandas, Python, 告警分析, 子域名突变, 故障排查, 无后门, 特征库, 自动化分析, 跨站脚本, 运维, 逆向工具
