anshikapundeel/incident-pilot
GitHub: anshikapundeel/incident-pilot
一个用 Go 编写的 AI 增强事件响应服务，通过确定性规则引擎关联 Alertmanager 告警与部署、日志、trace 数据，生成结构化事件报告。
Stars: 0 | Forks: 0
# incident-pilot
一个使用 Go 编写的 **AI 增强的事件响应服务**。它接收 Alertmanager 格式的告警，通过确定性的规则引擎将它们与最近的部署、日志和 trace 相关联，生成带有引用证据的结构化事件，并可选择使用本地配置的 LLM 进行重写。它将结果路由到 Slack（或 stdout）。
这是 [`ai-ops-design`](https://github.com/anshikapundeel/ai-ops-design) 中设计的可运行实现。
架构、故障模式、威胁模型和成本分析都在那里；这个仓库是将设计变为现实的 v0 代码。
```
Alertmanager webhook ──> incident-pilot ──> Slack / stdout
│
rule engine + LLM
│
(cited findings →
rephrased prose)
```
**纯 Go stdlib。零运行时依赖。不硬编码任何 API 密钥。**
## 为什么会有这个项目
当凌晨 3 点触发告警时，值班工程师需要知道三件事，顺序如下：
1. **刚刚发生了什么？**（一次部署、一次配置更改、某个依赖项的部分中断）
2. **是否已经有人在处理了？**（是否是某个未解决事件的重复项）
3. **最可能的修复方法是什么？**
incident-pilot 在告警信息到达之前就能回答这三个问题。它在分析过程中不使用 LLM（在时间紧迫的数据下，LLM 会对因果关系产生幻觉；请参阅 [llm-integration 设计文档](https://github.com/anshikapundeel/ai-ops-design/blob/main/docs/08-llm-integration.md)）。
分析是通过确定性的规则代码完成的。LLM（如果已配置）仅将规则输出重写为更自然的散文。
## 功能
- **兼容 Alertmanager 的 webhook**（位于 `POST /alerts`）。现有的 Prometheus 设置可以直接路由到它，无需进行任何更改。
- v0 版本包含 **5 条关联规则**：近期部署关联、错误日志激增聚类、trace 尾延迟、未解决重复事件检测、团队路由决策。
- **可插拔的富集** — 将部署 / trace / 日志推送到 `/context/*` endpoint；规则会在下一次告警时获取这些数据。
- **模板化叙述始终可用。** LLM 叙述是可选的，并且需要显式的环境变量才能启用。
- **Slack 输出**（通过 incoming webhook URL，由环境变量驱动；代码中无密钥）。
- **强制执行规则契约：** 每个发现都至少引用一条证据；损坏的规则会变成一个 LOW 级别的发现，而不是导致 pipeline 崩溃。
- 在并发摄取 + 查询期间**通过竞态检测器检查**。
## 构建并运行
需要 Go 1.22+。
```
git clone https://github.com/anshikapundeel/incident-pilot
cd incident-pilot
go build -o incident-pilot ./cmd/incident-pilot
./incident-pilot # listens on :9099
```
## 快速演示
在一个终端中：
```
./incident-pilot
```
在另一个终端中 — 记录一次部署，输入一些错误日志，然后触发告警：
```
# 告诉平台 3 分钟前发生了一次 deploy
curl -X POST localhost:9099/context/deploys -d '{
"service": "api-gateway",
"commit": "a39bf2c",
"author": "alice",
"when": "'$(date -u -d "3 minutes ago" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -v-3M +"%Y-%m-%dT%H:%M:%SZ")'"
}'
# 添加一些 error logs
for i in 1 2 3 4 5 6 7 8 9 10; do
curl -X POST localhost:9099/context/logs -d "{
\"service\":\"api-gateway\",\"level\":\"ERROR\",
\"message\":\"upstream timeout request $i\"
}"
done
# 触发 alert
curl -X POST localhost:9099/alerts \
-H 'Content-Type: application/json' \
-d @examples/sample_alert.json
# 查看结构化的 incident
curl -s "localhost:9099/api/incidents?limit=1" | jq .
```
在第一个终端中，你会看到模板化的事件报告出现，其中包含一个部署关联发现（HIGH 严重性，因为部署发生在告警前 3 分钟）和一个错误激增发现（MEDIUM，带有聚类的错误模式）。
## v0 中内置的规则
| 规则 ID | 捕获内容 |
|-------------------------------|----------------|
| `deploy.recent_corlated` | 告警发生在对同一服务的部署后不久。最强的单一信号。 |
| `logs.error_spike` | 告警服务有大量 ERROR 级别的日志行；通过聚类突出显示主要的错误模式。 |
| `traces.tail_latency` | 该服务近期 trace 的 p99 延迟超过阈值。 |
| `incident.duplicate_open` | 相同的指纹，或相同的服务+告警名称，已经有未解决的事件。防止告警风暴导致页面泛滥。 |
| `routing.team` | 将路由决策作为一个可见的发现展示出来，以便进行审计。 |
每条规则都位于 `internal/rules/` 中各自的文件中，大约是 100 行简单明了的 Go 代码。添加第六条规则只是一个很小的更改 — 请参阅 [ADDING_RULES.md](docs/ADDING_RULES.md)。
每个发现包含：
- `severity` (info / low / medium / high / critical)
- `confidence` (low / medium / high) — 与严重性正交
- `summary` — 一段话总结
- `suggestion` — 具体的下一步命令
- `evidence` — 指向触发它的数据
## API
| Endpoint | 用途 |
|----------|---------|
| `POST /alerts` | Alertmanager webhook（信封格式或裸告警） |
| `POST /context/deploys` | 记录部署事件 |
| `POST /context/traces` | 记录 trace 样本 (TraceID, service, duration) |
| `POST /context/logs` | 记录错误日志行 |
| `GET /api/incidents?limit=N` | 列出近期事件 |
| `GET /api/incidents/{id}` | 完整获取一个事件 |
| `POST /api/incidents/{id}/resolve` | 标记事件为已解决 |
| `GET /api/stats` | 计数器：告警输入、已开启事件等 |
| `GET /healthz` | 存活探针 |
## 可选的 LLM 叙述
incident-pilot **不包含任何 API 密钥、默认提供商，也不进行外部调用。** 它始终使用模板化叙述。要启用 LLM 重写层，请在启动前设置环境变量：
```
# 本地 Ollama（推荐用于数据敏感环境）：
export INCIDENT_PILOT_LLM_PROVIDER=ollama
export INCIDENT_PILOT_LLM_BASE_URL=http://localhost:11434
export INCIDENT_PILOT_LLM_MODEL=llama3.1:8b
./incident-pilot
# 或任何 OpenAI 兼容的 endpoint：
export INCIDENT_PILOT_LLM_PROVIDER=openai-compatible
export INCIDENT_PILOT_LLM_BASE_URL=https://your-endpoint.example.com
export INCIDENT_PILOT_LLM_MODEL=gpt-4o-mini
export INCIDENT_PILOT_LLM_API_KEY=YOUR_KEY
./incident-pilot
```
LLM **严格来说只是一个展示层**。系统提示明确禁止模型引入新的发现、更改严重性或捏造操作。结构化事件（权威数据）始终与叙述一起保留。
当 LLM 不可用或失败时，incident-pilot 会静默回退到模板化叙述。告警仍然会被路由。
有关此设计背后的完整原因，请参阅
[`ai-ops-design/docs/08-llm-integration.md`](https://github.com/anshikapundeel/ai-ops-design/blob/main/docs/08-llm-integration.md)。
## Slack 输出
将 `INCIDENT_PILOT_SLACK_WEBHOOK` 设置为 Slack 的 incoming-webhook URL：
```
export INCIDENT_PILOT_SLACK_WEBHOOK=https://hooks.slack.com/services/T.../B.../...
./incident-pilot
```
Slack sink 是在 stdout sink 之外添加的（而不是替代它）。如果你只想要 Slack 输出，请使用 `-quiet` 抑制 stdout。
## 这是什么以及不是什么
**是：**
- 一个完整、可运行的事件关联服务。只需放入环境，将 Alertmanager 指向 `/alerts`，将部署推送到 `/context/deploys`，每次触发时你都会得到结构化的事件报告。
- [ai-ops-design](https://github.com/anshikapundeel/ai-ops-design) 智能平面子系统的一个参考实现，特别是记录在 [docs/02-incident-pipeline.md](https://github.com/anshikapundeel/ai-ops-design/blob/main/docs/02-incident-pipeline.md) 中的事件 pipeline。
- 证明 AI 增强的事件响应可以使用确定性核心和 *可选的* LLM 层来构建，而不是使用会产生因果关系幻觉的 LLM 作为评判者。
**不是：**
- 一个存储后端。事件保存在内存中；重启后会丢失。生产环境部署应使用 Postgres 或类似技术作为存储后端。
- 一个告警管理器。使用 Prometheus Alertmanager（或其他任何工具）进行规则评估。incident-pilot 从 Alertmanager 交接的地方开始工作。
- 一个搜索引擎。未实现按内容查询过去的事件。完整设计通过向量检索涵盖了此功能（请参阅 ai-ops-design）；v0 中未包含。
- 一个完整的可观测性技术栈。将其与
[`flow-trace`](https://github.com/anshikapundeel/flow-trace)
用于 trace，
[`sched-trace`](https://github.com/anshikapundeel/sched-trace) 用于
内核遥测，
[`redfish-exporter`](https://github.com/anshikapundeel/redfish-exporter)
用于硬件事件，以及
[`perf-advisor`](https://github.com/anshikapundeel/perf-advisor) 用于
性能规则分析。
## 项目布局
```
internal/model/ Alert, Context, Finding, Incident — domain types
internal/correlate/ Rule engine: runs rules, enforces evidence contract
internal/rules/ Five v0 detection rules (one file each)
internal/store/ In-memory incident store, sync.RWMutex-guarded
internal/narrate/ Templated narration + optional LLM hook
internal/route/ Stdout + Slack delivery sinks
internal/server/ HTTP API (alerts, context, query endpoints)
cmd/incident-pilot/ Server binary
examples/ Sample alert + deploy JSON payloads
docs/ DESIGN.md, ADDING_RULES.md
```
## 测试
```
go test ./... # 27 tests, all green
go test -race ./... # also race-clean
```
CI matrix：Go 1.22 和 1.23，都带有 `-race` 标志，外加一个端到端冒烟测试，该测试向实时服务器触发告警并验证事件是否出现。
## 路线图
- [x] Alertmanager 格式摄取，裸告警回退
- [x] 带有引用证据的 5 条关联规则
- [x] 可选的 LLM hook（兼容 Ollama / OpenAI）
- [x] Slack + stdout 交付 sink
- [x] 内存存储 + REST 查询 API
- [x] 27 个单元 + e2e 测试，race-clean
- [ ] 过往事件检索（已解决事件的向量相似度）
- [ ] 基于 Postgres 的持久化存储
- [ ] 对 LLM 输出进行幻觉检查（声明 → 发现基础）
- [ ] PagerDuty / Opsgenie sink
- [ ] Prometheus `/metrics` endpoint
- [ ] 更多规则：cgroup OOM、leader-selection 抖动、依赖级联图
## License
MIT.
标签：AI风险缓解, EVTX分析, 日志审计