Keep 集成 Grafana Provider 完整实战指南：本地调试、告警接入与拓扑采集

Keep 集成 Grafana Provider 完整实战指南：本地调试、告警接入与拓扑采集

【免费下载链接】keepThe open-source AIOps and alert management platform项目地址: https://gitcode.com/GitHub_Trending/kee/keep

本篇指南围绕开源 AIOps 告警管理平台 Keep 的 Grafana 集成，系统讲解如何在本地环境快速拉起不同版本的 Grafana 实例用于调试，如何通过服务账户（Service Account）与 Keep Provider 对接、完成告警拉取与 webhook 推送，以及如何采集 Grafana 服务拓扑数据。读完本文，你将掌握一套可直接复制的本地调试与生产接入方法，并了解 Keep 底层 GrafanaProvider 的实现细节。

一、为什么需要本地 Grafana 调试环境

Keep 的 Grafana 集成（Provider）负责从 Grafana 拉取告警、接收 Grafana 推送的 webhook 事件，并采集服务拓扑数据。由于 Grafana 存在"传统告警（Legacy Alerting）"与"统一告警（Unified Alerting）"两套体系，且不同版本对 API 行为、webhook 认证方式有差异，在接入 Keep 之前，用本地容器快速拉起一个可控的 Grafana 实例进行验证是最稳妥的做法。

GrafanaProvider 的实现中，setup_webhook会读取 Grafana 版本来决定 webhook 的认证方式：版本大于 9.4.7 时使用authorization_scheme: digest，小于等于 9.4.7 时则把api_key追加为查询参数（见 grafana_provider.py）。这正是官方调试文档要区分不同版本的直接原因。

二、按版本启动本地 Grafana 容器

以下命令对应 Keep 仓库 grafana_provider/README.md 提供的调试方案，覆盖三种典型场景。

2.1 版本 9.3.2（带旧版缺陷的验证场景）

docker run -d --name=grafana -p 3001:3000 grafana/grafana-enterprise:9.3.2

该版本小于 9.4.7，Keep 的 webhook 集成会走"api_key 作为查询参数"的兼容路径，适合复现和验证旧版本行为。

2.2 版本 > 9.4.7（latest）

docker run -d --name=grafana -p 3001:3000 grafana/grafana-enterprise

9.4.7 以上的版本在 webhook 中能正确发送 digest 认证信息，Keep 会以标准authorization_scheme: digest方式注入 API Key。

2.3 版本 10.4 开启传统告警（Legacy Alerting）

从 Grafana 9.0 起默认启用统一告警（Unified Alerting），传统告警默认关闭。若需要测试传统告警链路（Keep 的_setup_legacy_alerting_webhook会调用/api/alert-notifications创建通知渠道，并通过/api/alerts遍历告警、回写仪表盘面板），需要手动开启。

先创建自定义配置文件grafana.ini：

cat << EOF > grafana.ini [alerting] enabled = true [unified_alerting] enabled = false EOF

再用挂载方式启动 Grafana：

docker run -d \ --name=grafana-legacy \ -p 3001:3000 \ -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini \ grafana/grafana-enterprise:10.4.0

默认登录凭据为：

• 用户名：admin
• 密码：admin

对照参考：仓库自带的 docker-compose.yml 则演示了"统一告警 + 图片渲染 + Prometheus + node-exporter"的完整本地环境，其中 grafana.ini 明确保持[alerting] enabled = false、[unified_alerting] enabled = true，并启用了截图捕获（capture = true）、本地外部图片存储与渲染服务http://renderer:8081/render。

三、手动创建 Keep 专用的服务账户令牌

容器拉起后，唯一需要手动执行的一步是创建服务账户（Service Account）并生成令牌，其余集成工作（webhook 联系点、通知策略）可由 Keep 自动完成。官方文档给出了两段curl：

第一步，创建服务账户（角色 Admin）：

curl -X POST -H "Content-Type: application/json" \ -u admin:admin \ http://localhost:3001/api/serviceaccounts \ -d '{"name":"keep-service-account","role":"Admin"}'

预期返回类似：

{"id":2,"name":"keep-service-account","login":"sa-keep-service-account","orgId":1,"isDisabled":false,"role":"Admin","tokens":0,"avatarUrl":""}

第二步，用返回的id生成访问令牌：

