Observability AIops

Observability AIops

免责声明：由社区维护的开源项目。与 Prometheus 或 Grafana 项目、Grafana Labs 或 Cloud Native Computing Foundation 均无关联，也未获其认可或赞助。 Prometheus、Alertmanager 和 Grafana 是其各自所有者的商标。采用 MIT 许可。

在一台服务器上，为可自托管的可观测性技术栈提供受治理的 AI 运维能力 — Prometheus（HTTP API、PromQL、目标、规则、告警）、Alertmanager （告警 + 静默）、Grafana（仪表板、数据源、文件夹），以及 Grafana Loki（有界 LogQL 日志读取 + 日志根因分析）— 并配备内置 治理机制：统一审计日志、令牌 / 失控预算 防护、撤销令牌记录，以及描述性风险等级标签。一份配置即可覆盖整个技术栈；每个目标都指定自己的 platform。 除了模拟测试套件，Prometheus / Alertmanager / Grafana 读取、根因分析，以及受治理的静默 + 仪表板写入路径（含撤销）都已在运行中的 Prometheus 3.x + Alertmanager + Grafana 13 技术栈上经过测试 — 请参阅 docs/VERIFICATION.md。

这是企业级监控套件的可自托管可观测性补充方案：它使用 SRE 实际运行的开放 Prometheus / Grafana API，而不是厂商的 NMS。

功能

解答 SRE 在 Prometheus / Grafana 技术栈上反复遇到的问题，并为后续写入操作提供防护：

• PromQL + 元数据 — 即时查询和范围查询、标签值枚举及 序列元数据；全部为只读操作，并限制结果数量。
• 抓取目标与规则健康状况 — 哪些目标处于正常 / 异常状态（以及来自 lastError 的异常原因）、哪些目标因重新标记而被丢弃，以及哪些记录 / 告警规则出现错误。
• 告警与静默 — 正在触发 / 待处理的 Prometheus 规则告警、Alertmanager 路由处理后的视图，以及其静默。
• Grafana — 仪表板、数据源（+ 健康状况）和文件夹。
• Loki 日志 — 有界 LogQL 读取（标签 + 标签值枚举、经验证门控的 query_range，以及预设的错误日志尾部读取）；全部为只读操作，设有严格的回溯时间范围 + 行数上限，支持可选的多租户 X-Scope-OrgID，并可为每个目标配置基本身份验证 / bearer 身份验证。
• 旗舰分析 — 透明且会显示具体数值的启发式分析： firing_alert_rca（将每个正在触发的告警关联到其规则表达式 → 原因 + 操作建议）、 target_scrape_health_analysis（对异常 / 报错的抓取进行排序 → 可能原因）、 alert_noise_and_flap_analysis（频繁重复 / 重复告警 → 去重 / 汇总建议），以及两项日志分析 — log_error_burst_rca （按流分析错误突发与基线的差异 → 新签名 / 流量激增 / 单实例 / 无基线）和 log_volume_analysis（主要日志流 + 高基数标签 警告 + 保留期限提示）— 以及 alert_log_context，用于将正在触发的 Prometheus 告警与其 Loki 日志流相关联。
• 受治理的写入操作 — 创建 / 使 Alertmanager 静默过期（设定时限）、创建 Grafana 注释、更新 / 删除仪表板，以及热重载 Prometheus 配置 — 每项操作都会记录审计日志、划分风险等级、支持 dry_run；可撤销的操作会捕获实际获取的写入前状态，用于撤销。

此工具会做什么，不会决定什么

它准确、高效地执行 Prometheus + Grafana 运维操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入。这取决于 Agent 的判断，或你所连接账户的权限：如果给它的 Grafana 令牌只有 Viewer 权限范围，并且连接的 Prometheus/Alertmanager 未开放管理/写入 API，写入就会在服务器端失败——那里才是真正负责权限控制的地方。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一保证的是绝不静默：通过 MCP 或 CLI 发起的每次调用，都会在 ~/.observability-aiops/audit.db 中生成一条审计记录；对于破坏性写入，还会捕获操作前的状态，并在存在逆向操作时记录该操作。

每个工具都会声明一个 risk_level，并将其作为描述性等级（none/confirm/review）写入审计记录，方便审核者一眼看出某条记录是否涉及高风险删除。这只是一个标签，不是关卡。

功能矩阵（39 个 MCP 工具）

