nithish-kumar-t/incident-response-agent
GitHub: nithish-kumar-t/incident-response-agent
这是一个AI辅助的事件响应系统，用于自动收集监控数据并生成故障分析报告，帮助工程师快速定位和修复生产环境问题。
Stars: 0 | Forks: 0
# 事件响应代理
一个用于本地微服务的 AI 辅助事件响应系统。
该项目将应用程序遥测数据、警报、日志和 LLM 分析整合到一个事件工作流中。该代理自动收集第一层上下文并生成结构化的事件摘要，而不是让值班工程师在 Prometheus、Loki、服务日志和源代码之间来回切换。
## 灵感
生产环境的中断令人压力巨大，因为答案很少集中在一个地方。指标存放在 Prometheus，日志在另一个系统，部署上下文可能在 Git 中，而值班工程师仍需在压力下将线索串联起来。
本项目围绕一个问题而构建：
目标不是取代工程师。目标是为他们提供一个有用的初稿：是什么触发了警报，什么发生了变化，存在什么证据，可能的原因是什么，以及接下来该检查什么。
## 功能
事件响应代理监控演示服务，并在 Prometheus 检测到事件时作出反应。
当出现服务宕机、MongoDB 依赖失败或 5xx 错误上升等问题时：
1. Prometheus 评估警报规则。
2. Alertmanager 向 `incident-agent-workflow` 发送 webhook。
3. 代理查询 Prometheus 获取实时指标。
4. 代理查询 Loki 获取受影响服务的近期日志。
5. 代理将结构化上下文发送到本地 Ollama 模型。
6. 分析结果被记录，供 Grafana、调试和后续跟进使用。
7. 通知器发送结构化的事件邮件。
8. 更深层的 GPT 代理流水线调查日志和源代码。
9. 修复流程会打开一个草稿 GitHub Pull Request 供人工审核。
为了进行更深入的调查，该仓库还在 `apps/agent/` 下包含一个运行在主机上的 3 代理 OpenAI 流水线：
| 代理 | 角色 | 职责 |
| --- | --- | --- |
| 代理 1 | 分诊与服务解决 | 识别受影响的服务并解决服务配置问题 |
| 代理 2 | 调查 | 运行健康检查、扫描日志并提取堆栈跟踪信息 |
| 代理 3 | 根因分析 | 读取相关文件/行位置附近的源代码上下文并建议修复方案 |
默认的 Docker 演示从本地 Ollama 工作流开始。更深层的 OpenAI 流水线单独在主机上运行，负责源码级别的调查和草稿 PR 生成。
## 系统设计
```
---
config:
theme: mc
---
sequenceDiagram
autonumber
participant U as Service
participant P as Prometheus
participant A as Alertmanager
participant AI as AI Agent
participant N as Notifier
participant G as GitHub
U--xP: Service crashes
P->>P: up == 0 for 30s
P->>A: Alert fires
A->>AI: POST /alerts (webhook)
AI->>P: Pull metrics
AI->>AI: Pull recent logs from Loki
AI->>AI: Ollama analyzes
AI->>N: Send incident email
AI->>AI: Deep-dive (3 GPT agents)
AI->>G: Open draft PR with fix
Note over U,G: Human reviews PR, merges, incident resolved
```
### 设计流程
1. **一个服务发生故障**
被监控的服务崩溃、无法访问或开始返回错误。每个服务都暴露 `/metrics` 端点，并将日志写入 `apps//logs/` 下。
2. **Prometheus 检测到中断**
Prometheus 根据 `monitoring/targets.docker.yml` 抓取目标。当 `up == 0` 持续 30 秒，或 `monitoring/alert-rules.yml` 中的其他规则触发时，事件开始。
3. **Alertmanager 调用 AI 代理**
当规则触发时，Alertmanager 将一个兼容 Alertmanager 的载荷发送到：
http://incident-agent-workflow:9100/alerts
4. **代理收集上下文**
该工作流查询 Prometheus 获取服务健康和 5xx 频率，然后使用警报中相同的 `service` 标签查询 Loki 获取近期日志。
5. **Ollama 生成首个事件摘要**
当前 Docker 工作流使用 `mistral-nemo` 将上下文发送到运行在主机 `host.docker.internal:11434` 上的 Ollama。
6. **通知器发送事件邮件**
通知器接收结构化的事件结果，并发送一封包含警报、服务、摘要和 AI 分析的邮件。
7. **GPT 流水线进行深度调查**
3 代理流水线解决服务问题、检查健康状况、扫描日志、提取堆栈跟踪，并读取可能故障点附近的源代码上下文。
8. **GitHub 收到草稿 PR**
当调查找到具体的修复方案时，系统会打开一个草稿 GitHub Pull Request，以便人工在合并前审核修复。
9. **人类保持控制**
PR 默认为草稿状态。工程师审核证据、测试和差异，在同意修复后再合并并解决事件。
## 代理式调查与 Git 流程
此图展示了深度调查流水线如何将事件分解为代理职责，以及 Git/源代码工具如何融入草稿修复路径。
```
flowchart LR
%% Input
IN([Incident Alert])
%% Agents
subgraph PIPELINE["AI Investigation Pipeline"]
direction LR
A1["Agent 1
Triage & Service Resolution"] A2["Agent 2
Log Investigation"] A3["Agent 3
Root Cause Analysis"] end %% Output OUT([Analysis Result
+ Draft Fix]) %% External tools REG[("service_registry.json")] TOOLS["Health + Log Tools"] GIT["Git / Source Tools"] %% Main flow IN --> A1 A1 --> A2 A2 --> A3 A3 --> OUT %% Tool usage A1 -. resolve services .-> REG A2 -. inspect logs & health .-> TOOLS A3 -. analyze source code .-> GIT %% Styling style PIPELINE fill:#eef4ff,stroke:#4a78c2,stroke-width:2px style A1 fill:#dbeafe,stroke:#2563eb,stroke-width:2px style A2 fill:#e0f2fe,stroke:#0284c7,stroke-width:2px style A3 fill:#ede9fe,stroke:#7c3aed,stroke-width:2px style OUT fill:#dcfce7,stroke:#16a34a,stroke-width:2px style IN fill:#fee2e2,stroke:#dc2626,stroke-width:2px style REG fill:#f8fafc,stroke:#64748b style TOOLS fill:#f8fafc,stroke:#64748b style GIT fill:#f8fafc,stroke:#64748b ``` 1. **代理 1 解决服务问题** 流水线从事件警报开始，使用 `service_registry.json` 将服务名称映射到健康检查 URL、日志路径、仓库路径以及语言/运行时上下文。 2. **代理 2 调查运行时证据** 第二个代理检查服务健康状况、读取相关日志、搜索错误，并提取解释故障原因的堆栈跟踪或请求上下文。 3. **代理 3 检查源代码** 最后一个代理使用 Git/源代码工具检查与堆栈跟踪或错误上下文相关的文件和行范围。这是流水线从“什么故障”转向“此代码为何可能故障”的环节。 4. **输出成为草稿修复** 结果包括根因分析、支持证据和一个建议的代码更改。这个建议的修复方案将输入到 GitHub 草稿 PR 流程，供人工审核。 有关两种 AI 路径的详细图表，请参阅 [architecture.md](architecture.md)。 ## 如何构建 完整的本地环境通过 Docker Compose 编排。 ### 应用层 - `weather-app1`：运行在端口 `8000` 的 FastAPI 天气服务 - `mongo-api-service`：运行在端口 `9000` 的 FastAPI CRUD 服务，后端为 MongoDB - 通过 `prometheus-fastapi-instrumentator` 提供 Prometheus `/metrics` 端点 - 基于文件的日志挂载到 Promtail ### 可观测性技术栈 - Prometheus：用于指标抓取和警报规则 - Alertmanager：用于警报分组和 webhook 分发 - Promtail 和 Loki：用于日志聚合 - Grafana：用于探索指标和日志 ### 警报工作流 - `incident-agent-workflow` 接收 `POST /alerts` - 它查询 Prometheus 获取 `up` 和 5xx 频率信号 - 它查询 Loki 获取服务的近期日志 - 它构建一个结构化的事件上下文对象 - 它将该上下文发送到 Ollama - 它将生成的分析记录为 `ollama_analysis` - 它将结果发送给通知器，用于事件邮件递送 - 它可以将复杂事件移交给 3 代理深度调查流水线 ### 通知系统 该仓库在 `apps/notifier/` 下包含一个 FastAPI 通知服务。 - 已实现 SMTP 邮件支持。 - 工作流将事件结果发布到 `/notify`。 - 邮件包含受影响的服务、警报名称、摘要和 AI 分析。 - 可以使用本地演示邮件工具（如 Mailpit），只需将通知器的 SMTP 设置指向该本地 SMTP 服务器。 ### 深度调查流水线 运行在主机上的 `apps/agent/` 流水线使用 OpenAI 和确定性工具进行： - 服务配置解决 - 健康检查 - 日志扫描 - 堆栈跟踪提取 - 通过 Git 命令检查源文件 ### 草稿 PR 自动化 深度调查代理确定可靠的修复方案后，修复流程会创建一个最小补丁并打开一个草稿 GitHub Pull Request。PR 保持草稿状态，以便工程师检查证据、审核代码、运行测试，并只在同意修复时才合并。 ### 报告 该仓库包含用于演示和事后分析工件的报告工具： - `apps/log_watcher.py` - `apps/monitor_service.py` - `apps/report_generator.py` 生成的报告写入 `apps/reports/` 目录下。 ## 仓库结构 ``` . |-- docker-compose.yml |-- architecture.md |-- README.md |-- apps/ | |-- weather-app1/ | |-- mongo-api-service/ | |-- incident-agent-workflow/ | |-- agent/ | |-- notifier/ | |-- log_watcher.py | |-- monitor_service.py | `-- report_generator.py `-- monitoring/ |-- prometheus.yml |-- targets.docker.yml |-- alert-rules.yml |-- alertmanager.yml |-- loki-config.yml |-- promtail-config.yml `-- grafana/provisioning/ ``` ## 本地运行 ### 前置条件 - Docker 和 Docker Compose - 主机上运行 Ollama - 本地拉取 `mistral-nemo` 模型 ``` ollama pull mistral-nemo ollama serve ``` 如果 Ollama 已经运行，`ollama serve` 可能会报告端口被占用。这没有关系。 ### 配置 Mongo API 创建 `apps/mongo-api-service/.env`： ``` cat > apps/mongo-api-service/.env <<'EOF' MONGO_URI=mongodb://mongo:27017 MONGO_DB=servicedb APP_NAME=Mongo API Service LOG_FILE=/app/logs/service.log EOF ``` ### 启动技术栈 ``` docker compose up -d --build ``` 检查状态： ``` docker compose ps ``` 停止技术栈： ``` docker compose down ``` ## 服务 URL | 服务 | URL | | --- | --- | | Weather API | http://localhost:8000 | | Mongo API | http://localhost:9000 | | 事件工作流 | http://localhost:9100 | | Prometheus | http://localhost:9090 | | Alertmanager | http://localhost:9093 | | Grafana | http://localhost:3000 | | Loki | http://localhost:3100 | | MongoDB | `localhost:27017` | Grafana 凭据为 `admin` / `admin`。 ## 验证演示 检查服务健康状况： ``` curl http://localhost:8000/ curl http://localhost:9000/health curl http://localhost:9100/health ``` 检查 Prometheus 目标： ``` http://localhost:9090/targets ``` 创建 Mongo 条目： ``` curl -X POST http://localhost:9000/items/ \ -H "Content-Type: application/json" \ -d '{"name":"demo","description":"test item","value":42}' ``` 查询天气服务： ``` curl "http://localhost:8000/weather/latitude=41.8781&longitude=-87.6298" ``` 手动触发测试警报： ``` curl -X POST http://localhost:9100/alerts \ -H "Content-Type: application/json" \ -d '{ "alerts": [ { "status": "firing", "labels": { "alertname": "ServiceDown", "service": "weather-app1" }, "annotations": { "summary": "weather-app1 is not responding" } } ] }' ``` 查看事件分析： ``` docker compose logs -f incident-agent-workflow ``` 或检查日志文件： ``` tail -f apps/incident-agent-workflow/logs/workflow.log ``` 寻找 `ollama_analysis`。 ## 活动警报 警报规则位于 [monitoring/alert-rules.yml](monitoring/alert-rules.yml)。 | 警报 | 条件 | 严重性 | | --- | --- | --- | | `ServiceDown` | Prometheus 无法抓取服务超过 30 秒 | `critical` | | `MongoDependencyDown` | `mongo-api-service` 无法 ping 通 MongoDB 超过 30 秒 | `critical` | | `Service5xxErrors` | 服务的非零 5xx 频率持续 30 秒 | `warning` | ## 有用查询 Prometheus: ``` up sum by (service) (up) sum by (service, handler, method, status) (rate(http_requests_total[1m])) sum by (service) (rate(http_requests_total{status="5xx"}[2m])) dependency_up{service="mongo-api-service", dependency="mongodb"} ``` Loki: ``` {service="weather-app1"} {service="mongo-api-service"} {service="incident-agent-workflow"} {service="incident-agent-workflow"} |= "ollama_analysis" {service="mongo-api-service"} |= "ERROR" ``` ## API 参考 ### `天气应用1` | 方法 | 路径 | 描述 | | --- | --- | --- | | `GET` | `/` | 基本服务检查 | | `GET` | `/weather/latitude={latitude}&longitude={longitude}` | 从 Open-Meteo 获取天气数据 | | `GET` | `/metrics` | Prometheus 指标 | ### `Mongo API 服务` | 方法 | 路径 | 描述 | | --- | --- | --- | | `GET` | `/health` | 存活检查 | | `GET` | `/health/ready` | MongoDB 就绪检查 | | `POST` | `/items/` | 创建条目 | | `GET` | `/items/` | 列出条目 | | `GET` | `/items/{item_id}` | 获取条目 | | `PUT` | `/items/{item_id}` | 更新条目 | | `DELETE` | `/items/{item_id}` | 删除条目 | | `GET` | `/metrics` | Prometheus 指标 | ### `事件代理工作流` | 方法 | 路径 | 描述 | | --- | --- | --- | | `GET` | `/health` | 存活检查 | | `POST` | `/alerts` | Alertmanager webhook 接收器 | | `GET` | `/metrics` | Prometheus 指标 | ## 深度调查 OpenAI 流水线 当需要更深入的日志、源码和草稿 PR 分析时，可以与 Docker 演示分开运行此流水线。 ``` cd apps/agent python3 -m venv .venv source .venv/bin/activate pip install -r ../../requirements.txt openai export OPENAI_API_KEY=your_key_here uvicorn main:app --host 0.0.0.0 --port 8001 --reload ``` 端点： ``` GET http://localhost:8001/health GET http://localhost:8001/services POST http://localhost:8001/analyze ``` `apps/log_watcher.py` 可以调用此流水线并生成 Word 报告。它目前包含本地机器路径，使用前请更新 `LOG_SOURCES`。如果流水线运行在端口 `8001`，请传递 `--agent-url http://localhost:8001`。 ## 遇到的挑战 ### Docker 到主机的 LLM 通信 Ollama 运行在主机上，而工作流运行在 Docker 中。工作流使用 `host.docker.internal:11434`，以便容器可以访问主机上的 LLM 服务器。 ### 可观测性集成 该系统依赖于 Prometheus、Alertmanager、Loki 和 Promtail 之间一致的标签。如果 `service` 标签或日志路径错误，代理可能收到警报但会丢失日志上下文。 ### 有用的通知 在事件期间，原始模型输出可能过于嘈杂。通知器的存在使得配置 SMTP 后，事件摘要可以通过简洁的邮件格式发送。 ### 两种 AI 路径 本地 Ollama 工作流快速，非常适合首次分诊。OpenAI 流水线更深入，更适合日志、堆栈跟踪、源代码分析和草稿 PR 生成。将这些路径分开可以使演示更易于理解。 ### 安全的草稿 PR 自动化 自动提出修复方案存在风险，如果系统写入过多或未经审核就合并。该项目使用草稿 GitHub Pull Request 作为交接点，让人类批准修复。 ## 成就 - 构建了一个从警报到 AI 生成分析的完整本地事件响应闭环。 - 连接了指标、日志、警报和 LLM 上下文，而不是构建一个独立的聊天机器人。 - 添加了 Prometheus、Alertmanager、Loki、Promtail 和 Grafana 作为生产级可观测性技术栈。 - 实现了用于更深入分析的多代理调查流水线。 - 添加了基于通知器的事件邮件。 - 添加了 GitHub 草稿 PR 交接，用于提出修复方案。 - 添加了报告生成工具，用于演示和事后分析。 - 使用 Mermaid 图表和可运行的设置步骤记录了该系统。 ## 我们学到了什么 - 警报只是触发器；上下文才是真正的产出。 - AI 分析只有基于遥测数据才有用。 - 标签和日志路径与模型本身同样重要。 - 在事件期间，结构化的摘要比冗长的解释更有用。 - 自动化应产生可审核的建议，然后再进行更改。 - 快速的本地分诊路径和更深入的调查路径服务于不同的需求。 ## 下一步计划 ### 更智能的修复 - 置信度评分 - 自动化测试建议 - 更安全的“不建议修复”阈值 - 对何时应打开草稿 PR 设置更强的保护机制 ### 更多通知渠道 - Slack - PagerDuty - 移动友好的升级路径 ### 统一事件路由 - 简单警报使用本地 Ollama 分诊 - 复杂警报使用更深层的 AI 流水线 - 高置信度的发现创建可审核的修复方案 ### 运行手册与工单集成 - 运行手册查询 - Jira 或 Linear 问题创建 - 自动事件关联 ## 故障排除 ### `incident-agent-workflow` 日志报 `LLM error` 检查 Ollama 是否正在运行且模型可用： ``` ollama list ollama pull mistral-nemo ``` ### Prometheus 目标状态为 `DOWN` 检查容器和服务日志： ``` docker compose ps docker compose logs weather-app1 docker compose logs mongo-api-service docker compose logs incident-agent-workflow ``` ### Mongo API 启动失败 确认 `apps/mongo-api-service/.env` 文件存在且 MongoDB 运行正常： ``` docker compose ps mongo docker compose logs mongo ``` ### Grafana 没有日志 检查 Promtail 和 Loki： ``` docker compose logs promtail docker compose logs loki ``` 同时确认日志文件存在于 `apps/*/logs/` 下。
Triage & Service Resolution"] A2["Agent 2
Log Investigation"] A3["Agent 3
Root Cause Analysis"] end %% Output OUT([Analysis Result
+ Draft Fix]) %% External tools REG[("service_registry.json")] TOOLS["Health + Log Tools"] GIT["Git / Source Tools"] %% Main flow IN --> A1 A1 --> A2 A2 --> A3 A3 --> OUT %% Tool usage A1 -. resolve services .-> REG A2 -. inspect logs & health .-> TOOLS A3 -. analyze source code .-> GIT %% Styling style PIPELINE fill:#eef4ff,stroke:#4a78c2,stroke-width:2px style A1 fill:#dbeafe,stroke:#2563eb,stroke-width:2px style A2 fill:#e0f2fe,stroke:#0284c7,stroke-width:2px style A3 fill:#ede9fe,stroke:#7c3aed,stroke-width:2px style OUT fill:#dcfce7,stroke:#16a34a,stroke-width:2px style IN fill:#fee2e2,stroke:#dc2626,stroke-width:2px style REG fill:#f8fafc,stroke:#64748b style TOOLS fill:#f8fafc,stroke:#64748b style GIT fill:#f8fafc,stroke:#64748b ``` 1. **代理 1 解决服务问题** 流水线从事件警报开始，使用 `service_registry.json` 将服务名称映射到健康检查 URL、日志路径、仓库路径以及语言/运行时上下文。 2. **代理 2 调查运行时证据** 第二个代理检查服务健康状况、读取相关日志、搜索错误，并提取解释故障原因的堆栈跟踪或请求上下文。 3. **代理 3 检查源代码** 最后一个代理使用 Git/源代码工具检查与堆栈跟踪或错误上下文相关的文件和行范围。这是流水线从“什么故障”转向“此代码为何可能故障”的环节。 4. **输出成为草稿修复** 结果包括根因分析、支持证据和一个建议的代码更改。这个建议的修复方案将输入到 GitHub 草稿 PR 流程，供人工审核。 有关两种 AI 路径的详细图表，请参阅 [architecture.md](architecture.md)。 ## 如何构建 完整的本地环境通过 Docker Compose 编排。 ### 应用层 - `weather-app1`：运行在端口 `8000` 的 FastAPI 天气服务 - `mongo-api-service`：运行在端口 `9000` 的 FastAPI CRUD 服务，后端为 MongoDB - 通过 `prometheus-fastapi-instrumentator` 提供 Prometheus `/metrics` 端点 - 基于文件的日志挂载到 Promtail ### 可观测性技术栈 - Prometheus：用于指标抓取和警报规则 - Alertmanager：用于警报分组和 webhook 分发 - Promtail 和 Loki：用于日志聚合 - Grafana：用于探索指标和日志 ### 警报工作流 - `incident-agent-workflow` 接收 `POST /alerts` - 它查询 Prometheus 获取 `up` 和 5xx 频率信号 - 它查询 Loki 获取服务的近期日志 - 它构建一个结构化的事件上下文对象 - 它将该上下文发送到 Ollama - 它将生成的分析记录为 `ollama_analysis` - 它将结果发送给通知器，用于事件邮件递送 - 它可以将复杂事件移交给 3 代理深度调查流水线 ### 通知系统 该仓库在 `apps/notifier/` 下包含一个 FastAPI 通知服务。 - 已实现 SMTP 邮件支持。 - 工作流将事件结果发布到 `/notify`。 - 邮件包含受影响的服务、警报名称、摘要和 AI 分析。 - 可以使用本地演示邮件工具（如 Mailpit），只需将通知器的 SMTP 设置指向该本地 SMTP 服务器。 ### 深度调查流水线 运行在主机上的 `apps/agent/` 流水线使用 OpenAI 和确定性工具进行： - 服务配置解决 - 健康检查 - 日志扫描 - 堆栈跟踪提取 - 通过 Git 命令检查源文件 ### 草稿 PR 自动化 深度调查代理确定可靠的修复方案后，修复流程会创建一个最小补丁并打开一个草稿 GitHub Pull Request。PR 保持草稿状态，以便工程师检查证据、审核代码、运行测试，并只在同意修复时才合并。 ### 报告 该仓库包含用于演示和事后分析工件的报告工具： - `apps/log_watcher.py` - `apps/monitor_service.py` - `apps/report_generator.py` 生成的报告写入 `apps/reports/` 目录下。 ## 仓库结构 ``` . |-- docker-compose.yml |-- architecture.md |-- README.md |-- apps/ | |-- weather-app1/ | |-- mongo-api-service/ | |-- incident-agent-workflow/ | |-- agent/ | |-- notifier/ | |-- log_watcher.py | |-- monitor_service.py | `-- report_generator.py `-- monitoring/ |-- prometheus.yml |-- targets.docker.yml |-- alert-rules.yml |-- alertmanager.yml |-- loki-config.yml |-- promtail-config.yml `-- grafana/provisioning/ ``` ## 本地运行 ### 前置条件 - Docker 和 Docker Compose - 主机上运行 Ollama - 本地拉取 `mistral-nemo` 模型 ``` ollama pull mistral-nemo ollama serve ``` 如果 Ollama 已经运行，`ollama serve` 可能会报告端口被占用。这没有关系。 ### 配置 Mongo API 创建 `apps/mongo-api-service/.env`： ``` cat > apps/mongo-api-service/.env <<'EOF' MONGO_URI=mongodb://mongo:27017 MONGO_DB=servicedb APP_NAME=Mongo API Service LOG_FILE=/app/logs/service.log EOF ``` ### 启动技术栈 ``` docker compose up -d --build ``` 检查状态： ``` docker compose ps ``` 停止技术栈： ``` docker compose down ``` ## 服务 URL | 服务 | URL | | --- | --- | | Weather API | http://localhost:8000 | | Mongo API | http://localhost:9000 | | 事件工作流 | http://localhost:9100 | | Prometheus | http://localhost:9090 | | Alertmanager | http://localhost:9093 | | Grafana | http://localhost:3000 | | Loki | http://localhost:3100 | | MongoDB | `localhost:27017` | Grafana 凭据为 `admin` / `admin`。 ## 验证演示 检查服务健康状况： ``` curl http://localhost:8000/ curl http://localhost:9000/health curl http://localhost:9100/health ``` 检查 Prometheus 目标： ``` http://localhost:9090/targets ``` 创建 Mongo 条目： ``` curl -X POST http://localhost:9000/items/ \ -H "Content-Type: application/json" \ -d '{"name":"demo","description":"test item","value":42}' ``` 查询天气服务： ``` curl "http://localhost:8000/weather/latitude=41.8781&longitude=-87.6298" ``` 手动触发测试警报： ``` curl -X POST http://localhost:9100/alerts \ -H "Content-Type: application/json" \ -d '{ "alerts": [ { "status": "firing", "labels": { "alertname": "ServiceDown", "service": "weather-app1" }, "annotations": { "summary": "weather-app1 is not responding" } } ] }' ``` 查看事件分析： ``` docker compose logs -f incident-agent-workflow ``` 或检查日志文件： ``` tail -f apps/incident-agent-workflow/logs/workflow.log ``` 寻找 `ollama_analysis`。 ## 活动警报 警报规则位于 [monitoring/alert-rules.yml](monitoring/alert-rules.yml)。 | 警报 | 条件 | 严重性 | | --- | --- | --- | | `ServiceDown` | Prometheus 无法抓取服务超过 30 秒 | `critical` | | `MongoDependencyDown` | `mongo-api-service` 无法 ping 通 MongoDB 超过 30 秒 | `critical` | | `Service5xxErrors` | 服务的非零 5xx 频率持续 30 秒 | `warning` | ## 有用查询 Prometheus: ``` up sum by (service) (up) sum by (service, handler, method, status) (rate(http_requests_total[1m])) sum by (service) (rate(http_requests_total{status="5xx"}[2m])) dependency_up{service="mongo-api-service", dependency="mongodb"} ``` Loki: ``` {service="weather-app1"} {service="mongo-api-service"} {service="incident-agent-workflow"} {service="incident-agent-workflow"} |= "ollama_analysis" {service="mongo-api-service"} |= "ERROR" ``` ## API 参考 ### `天气应用1` | 方法 | 路径 | 描述 | | --- | --- | --- | | `GET` | `/` | 基本服务检查 | | `GET` | `/weather/latitude={latitude}&longitude={longitude}` | 从 Open-Meteo 获取天气数据 | | `GET` | `/metrics` | Prometheus 指标 | ### `Mongo API 服务` | 方法 | 路径 | 描述 | | --- | --- | --- | | `GET` | `/health` | 存活检查 | | `GET` | `/health/ready` | MongoDB 就绪检查 | | `POST` | `/items/` | 创建条目 | | `GET` | `/items/` | 列出条目 | | `GET` | `/items/{item_id}` | 获取条目 | | `PUT` | `/items/{item_id}` | 更新条目 | | `DELETE` | `/items/{item_id}` | 删除条目 | | `GET` | `/metrics` | Prometheus 指标 | ### `事件代理工作流` | 方法 | 路径 | 描述 | | --- | --- | --- | | `GET` | `/health` | 存活检查 | | `POST` | `/alerts` | Alertmanager webhook 接收器 | | `GET` | `/metrics` | Prometheus 指标 | ## 深度调查 OpenAI 流水线 当需要更深入的日志、源码和草稿 PR 分析时，可以与 Docker 演示分开运行此流水线。 ``` cd apps/agent python3 -m venv .venv source .venv/bin/activate pip install -r ../../requirements.txt openai export OPENAI_API_KEY=your_key_here uvicorn main:app --host 0.0.0.0 --port 8001 --reload ``` 端点： ``` GET http://localhost:8001/health GET http://localhost:8001/services POST http://localhost:8001/analyze ``` `apps/log_watcher.py` 可以调用此流水线并生成 Word 报告。它目前包含本地机器路径，使用前请更新 `LOG_SOURCES`。如果流水线运行在端口 `8001`，请传递 `--agent-url http://localhost:8001`。 ## 遇到的挑战 ### Docker 到主机的 LLM 通信 Ollama 运行在主机上，而工作流运行在 Docker 中。工作流使用 `host.docker.internal:11434`，以便容器可以访问主机上的 LLM 服务器。 ### 可观测性集成 该系统依赖于 Prometheus、Alertmanager、Loki 和 Promtail 之间一致的标签。如果 `service` 标签或日志路径错误，代理可能收到警报但会丢失日志上下文。 ### 有用的通知 在事件期间，原始模型输出可能过于嘈杂。通知器的存在使得配置 SMTP 后，事件摘要可以通过简洁的邮件格式发送。 ### 两种 AI 路径 本地 Ollama 工作流快速，非常适合首次分诊。OpenAI 流水线更深入，更适合日志、堆栈跟踪、源代码分析和草稿 PR 生成。将这些路径分开可以使演示更易于理解。 ### 安全的草稿 PR 自动化 自动提出修复方案存在风险，如果系统写入过多或未经审核就合并。该项目使用草稿 GitHub Pull Request 作为交接点，让人类批准修复。 ## 成就 - 构建了一个从警报到 AI 生成分析的完整本地事件响应闭环。 - 连接了指标、日志、警报和 LLM 上下文，而不是构建一个独立的聊天机器人。 - 添加了 Prometheus、Alertmanager、Loki、Promtail 和 Grafana 作为生产级可观测性技术栈。 - 实现了用于更深入分析的多代理调查流水线。 - 添加了基于通知器的事件邮件。 - 添加了 GitHub 草稿 PR 交接，用于提出修复方案。 - 添加了报告生成工具，用于演示和事后分析。 - 使用 Mermaid 图表和可运行的设置步骤记录了该系统。 ## 我们学到了什么 - 警报只是触发器；上下文才是真正的产出。 - AI 分析只有基于遥测数据才有用。 - 标签和日志路径与模型本身同样重要。 - 在事件期间，结构化的摘要比冗长的解释更有用。 - 自动化应产生可审核的建议，然后再进行更改。 - 快速的本地分诊路径和更深入的调查路径服务于不同的需求。 ## 下一步计划 ### 更智能的修复 - 置信度评分 - 自动化测试建议 - 更安全的“不建议修复”阈值 - 对何时应打开草稿 PR 设置更强的保护机制 ### 更多通知渠道 - Slack - PagerDuty - 移动友好的升级路径 ### 统一事件路由 - 简单警报使用本地 Ollama 分诊 - 复杂警报使用更深层的 AI 流水线 - 高置信度的发现创建可审核的修复方案 ### 运行手册与工单集成 - 运行手册查询 - Jira 或 Linear 问题创建 - 自动事件关联 ## 故障排除 ### `incident-agent-workflow` 日志报 `LLM error` 检查 Ollama 是否正在运行且模型可用： ``` ollama list ollama pull mistral-nemo ``` ### Prometheus 目标状态为 `DOWN` 检查容器和服务日志： ``` docker compose ps docker compose logs weather-app1 docker compose logs mongo-api-service docker compose logs incident-agent-workflow ``` ### Mongo API 启动失败 确认 `apps/mongo-api-service/.env` 文件存在且 MongoDB 运行正常： ``` docker compose ps mongo docker compose logs mongo ``` ### Grafana 没有日志 检查 Promtail 和 Loki： ``` docker compose logs promtail docker compose logs loki ``` 同时确认日志文件存在于 `apps/*/logs/` 下。
标签：AI 辅助, AI风险缓解, Git, GPT, Grafana, LLM 分析, LLM评估, Loki, MongoDB, Ollama, OpenAI, 事件管理, 代码审查, 健康检查, 内存规避, 多引擎聚合, 开源监控, 拉取请求, 指标查询, 故障排除, 故障诊断, 服务配置, 根因分析, 漏洞管理, 电子邮件通知, 监控系统, 站点可靠性工程, 结构化摘要, 网络安全研究, 自动修复, 自定义请求头, 警报系统, 请求拦截, 逆向工具