curl -X POST -H "Content-Type: application/json" \ -u admin:admin \ http://localhost:3001/api/serviceaccounts/2/tokens \ -d '{"name":"keep-token"}'

预期返回：

{"id":1,"name":"keep-token","key":"glsa_XXXXXX"}

key字段（glsa_开头）即 Keep Provider 配置中需要的令牌。Keep 的端到端测试 test_grafana_provider.py 采用完全相同的 API 流程：先POST /api/serviceaccounts创建账户，再POST /api/serviceaccounts/{id}/tokens生成令牌，随后用该令牌安装 Provider。

四、Keep 侧接入 Grafana Provider

在 Keep 的 Providers 页面安装 Grafana Provider 时，需要提供以下认证参数（对应源码中 GrafanaProviderAuthConfig 的定义）：

4.1 权限范围（Scopes）

Provider 安装时会通过/api/access-control/user/permissions校验令牌权限（见 validate_scopes）。Keep 声明的三个 scope 如下：

webhook 集成会自动为 Keep 申请alert.provisioning:read与alert.provisioning:write两个 scope。若令牌权限不足，界面会显示 "Missing Scope"——e2e 测试中故意使用随机令牌安装时，正是断言出现 3 个 "Missing Scope"（见 test_grafana_provider.py）。

4.2 传统告警与统一告警的选择

Keep 同时支持 Grafana 两套告警体系（详见 docs/providers/documentation/grafana-provider.mdx）：

