gaurav0106/iirs

# IIRS IIRS 是针对 issue [#1](https://github.com/gaurav0106/iirs/issues/1) 的本地事件响应助手原型。它在模拟或实时遥测数据上运行 `Retriever -> Analyst -> Critic -> Planner` 流水线，并生成包含排序后根因、证据引用和推荐操作的事件简报。 ## 当前范围 已实现： - 共享事件状态和按事件的 JSON 追踪 - LangGraph 优先的线性流水线，包含本地回退运行器 - CLI 和 Chainlit 入口 - 针对 `postgres_down` 和 `redis_down` 的模拟故障场景 - 实时 Prometheus、Loki 和 Tempo 遥测适配器 - 本地可观测性栈资产和 Aspire Shop 引导助手 - 基于 Docker 的 PostgreSQL 和 Redis 故障注入助手 - 带有真值标签的定量评估工具 - 当存在本地密钥时，由 OpenAI 支持的 Analyst、Critic 和后续响应 尚未完成： - Aspire Shop 仍从上游示例仓库获取，而非在此处打包 - Retriever 和 Planner 仍是确定性的 - 实时遥测签名检查尚未自动化 - 定性审查评分和最终演示/报告润色尚未实现 ## 前置条件 - Python `3.12+` - `git` - 对于实时栈路径：Docker、Docker Compose、`.NET 10 SDK` 以及 Aspire CLI 或 `dotnet run` - 对于模型支持路径：`.env.local` 中的本地 OpenAI API 密钥 ## 设置 创建虚拟环境并安装包： ``` python3 -m venv .venv source .venv/bin/activate pip install -e . ``` ### 本地 OpenAI 配置 如果 `.env.local` 存在，IIRS 会自动加载它。`.env` 和 `.env.local` 已被 gitignore。 推荐的 `.env.local`： ``` OPENAI_API_KEY=sk-... IIRS_AGENT_MODEL=gpt-5-mini IIRS_OPENAI_REASONING_EFFORT=low IIRS_EMBEDDING_MODEL=text-embedding-3-small ``` 注意： - `gpt-5-mini` 是此项目当前支持的模型中的最佳默认选择 - 如果存在密钥，Analyst、Critic 和后续回答将自动使用 OpenAI - 设置 `IIRS_USE_OPENAI_AGENTS=false` 以强制执行确定性行为 - 目前 Retriever 和 Planner 仍保持确定性 ## 最快路径：模拟端到端 运行内置场景： ``` iirs run --scenario postgres_down --show-trace iirs run --scenario redis_down --show-trace ``` 或从告警固件运行： ``` iirs run --alert-file fixtures/alerts/postgres_down.json --show-trace iirs run --alert-file fixtures/alerts/redis_down.json --show-trace ``` 你将看到： - 终端中的事件简报 - 排序后的根因 - 分为 `auto-safe` 和 `needs-approval` 的操作 - `traces/` 下的追踪路径 ### Chainlit ``` source .venv/bin/activate chainlit run chainlit_app.py -h ``` 然后发送： 1. `postgres_down` 或 `redis_down` 2. 后续问题，例如 `What is the root cause?` 3. 或完整的告警 JSON 负载 ### 评估 运行定量工具： ``` iirs eval --runs 3 ``` 有用的变体： ``` iirs eval --scenario postgres_down --runs 5 iirs eval --runs 3 --format json ``` 评估工具检查： - Top-1 根因准确率 - Top-3 根因准确率 - 必需的证据源覆盖率 - 必需的操作类型和操作关键词覆盖率 真值标签位于 `fixtures/ground_truth/`。 ## 实时本地栈 这是包含 Aspire Shop 以及 Prometheus、Loki、Tempo 和 OTel Collector 的完整本地路径。 ### 1. 启动可观测性栈 ``` ./scripts/run_observability_stack.sh up ./scripts/run_observability_stack.sh ps ``` 端口： - Prometheus: `http://localhost:9090` - Loki: `http://localhost:3100` - Tempo: `http://localhost:3200` - OTel Collector OTLP gRPC: `localhost:4317` - OTel Collector OTLP HTTP: `localhost:4318` - OTel Collector Prometheus exporter: `localhost:9464` ### 2. 获取 Aspire Shop ``` ./scripts/bootstrap_aspire_shop.sh ``` 默认情况下，这会将上游示例克隆到 `.external/aspire-samples`。 ### 3. 针对本地 Collector 运行 Aspire Shop ``` cd .external/aspire-samples/samples/aspire-shop export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 export OTEL_EXPORTER_OTLP_PROTOCOL=grpc aspire run ``` 替代方案： ``` dotnet run --project AspireShop.AppHost ``` 该示例暴露了这些关键资源： - `frontend` - `catalogservice` - `catalogdbmanager` - `basketservice` - PostgreSQL 资源 `postgres` 及数据库 `catalogdb` - Redis 资源 `basketcache` ### 4. 生成基线流量 从 Aspire 输出中打开商店前端并： 1. 浏览目录 2. 将商品添加到购物篮 3. 刷新并重复 ### 5. 验证遥测数据已到达 Prometheus: ``` curl -s http://localhost:9090/api/v1/targets curl -s -G http://localhost:9090/api/v1/query --data-urlencode 'query=up' ``` Loki: ``` curl -s -G http://localhost:3100/loki/api/v1/query --data-urlencode 'query={service_name="catalogservice"}' curl -s -G http://localhost:3100/loki/api/v1/query --data-urlencode 'query={service_name="basketservice"}' ``` Tempo: ``` curl -s -G http://localhost:3200/api/search --data-urlencode 'q={ resource.service.name = "catalogservice" }' curl -s -G http://localhost:3200/api/search --data-urlencode 'q={ resource.service.name = "basketservice" }' ``` ### 6. 启用实时 IIRS 后端 ``` export IIRS_TELEMETRY_BACKEND=plt export IIRS_PROMETHEUS_URL=http://localhost:9090 export IIRS_LOKI_URL=http://localhost:3100 export IIRS_TEMPO_URL=http://localhost:3200 ``` 可选： ``` export IIRS_TENANT_ID=tenant-a export IIRS_HTTP_TIMEOUT_SECONDS=15 export IIRS_VERIFY_TLS=false ``` 运行 IIRS： ``` iirs run --alert-file fixtures/alerts/postgres_down.json --show-trace ``` 或使用 Chainlit： ``` chainlit run chainlit_app.py -h ``` 实时模式检查： - 运行完成且未出现 `TelemetryConfigurationError` - 追踪包含 `"used_langgraph": true` - Retriever 证据 ID 类似于 `log.live.*`、`metric.live.*` 或 `trace.live.*` - 引用指向 `/api/v1/query_range`、`/loki/api/v1/query_range` 和 `/api/search` ## 故障注入 使用助手： ``` ./scripts/inject_aspire_fault.sh discover ./scripts/inject_aspire_fault.sh stop postgres ./scripts/inject_aspire_fault.sh start postgres ./scripts/inject_aspire_fault.sh stop redis ./scripts/inject_aspire_fault.sh start redis ``` 别名： - PostgreSQL: `postgres`, `db`, `catalogdb` - Redis: `redis`, `basketcache`, `cache` 发现行为： - PostgreSQL 匹配包含 `postgres` 或 `catalogdb` 的容器名称 - Redis 匹配包含 `basketcache` 或 `redis` 的容器名称 - 模糊匹配会快速失败并需要覆盖 显式覆盖： ``` export IIRS_ASPIRE_POSTGRES_CONTAINER= export IIRS_ASPIRE_REDIS_CONTAINER= ``` 典型工作流： 1. 启动可观测性栈 2. 运行 Aspire Shop，将 OTLP 指向 Collector 3. 生成基线流量 4. 运行 `./scripts/inject_aspire_fault.sh discover` 5. 停止 PostgreSQL 或 Redis 6. 生成更多流量并验证故障信号 7. 针对匹配的告警固件运行 IIRS 8. 使用 `start postgres` 或 `start redis` 恢复 脚本级工具为： ``` bash tests/test_fault_injection.sh ``` ## 验证和故障排除 运行测试套件： ``` python3 -m unittest discover -s tests ``` 检查追踪产物： ``` ls traces rg -n '"used_langgraph"|"scenario_name"|"source_type"' traces/*.json ``` 如果你希望即使在存在 `.env.local` 的情况下流水线也保持完全确定性： ``` export IIRS_USE_OPENAI_AGENTS=false ``` 如果 OpenAI 支持的运行太慢，请保持 `IIRS_OPENAI_REASONING_EFFORT=low` 并优先使用 CLI 运行而非 Chainlit。 ## 配置参考 常规： - `IIRS_TRACE_DIR`：追踪输出目录，默认为 `traces` - `IIRS_PREFER_LANGGRAPH`：默认为 `true` 遥测： - `IIRS_TELEMETRY_BACKEND`：`mock` 或 `plt` - `IIRS_PROMETHEUS_URL` - `IIRS_LOKI_URL` - `IIRS_TEMPO_URL` - `IIRS_TENANT_ID` - `IIRS_HTTP_TIMEOUT_SECONDS` - `IIRS_VERIFY_TLS` OpenAI: - `OPENAI_API_KEY` 或 `IIRS_OPENAI_API_KEY` - `IIRS_USE_OPENAI_AGENTS` - `IIRS_OPENAI_BASE_URL` - `IIRS_OPENAI_REASONING_EFFORT` - `IIRS_AGENT_MODEL` - `IIRS_EMBEDDING_MODEL` 故障注入： - `IIRS_ASPIRE_POSTGRES_CONTAINER` - `IIRS_ASPIRE_REDIS_CONTAINER` - `IIRS_DOCKER_CMD` ## 仓库布局 - `src/iirs/`：应用程序代码 - `infra/observability/`：Prometheus、Loki、Tempo 和 OTel Collector 配置 - `runbooks/`：Retriever 使用的静态故障排除文档 - `fixtures/alerts/`：示例告警负载 - `fixtures/ground_truth/`：评估标签 - `scripts/`：可观测性、Aspire Shop 和故障注入助手 - `tests/`：单元和集成覆盖 - `docs/implementation-status.md`：针对 issue #1 的实现状态 ## 其他参考 - Issue: [#1](https://github.com/gaurav0106/iirs/issues/1) - 状态文档：[`docs/implementation-status.md`](docs/implementation-status.md)

标签：AIOps, API集成, Chainlit, DevOps工具, Docker, GPT集成, Grafana Loki, LangGraph, PostgreSQL, PyRIT, Python, RAG, Redis, SRE, Tempo, 事件管理, 值班工程师助手, 偏差过滤, 决策辅助, 分布式追踪, 可观测性, 多智能体系统, 安全防御评估, 对话式AI, 指标监控, 搜索引擎查询, 故障注入, 故障诊断, 无后门, 智能事件响应系统, 本地部署, 根因分析, 测试用例, 混沌工程, 自定义请求头, 证据溯源, 请求拦截, 运维自动化, 逆向工具, 链路追踪