stephendelaney/OpsAgent

# OpsAgent - AI 驱动的 Java 节点事件响应 一个智能运维 Agent，通过收集诊断数据、执行基于 LLM 的根因分析并向运维团队发送告警，自动响应 AWS EC2 实例上的 Java 节点故障。 ## 概述 当 Java 节点发生故障时，OpsAgent 由 Monit 告警触发。它会： 1. **收集诊断数据**：来自 EFS 的日志、当前系统指标，以及可选的 heap dump 2. **AI 分析**：使用 Claude/GPT 进行全面的根因分析 3. **告警运维团队**：通过 Slack/PagerDuty 发送详细报告 4. **可选重启**：如果启用，可以自动重启节点（默认禁用） ## 运行模型 OpsAgent 的实际运行方式与其功能同样重要。需要了解三点： 1. **它是一个常驻监听器，通常在本地/运维主机上运行。** OpsAgent 是一个长期运行的 Flask webhook 服务——每个 EC2 节点上的 Monit 会在 Java 进程失败的那一刻向其发送 POST 请求。因此，托管 OpsAgent 的机器必须保持**开机状态，且能被节点网络访问到**，以便告警能够到达。在笔记本电脑上运行适合开发，但在实际部署中需要一台专用的常驻主机（小型运维机器或 bastion）。默认情况下，webhook 绑定到 `127.0.0.1`；要从远程节点接收告警，请设置 `webhook_host: "0.0.0.0"` **并**启用 `authentication`（参见[安全注意事项](#security-considerations)）。 2. **应用日志存在于每个实例的 EFS 挂载中，并保留两份深度。** 每个 EC2 实例都挂载了共享的 EFS 驱动器，Java 应用将其日志写入此处。保留策略是一个**保留两份文件的滚动窗口**（当前日志加上一次轮转）——因此及时收集至关重要：一旦发生第三次轮转，最早的证据就会丢失。当告警触发时，OpsAgent 会通过 SSH/SFTP 连接到节点，并在该窗口越过故障点之前提取挂载到 EFS 的日志（路径在 `config.yaml` 中的 `efs:` 下配置）。 3. **在存放 Java 源代码的地方运行它，您将获得源代码级别的关联分析。** 日志分诊告诉您发生了*什么*失败；将堆栈跟踪和日志证据与实际的源代码树配对，可以告诉您是*哪段代码路径*导致的。当 OpsAgent 运行在一台也检出了服务源代码的机器上时，这种关联就变得可行了——这就是“思考伙伴”步骤，Claude 结合运行时证据和源代码进行推理。有关这如何契合默认的“日志优先”设计，请参见[日志与代码分析对比](#logs-vs-code-analysis)。 ## 核心功能 - 🤖 **基于 LLM 的分析**：使用 Claude Sonnet 或 GPT-4 进行全面的根因诊断 - 📊 **智能数据收集**：仅收集必要的数据（仅在出现内存问题时才收集 heap dump） - 🎯 **务实的设计**：专注于诊断，而非代码分析（日志中包含答案） - 🔒 **默认安全**：禁用自动恢复 - 由运维团队决定是否重启 - ⚡ **快速响应**：简化的工作流，用于快速的事件分诊 - 🧪 **全面测试**：包含模拟组件的全面测试套件 ## 架构（简化版） ``` OpsAgent/ ├── OpAgent.py # Main orchestrator + Monit webhook ├── config.yaml # Configuration ├── requirements.txt # Dependencies ├── collectors/ # Data collection modules │ ├── log_collector.py # Gather logs from EFS │ ├── metrics_collector.py # Current system metrics │ └── heap_dump_collector.py # Optional heap dump collection ├── analyzer.py # Unified LLM analyzer ├── recovery.py # Optional automated restart ├── utils/ # Supporting utilities │ ├── logger.py # Structured logging │ └── notifier.py # Slack/PagerDuty alerts └── tests/ # Comprehensive test suite ``` ## 工作流 ``` ┌─────────────┐ │ Monit Alert │ └──────┬──────┘ │ v ┌──────────────────────────────────┐ │ 1. Collect Current Metrics │ │ - CPU, memory, disk, Java PID │ └──────┬───────────────────────────┘ │ v ┌──────────────────────────────────┐ │ 2. Collect Logs from EFS │ │ - Application logs │ │ - System logs │ │ - GC logs │ │ (rolling window, two deep — │ │ pulled before it rotates past)│ └──────┬───────────────────────────┘ │ v ┌──────────────────────────────────┐ │ 3. Collect Heap Dumps (Optional) │ │ - Only if OOM detected │ └──────┬───────────────────────────┘ │ v ┌──────────────────────────────────┐ │ 4. LLM Analysis (Claude/GPT) │ │ - Root cause identification │ │ - Evidence correlation │ │ - Actionable recommendations │ └──────┬───────────────────────────┘ │ v ┌──────────────────────────────────┐ │ 5. Alert Operations Team │ │ - Slack notification │ │ - PagerDuty incident │ │ - Detailed incident report │ └──────┬───────────────────────────┘ │ v ┌──────────────────────────────────┐ │ 6. Optional: Automated Restart │ │ - Disabled by default │ │ - Ops team manually restarts │ └──────────────────────────────────┘ ``` ## 安装说明 ### 前置条件 - Python 3.8+ - 已配置 AWS 凭证 - 对 EC2 实例的 SSH 访问权限 - Anthropic 或 OpenAI API key ### 设置 ``` # 克隆仓库 git clone https://github.com/stephendelaney/OpsAgent.git cd OpsAgent # 安装依赖 pip install -r requirements.txt # 复制并自定义配置 cp config.yaml.example config.yaml vi config.yaml # 更新：SSH key 路径、EFS 路径、实例详情 # 配置 API keys export ANTHROPIC_API_KEY="your-api-key-here" export SLACK_WEBHOOK_URL="your-slack-webhook-url" # 运行测试 pytest tests/ -v # 启动 agent python OpAgent.py ``` ### 部署（常驻主机） 由于 OpsAgent 是一个长期运行的监听器（参见[运行模型](#operating-model)），在实际部署中，应该通过进程管理器将其运行在一台常驻主机上，而不是在终端中运行。 一个最简的 `systemd` unit： ``` # /etc/systemd/system/ops-agent.service [Unit] Description=OpsAgent - Java incident response listener After=network-online.target Wants=network-online.target [Service] Type=simple User=ops-agent WorkingDirectory=/opt/ops-agent # 在此处提供 API keys / MONIT_AUTH_TOKEN，或通过 config.yaml 从 AWS Secrets Manager 加载 EnvironmentFile=/etc/ops-agent/ops-agent.env ExecStart=/opt/ops-agent/.venv/bin/python /opt/ops-agent/OpAgent.py Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target ``` ``` sudo systemctl daemon-reload sudo systemctl enable --now ops-agent sudo systemctl status ops-agent journalctl -u ops-agent -f # follow logs ``` 请记住在 `config.yaml` 中设置 `webhook_host: "0.0.0.0"` 并启用 `authentication`，以便远程的 Monit 节点能够访问该监听器（参见[安全注意事项](#security-considerations)）。 ## 配置 ### 核心配置项 ``` # 启用/禁用自动恢复 (DEFAULT: false) recovery: auto_restart: false # Ops team manually restarts by default # 用于收集 log 和 heap dump 的 EFS 路径 efs: logs_path: "/mnt/efs/logs" heap_dumps_path: "/mnt/efs/heap-dumps" # LLM provider (anthropic 或 openai) llm: provider: "anthropic" anthropic: model: "claude-sonnet-4-5-20250929" # 通知渠道 notifications: slack: enabled: true channel: "#ops-alerts" ``` 有关所有选项，请参见 [config.yaml.example](config.yaml.example)。 ## 用法 ### 作为 Webhook 服务 将 Agent 启动为监听 Monit 告警的 webhook 服务： ``` python OpAgent.py ``` Agent 将监听 8000 端口（可配置）以接收传入的 Monit webhook。 ### 配置 Monit 将 webhook 添加到您的 Monit 配置中： ``` check process java-app with pidfile /var/run/java-app.pid start program = "/opt/java-app/bin/start.sh" stop program = "/opt/java-app/bin/stop.sh" if does not exist then exec "/usr/bin/curl -X POST http://ops-agent-host:8000/monit-webhook \ -H 'Content-Type: application/json' \ -d '{\"service\":\"java-app\",\"event\":\"Does not exist\",\"instance_ip\":\"INSTANCE_IP\",\"instance_id\":\"INSTANCE_ID\"}'" ``` ### 手动触发（用于测试） ``` import asyncio from OpAgent import OpAgent agent = OpAgent('config.yaml') alert_data = { 'service': 'java-app', 'event': 'Does not exist', 'instance_ip': '10.0.1.50', 'instance_id': 'i-1234567890abcdef0' } result = asyncio.run(agent.handle_alert(alert_data)) print(result) ``` ## 测试 包含单元测试和集成测试的全面测试套件： ``` # 运行所有测试 pytest tests/ -v # 运行特定 test module pytest tests/test_collectors.py -v # 附带 coverage 运行 pytest tests/ --cov=. --cov-report=html # 仅运行 integration tests pytest tests/test_integration.py -v ``` ### 测试固件 位于 `tests/fixtures/` 的示例数据文件： - `sample_monit_alert.json`：Monit 告警示例 - `sample_app.log`：包含 OOM 错误的应用日志 - `sample_gc.log`：显示内存压力的 GC 日志 - `test_config.yaml`：测试配置 ## 为什么采用这种设计？ ### 日志与代码分析对比 **决策**：自动化路径专注于日志分析，而不是代码仓库分析。 **理由**： - Java 故障（OOM、死锁、连接问题）在日志中显而易见 - 堆栈跟踪直接指向问题区域 - 无需检出/解析代码，响应更快 - 复杂度更低，可靠性更高——自动化分诊保持快速且无依赖 **本地源代码例外**：默认采用“日志优先”，因为 Agent 无法假设其运行的任何主机上都存在源代码。但是，当您在检出了服务源代码的环境中*确实*运行了 OpsAgent 时（参见[运行模型](#operating-model)，第 3 点），将日志证据与实际代码关联起来是顺理成章的下一步——堆栈帧映射到真实的文件和行号，LLM 可以直接针对出错的路径进行推理。可以将其视为两个层级：默认情况下进行快速的纯日志分诊，当手头有代码时，则进行更深度的源码关联根因分析。 ### 默认手动恢复 **决策**：默认禁用自动恢复。 **理由**： - 运维人员在重启前会审查分析结果 - 防止重启循环 - 允许对复杂问题进行人工干预 - 在生产环境中更安全 ### 可选的 Heap Dump **决策**：仅在检测到内存问题时才收集 heap dump。 **理由**： - Heap dump 体积庞大（GB 级别），传输缓慢 - 只有与内存相关的故障才需要它 - 大多数问题仅通过日志即可诊断 ## 安全注意事项 - **SSH 密钥**：存储在 AWS Secrets Manager 中（推荐）或安全的文件系统中 - **API 密钥**：使用环境变量，切勿提交到代码中 - **Webhook 认证**：在生产环境中启用基于 token 的认证 - **凭证脱敏**：敏感数据在记录前进行脱敏处理 - **日志数据会离开您的环境**：收集到的应用日志会被发送给第三方 LLM （Claude/GPT）进行分析，日志中可能包含嵌入在堆栈跟踪中的 PII、token 或机密信息。 请审查您服务商的数据处理条款，如果这关系到您的合规性要求，请在源头对敏感字段进行清洗或脱敏。（注意：EFS 的滚动窗口只有两个文件的深度，因此它本身并不是一个长期的留存存储——请在其他地方满足审计/留存需求。） ## 故障排除 ### Agent 未收到告警 - **Webhook 绑定地址**：默认情况下，OpsAgent 绑定 `127.0.0.1`，因此远程 Monit 节点无法访问它。要接受来自其他主机的告警，请设置 `webhook_host: "0.0.0.0"` 并通过 `MONIT_AUTH_TOKEN` 启用 `authentication`。 - 确认运行 OpsAgent 的主机已开机且可访问——它是一个常驻监听器（参见[运行模型](#operating-model)）；如果机器休眠或断网，告警将会丢失。 - 检查 Monit webhook 配置 - 验证到 Agent 的网络连通性 - 检查 Agent 日志：`/var/log/ops-agent/ops-agent.log` ### SSH 连接失败 - 验证配置中的 SSH 密钥路径 - 检查 EC2 安全组是否允许来自 Agent 的 SSH 连接 - 测试手动 SSH 连接：`ssh -i /path/to/key.pem ec2-user@instance-ip` ### LLM 分析失败 - 验证 API 密钥是否已设置：`echo $ANTHROPIC_API_KEY` - 检查 API 速率限制 - 查看 LLM 服务商的状态页面 ### Heap dump 收集缓慢 - Heap dump 可能有几个 GB 大小 - 这是正常现象 - 考虑在配置中增加 `collection_timeout` - 验证 EFS 挂载性能 ## 许可证 [在此处添加您的许可证] ## 支持 如有问题或疑问： - 检查 `/var/log/ops-agent/` 中的日志 - 查看 `/tmp/ops-agent-incidents/` 中的事件报告 - 启用 DEBUG 日志记录以获取详细输出 **注意**：此 Agent 专为防御性安全和事件响应设计。它不执行代码修改或进攻性安全操作。

标签：AIOps, Petitpotam, 库, 应急响应, 故障诊断, 根因分析, 自动化响应, 运维工具, 逆向工具