• 传统告警（Legacy Alerting）：通过通知渠道（notification channels）投递告警，在仪表盘面板级别配置，使用/api/alerts与/api/alert-notifications接口；配置简单但功能较少，告警与仪表盘面板强耦合。适用于 Grafana 8.x 及更早版本，或在新版本中显式开启传统告警的情况。
• 统一告警（Unified Alerting，Grafana 9.0 起默认）：通过告警规则（alert rules）与联系点（contact points）集中管理，支持基于标签的路由和跨数据源的多数据源告警，使用/api/v1/provisioning/*系列接口。

setup_webhook在执行统一告警配置后，还会通过_is_legacy_alerting_enabled探测/api/alert-notifications是否可用（返回 200 即启用），自动为传统告警创建同名 webhook 通知渠道，并把通知 UID 回写到对应仪表盘面板的 alert 配置中（见 grafana_provider.py 与 L825-L933）。

五、验证接入是否成功

5.1 通过 Grafana 联系点测试（推荐）

Keep 的 webhook 集成会在 Grafana 的Contact Points下安装名为keep-grafana-webhook-integration的联系点（常量定义见 KEEP_GRAFANA_WEBHOOK_INTEGRATION_NAME）。验证步骤：

1. 在 Grafana 中进入Alerting → Contact Points，找到keep-grafana-webhook-integration；
2. 点击View contact point，再点击Test；
3. 回到 Keep，此时应能看到一条来自 Grafana 的测试告警。

5.2 Keep 不可外部访问时的替代验证

• 在 Grafana 中手动创建测试告警，配置一个指向 Keep 的联系点，触发告警后检查 Grafana 日志确认投递成功；
• 通过 Grafana 的 Explore/日志功能排查 webhook 相关错误；
• 在Alerting页面确认集成状态为活跃，并监控出站 HTTP 请求是否到达 Keep 端点。

六、拉取告警（Pull）与 Webhook 推送（Push）的双通道原理

6.1 Webhook 推送：统一告警链路

setup_webhook的核心动作（见 grafana_provider.py）：

1. 从/api/v1/provisioning/contact-points读取全部联系点，按名称或 UID 判断keep-grafana-webhook-integration-{tenant_id}是否已存在，存在则更新、不存在则创建；
2. 根据 Grafana 版本选择认证注入方式（digest 或查询参数）；
3. 读取/api/v1/provisioning/policies，若没有指向该 webhook 的路由，则追加{"receiver": webhook_name, "continue": true}路由，且不会覆盖用户已有的默认接收器。

手动配置等效方案：在 Grafana 中新建 Webhook 类型联系点，URL 填{keep_webhook_api_url}，请求头添加X-API-KEY: {api_key}；随后在Notification policies下新建子策略（不指定 matchers），选择该联系点并保存（见 webhook_markdown）。

6.2 拉取：三路合并采集

_get_alerts（见 grafana_provider.py）从三个来源聚合告警：

1. 数据源直查：通过/api/datasources枚举 Prometheus、Loki、Mimir 数据源，再经/api/datasources/proxy/uid/{uid}/api/v1/alerts（Loki 走 Prometheus 兼容端点）读取活跃告警；
2. 历史 API：查询最近 7 天/api/v1/rules/history?from=...&to=...；新版 Grafana 若要求ruleUID参数，则先取全部规则 UID 再逐个拉取历史；
3. Alertmanager：查询/api/alertmanager/grafana/api/v2/alerts，把suppressed状态映射为 SUPPRESSED、有endsAt的映射为 RESOLVED。

6.3 状态与严重级别的映射

Keep 将 Grafana 的状态和级别统一映射为内部枚举（见 STATUS_MAP 与 SEVERITIES_MAP）：

6.4 告警指纹（Fingerprint）计算

Keep 依靠指纹对告警做去重与关联。GrafanaProvider 的calculate_fingerprint（见 grafana_provider.py）按如下优先级取值：告警体中的fingerprint字段 → labels 中的fingerprint→ labels 的 JSON 序列化做 SHA-256 → 兜底使用alertname + service的 SHA-256。另外，_format_alert会把 Grafana 告警的annotations、values、generatorURL（结合externalURL解析为完整 URL）、dashboardURL、panelURL、silenceURL、valueString等字段写入AlertDto，供工作流模板安全引用（见 grafana_provider.py）。

6.5 模拟告警与告警规则 Schema

• simulate_alert（见 grafana_provider.py）基于 alerts_mock.py 中的HighMemoryConsumption、NetworkLatencyIsHigh等样例生成模拟告警，用于联调工作流，无需真实触发 Grafana 告警。
• get_alert_schema返回 grafana_alert_format_description.py 定义的GrafanaAlertFormatDescription，描述了一条 Grafana 告警规则的最小字段约束（如condition必须是data中某个refId、folderUID/ruleGroup/title非空且限长等），Keep 侧的deploy_alert依赖该结构通过/api/v1/provisioning/alert-rules部署规则。

七、采集服务拓扑数据（Service Topology）

Grafana Provider 还可向 Keep 的服务拓扑图贡献数据。前提是在 Provider 配置中填写datasource_uid（Tempo 通过 Prometheus 兼容数据源暴露服务图指标）。

获取数据源 UID 的方法：Connections → Data Sources，找到正在采集 Tempo 数据的 Prometheus 实例，其 URL 形如https://host/connections/datasources/edit/<DATASOURCE_UID>，复制该 UID 填入 Provider 配置即可。

底层实现上，pull_topology（见 grafana_provider.py）向/api/ds/query提交两条 PromQL 即时查询：

• sum by (client, server) (rate(traces_service_graph_request_total[3600s]))—— 每秒请求数；
• sum by (client, server) (rate(traces_service_graph_request_server_seconds_sum[3600s]))—— 请求总耗时。

随后从返回帧的labels中解析client/server标签，构建服务依赖关系，边权值格式为{rps}r/sec || {ms}ms/r（总耗时/请求数 × 1000），最终生成TopologyServiceInDto列表写入 Keep 拓扑（见 pull_topology）。若未配置datasource_uid，Provider 会跳过拓扑拉取。

八、进一步探索

• 阅读 docs/providers/documentation/grafana-provider.mdx 获取 Provider 安装的完整界面操作说明与拓扑数据源配置注意事项；
• 查看 tests/providers/grafana_provider/ 下的test_grafana_v12_webhook.py（验证 Grafana 12 告警 webhook 载荷解析与相对 URL 拼接）和test_grafana_datasource_query.py（验证数据源查询与帧展平逻辑）；
• 参考 tests/e2e_tests/test_grafana_provider.py 了解 Provider 安装、scope 校验与告警触发的端到端行为；
• 仓库自带的 grafana_provider/docker-compose.yml 与 grafana/grafana.ini 提供了一套包含渲染器、Prometheus、node-exporter 的完整本地 Grafana 环境，可直接docker compose up复现统一告警与截图能力。

【免费下载链接】keepThe open-source AIOps and alert management platform项目地址: https://gitcode.com/GitHub_Trending/kee/keep