asthamohta/CS224G-SRE

# RootScout RootScout 是一个用于分布式系统自动化根因分析 (RCA) 的智能体系统。它摄取遥测数据（OTel 链路、指标、日志）和 GitHub PR 数据，构建因果依赖关系图，并使用 LLM 识别导致事故的服务及其原因。 ## 工作原理 1. **图构建** — 摄取 Trace Span 并将其连接成有向依赖关系图。每个节点跟踪健康状态和近期事件。 2. **故障隔离** — 当警报触发时，从告警服务开始进行 BFS 遍历，收集可疑的子图。 3. **LLM 推理** — Gemini（或 Claude）智能体接收上下文数据包并返回结构化的根因报告。 ## 设置 ### 前置条件 - Python 3.9+ - 来自 [Google AI Studio](https://aistudio.google.com/) 的 Gemini API 密钥 ### 安装 ``` git clone https://github.com/asthamohta/CS224G-SRE.git cd CS224G-SRE pip install -r requirements.txt ``` ### 配置 ``` cp .env.example .env # 编辑 .env 并设置 GEMINI_API_KEY=your_key_here ``` ### 运行演示 ``` python demo.py ``` 演示程序会摄取合成的 OTel 数据，构建依赖关系图，并针对模拟的 cart-service 故障运行由 LLM 驱动的 RCA。 ## 评估 两条评估赛道用于衡量智能体是否正确识别了故障的组件、原因和日期时间，使用 [OpenRCA](https://github.com/microsoft/OpenRCA) 评分标准。 安装评估依赖项： ``` pip install -r requirements_eval.txt ``` ### 评分 根据任务类型，每个事故最多按三个标准进行评分： | 标准 | 匹配方法 | |---|---| | 根因组件 | 精确字符串匹配 | | 根因原因 | 余弦相似度 >= 0.50 (all-MiniLM-L6-v2) | | 发生日期时间 | 在真实值的 +/- 60 秒范围内 | 只有当所有适用标准都满足时，场景才算通过。 ### 赛道 A — 合成基准 十个手工 crafted 的场景，具有已知的拓扑结构和注入的故障。适用于在不针对真实数据运行的情况下迭代优化智能体 Prompt。 ``` python eval/run_eval.py # all 10 scenarios (requires Gemini API key) python eval/run_eval.py --mock # mock LLM, no API key needed python eval/run_eval.py --difficulty easy ``` 样本结果： ``` Class Total Correct Accuracy easy 3 2 66.7% medium 3 3 100.0% hard 4 3 75.0% Total 10 8 80.0% ``` ### 赛道 B — 真实 OpenRCA Bank 遥测数据 来自 [OpenRCA Bank 数据集](https://github.com/microsoft/OpenRCA) 的 27 个事故 — 这是一个基于 Java 的银行微服务系统，包含 14 个 Pod。需要在项目根目录下有 `Bank/` 数据集目录： ``` Bank/ query.csv record.csv telemetry/ 2021_03_04/ metric/metric_container.csv log/log_service.csv 2021_03_06/ ... ``` ``` python eval/run_openrca_eval.py # 27 Bank incidents (requires Gemini API key) python eval/run_openrca_eval.py --mock # no API key needed python eval/run_openrca_eval.py --n 5 # quick test with 5 incidents python eval/run_openrca_eval.py --bank-dir /path/to/Bank ``` 样本结果： ``` BANK BENCHMARK SUMMARY (real OpenRCA telemetry) Class Total Full pass Avg score easy 2 1 0.71 medium 18 4 0.52 hard 7 1 0.38 Total 27 6 0.49 ``` 真实数据的得分低于合成数据，因为真实事故存在噪声信号、跨 Pod 资源争用以及模糊的遥测数据。 ## 已知限制 - **赛道 B 上的日期时间评分并非真实有效的。** 故障时间戳直接取自 `record.csv`，而非由智能体预测，因此日期时间标准总是通过。真正的修复方法是在智能体的响应模式中添加 `root_cause_datetime` 字段。 - **真实数据上无 Trace 拓扑。** `trace_span.csv` 使用的是无法映射到 Pod 名称的内部容器 ID，因此改用了静态的手写拓扑。 - **异常检测存在噪声。** KPI 阈值是启发式的；在真实事故期间，许多 Pod 会同时出现峰值，使得因果隔离更加困难。 - **单一系统。** 仅评估了 Bank 系统。OpenRCA 还包括 Telecom 和 Market。 ## 项目结构 ``` graph/ Graph construction, context retrieval, RCA agent llm_integration/ Gemini and Claude client wrappers eval/ Evaluation scripts and scenarios RootScout/ OTel ingester service (FastAPI) Ingester/ GitHub webhook ingester slack_integration/ Slack notification connector ```

标签：AIOps, AI工程师, API集成, DLL 劫持, Gemini, GET参数, OpenTelemetry, OTel, Python, RCA, Site Reliability Engineering, SRE, 偏差过滤, 分布式系统, 可观测性, 告警关联, 响应大小分析, 因果依赖图, 大语言模型, 微服务监控, 故障排查, 无后门, 智能运维, 用户代理, 自动化根因分析, 自动化运维, 逆向工具, 链路追踪