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 --namegrafana -p 3001:3000 grafana/grafana-enterprise:9.3.2该版本小于 9.4.7Keep 的 webhook 集成会走api_key 作为查询参数的兼容路径适合复现和验证旧版本行为。2.2 版本 9.4.7latestdocker run -d --namegrafana -p 3001:3000 grafana/grafana-enterprise9.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.inicat EOF grafana.ini [alerting] enabled true [unified_alerting] enabled false EOF再用挂载方式启动 Grafanadocker run -d \ --namegrafana-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第一步创建服务账户角色 Admincurl -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 的定义参数是否必填说明token是上一步生成的服务账户令牌glsa_...敏感字段host是Grafana 地址例如https://keephq.grafana.net必须是合法 URLdatasource_uid否需要拉取拓扑数据时填写对应数据源的 UID4.1 权限范围ScopesProvider 安装时会通过/api/access-control/user/permissions校验令牌权限见 validate_scopes。Keep 声明的三个 scope 如下Scope必填用途alert.rules:read拉取告警时必填读取文件夹及其子文件夹中的告警规则alert.provisioning:readwebhook 集成时必填通过 provisioning API 读取告警规则、通知策略等alert.provisioning:writewebhook 集成时必填更新告警规则、通知策略等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 AlertingGrafana 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。验证步骤在 Grafana 中进入Alerting → Contact Points找到keep-grafana-webhook-integration点击View contact point再点击Test回到 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从/api/v1/provisioning/contact-points读取全部联系点按名称或 UID 判断keep-grafana-webhook-integration-{tenant_id}是否已存在存在则更新、不存在则创建根据 Grafana 版本选择认证注入方式digest 或查询参数读取/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从三个来源聚合告警数据源直查通过/api/datasources枚举 Prometheus、Loki、Mimir 数据源再经/api/datasources/proxy/uid/{uid}/api/v1/alertsLoki 走 Prometheus 兼容端点读取活跃告警历史 API查询最近 7 天/api/v1/rules/history?from...to...新版 Grafana 若要求ruleUID参数则先取全部规则 UID 再逐个拉取历史Alertmanager查询/api/alertmanager/grafana/api/v2/alerts把suppressed状态映射为 SUPPRESSED、有endsAt的映射为 RESOLVED。6.3 状态与严重级别的映射Keep 将 Grafana 的状态和级别统一映射为内部枚举见 STATUS_MAP 与 SEVERITIES_MAPGrafana 状态Keep 状态ok/resolved/normalRESOLVEDpausedSUPPRESSEDalertingFIRINGpending/no_dataPENDINGGrafana 级别Keep 级别criticalCRITICALhighHIGHwarningWARNINGinfoINFO默认兜底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 模拟告警与告警规则 Schemasimulate_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 TopologyGrafana Provider 还可向 Keep 的服务拓扑图贡献数据。前提是在 Provider 配置中填写datasource_uidTempo 通过 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_uidProvider 会跳过拓扑拉取。八、进一步探索阅读 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考