分组	平台	工具	数量	读/写
指标	Prometheus	instant_query, range_query, label_values, series_metadata	4	读取
目标	Prometheus	list_targets, target_scrape_health, dropped_targets	3	读取
状态	Prometheus	prometheus_config_status, prometheus_tsdb_status	2	读取
规则	Prometheus	list_rules, rule_health	2	读取
告警	Prometheus/Alertmanager	firing_alerts, pending_alerts, alertmanager_alerts, list_silences	4	读取
Grafana	Grafana	list_dashboards, get_dashboard, list_datasources, datasource_health, list_folders	5	读取
Loki	Loki	loki_labels, loki_label_values, loki_query, loki_tail_errors	4	读取
概览	all	observability_overview	1	读取
分析	Prometheus	firing_alert_rca, target_scrape_health_analysis, alert_noise_and_flap_analysis	3	读取
日志分析	Loki	log_error_burst_rca, log_volume_analysis	2	读取
跨信号	Prometheus + Loki	alert_log_context	1	读取
写入	Alertmanager	create_silence, expire_silence	2	写入（中）
	Grafana	create_annotation	1	写入（中）
	Grafana	update_dashboard	1	写入（中）
	Grafana	delete_dashboard	1	写入（高）
	Prometheus	reload_prometheus_config	1	写入（中）
撤销	all	undo_list	1	读取
	all	undo_apply	1	写入（中）

Loki 只读——Loki 不提供安全的运维写入接口（没有静默或注释这类对应功能），因此本工具特意不提供 Loki 写入功能。

CLI 提供一组便捷的子集功能（query、logs、alert、overview 等）；完整的 39 个工具通过 MCP 服务提供。

快速开始

作为 Claude Code 插件

安装一次，即可同时为 Agent 提供技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install observability-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定到此插件声明的包版本，因此可以将审计记录追溯到执行写入的代码。凭据仍需通过 observability-aiops init 配置——详见下文。

作为 OpenClaw 插件

同一套插件包也发布在 ClawHub，安装一次即可同时获得技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/observability-aiops
openclaw skills info observability-aiops          # expect: Visible to model: yes

之后重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定到此确切版本，因此 uvx 必须位于 PATH 中——如果没有，技能仍会安装，但会显示 Visible to model: no。凭据按下文所述配置。

作为 CLI 或独立 MCP 服务

uv tool install observability-aiops          # or: pipx install observability-aiops
observability-aiops init                     # wizard: pick platform (prometheus/grafana) + store the token (encrypted)
observability-aiops doctor                   # verify config, secrets, connectivity
observability-aiops overview                 # snapshot: firing alerts + targets up/down + rules erroring
observability-aiops query instant 'up'       # run a PromQL instant query
observability-aiops logs errors '{app="api"}' # tail error-level Loki logs (bounded)
observability-aiops alert rca                # root-cause the firing alerts

作为 MCP 服务运行（stdio）：

export OBSERVABILITY_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
observability-aiops mcp

密码随后会存在哪里：导出的变量对此 shell 启动的每个进程都可读，也会记录在 shell 历史中。在共享主机或长期运行的主机上，建议使用交互式提示，或从密钥管理器中注入密码，仅在需要它的那条命令运行期间使用。

治理

每个 MCP 工具都会通过随附的 @governed_tool 框架：

• 审计 — 每次调用（参数、结果、状态、耗时、风险等级，以及操作员提供的任何审批人／理由）都会记录到 ~/.observability-aiops/audit.db（可通过 OBSERVABILITY_AIOPS_HOME 更改位置）。CLI 写入的记录与 MCP 路径写入的相同——不存在未经审计的入口。
• 失控防护 — 安全后备机制，并非授权门控：同一调用在短时间内被反复触发时，会触发断路器。通过 OBSERVABILITY_RUNAWAY_MAX=0 禁用；也可设置可选的硬性上限 OBSERVABILITY_MAX_TOOL_CALLS / OBSERVABILITY_MAX_TOOL_SECONDS。
• 撤销记录 — 可逆写入会记录基于获取到的变更前状态构建的逆操作描述符（create_silence→过期，update_dashboard/delete_dashboard→恢复捕获的先前模型）。
• 风险等级 — 根据 risk_level 为审计记录生成的描述性标签；不进行任何限制。

支持范围和限制

• 平台：Prometheus HTTP API（以及配套的 Alertmanager）、Grafana HTTP API 和 Grafana Loki HTTP API（只读）。托管／SaaS 监控套件（Datadog、New Relic、企业级 NMS）有意不在此工具的支持范围内。
• 验证。 模拟套件覆盖全部四个平台；此外，还针对运行中的 Prometheus 3.x + Alertmanager + Grafana 13 技术栈测试了 Prometheus、Alertmanager 和 Grafana 接口（RCA、受治理的静默和仪表板写入，以及撤销重放）。Loki 接口尚未经过实时测试。四个平台都免费且开源，在实验环境中也很容易搭建（docker run prom/prometheus、grafana/grafana、grafana/loki），因此 observability-aiops doctor 是最快的实时检查方式（Prometheus /api/v1/status/buildinfo、Grafana /api/health、Loki /ready + /loki/api/v1/status/buildinfo）。请参阅 docs/VERIFICATION.md。

缺少某项功能？

想要增加读取能力、调整分析方式，或添加此处尚未提供的平台功能？ 欢迎提交 issue 或 PR——欢迎反馈和贡献。