使用 OpenMetadata Grafana 连接器导入仪表盘与面板连接配置指南与源码解析【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata本指南以 OpenMetadata 仓库中 Grafana Dashboard 连接器的配置文档openmetadata-ui/src/main/resources/ui/public/locales/en-US/Dashboard/Grafana.md为主体讲解如何配置 Grafana 实例连接、完成认证并导入仪表盘与面板元数据。读完本文你将掌握 Grafana 连接器的全部连接参数含义与推荐取值、Service Account Token 认证细节并了解连接测试、分页拉取、面板与血缘提取在源码层面的完整实现链路。一、前置要求认证方式与权限要将 Grafana 中的仪表盘Dashboard和面板Panel导入 OpenMetadata你需要对 Grafana 实例拥有合适的访问权限并准备正确的认证凭据。使用 Service Account Token 认证OpenMetadata 通过 Grafana HTTP API 拉取元数据认证方式为 Bearer Token。当前仓库推荐使用 Service Account Token其格式通常以glsa_开头例如glsa_xxxxx。Token 必须具备读取权限该 Token 需要拥有读取仪表盘dashboards、文件夹folders和数据源datasources的权限。为覆盖全部元数据官方文档建议直接使用Admin 角色的 Token这是实现完整元数据提取的推荐做法。关于这一认证约定可以从源码中得到印证。在 client.py 的GrafanaApiClient.__init__中客户端会对 Token 前缀做一次非阻塞校验——若 Token 不以glsa_开头会输出一条 warning 日志提示“Legacy API keys are no longer supported by Grafana as of January 2025, please create a Service Account Token in Grafana”即旧版 API Key 自 2025 年 1 月起已被 Grafana 官方弃用请改用 Service Account Tokenif not api_key.startswith(glsa_): logger.warning( Token does not appear to be a Service Account Token (should start with glsa_). Legacy API keys are no longer supported by Grafana as of January 2025. Please create a Service Account Token in Grafana. )二、连接配置项详解Connection DetailsGrafana 连接器在 OpenMetadata UI 的“Add Service → Dashboard → Grafana”表单中提供以下配置项其定义与默认值以 grafanaConnection.json 中的 JSON Schema 为准。1. Host and PorthostPortGrafana 实例的基础 URLBase URL即连接器的访问入口。示例取值Grafana Cloudhttps://your-org.grafana.net自托管Self-hostedhttps://grafana.company.com本地开发http://localhost:3000容器环境注意事项如果你以 Docker 方式运行 OpenMetadata ingestion而 Grafana 实例部署在本机localhost则应将主机名改为host.docker.internal例如http://host.docker.internal:3000以便容器内进程访问宿主机服务。在 JSON Schema 中该字段为uri格式的必填字符串。底层客户端在 client.py 中会先对传入 URL 做rstrip(/)处理再拼接/api前缀发起请求因此 URL 尾部是否带斜杠不影响请求正确性。2. Service Account TokenapiKey用于调用 Grafana API 的 Service Account Token即上节所述的glsa_前缀令牌。在 Schema 中该字段以password格式存储属于必填项OpenMetadata 在展示与日志中会对其做脱敏处理。关键要点优先使用 Service Account Token格式如glsa_xxxxxGrafana 自 2025 年 1 月起不再支持 Legacy API Keys请勿继续使用旧式 API Key自托管实例与 Grafana Cloud 均支持推荐使用 Admin 角色以获得完整元数据提取能力。3. Verify SSLverifySSL控制连接 Grafana 时是否校验 SSL 证书默认值true开启证书校验仅在开发或测试等非生产环境中且确认网络链路可信时才建议关闭。该布尔值在 connection.py 中被透传给 HTTP 客户端verify_ssl(self.service_connection.verifySSL if self.service_connection.verifySSL is not None else True)并最终设置为 requests Session 的session.verify属性。对应地单元测试 test_grafana_client.py 中专门验证了verify_sslFalse时session.verify为False。4. Page SizepageSize分页请求 Grafana API 时每页返回的记录条数默认值100当实例中的仪表盘数量较多时可适当增大该值以减少 API 调用次数Schema 中约束最小值为1。分页逻辑在 client.py 的get_folders与search_dashboards中实现客户端从page 1开始循环请求携带{page: page, limit: self.page_size}参数当返回条数小于page_size或返回空列表时停止翻页。单元测试 test_grafana_client.py 通过 mock 两页数据验证了该翻页逻辑page_size2时共发起 2 次请求。配置参数速查表参数字段名必填默认值说明Host and PorthostPort是无Grafana 实例基础 URLDocker 环境可用host.docker.internalService Account TokenapiKey是无glsa_前缀 TokenAdmin 角色推荐Verify SSLverifySSL否true是否校验 SSL 证书仅开发/测试可关闭Page SizepageSize否100分页大小仪表盘多时可调大以减少 API 调用除上述四项外Schema 还定义了dashboardFilterPattern按正则过滤仪表盘、chartFilterPattern按正则过滤图表与supportsMetadataExtraction字段并在required中声明hostPort与apiKey为必填项。三、连接构建与连接测试的源码实现Grafana 连接器在 Python 侧的模块结构为connection.py连接构建与连通性测试client.pyGrafana HTTP API 客户端metadata.py元数据提取主流程models.pyGrafana API 响应的 Pydantic 模型service_spec.py将GrafanaSource与GrafanaConnection组装为服务规格。在GrafanaConnection._get_client中四个配置参数被逐一映射到GrafanaApiClient构造函数host_port、api_key通过get_secret_value()解密、verify_ssl为空时回退为True、page_size为空时回退为100。连接测试流程test_connection调用client.test_connection()其底层请求 Grafana 的GET /api/org接口——能成功返回组织信息即视为连通。该探测逻辑在 test_grafana_client.py 中有对应断言URL 为https://grafana.example.com/api/org。因此用于连接测试的 Token 至少需要具备访问org接口的权限这进一步印证了推荐使用具备完整读权限Admin角色的必要性。四、从连接参数到元数据导入的完整链路配置好上述参数后Grafana 连接器会依次完成以下元数据提取步骤对应 metadata.py准备阶段prepare调用get_datasources()GET /api/datasources拉取全部数据源并按 UID 与名称双重建索引供后续血缘解析使用仪表盘列表get_dashboards_list调用search_dashboards()GET /api/search携带typedash-db与分页参数获取仪表盘列表每个条目以 UID 作为 OpenMetadata 中的实体名称仪表盘详情get_dashboard_details对每个 UID 调用GET /api/dashboards/uid/{uid}获取完整定义标题、描述、标签、面板、URL 等并通过createdBy尝试匹配 OpenMetadata 中的用户作为 Owner面板提取yield_dashboard_chart遍历仪表盘panels数组跳过row行容器与text类型面板将每个面板映射为 Chart 实体。需要注意面板 ID 仅在单个仪表盘内唯一因此图表名称采用dashboard_uid _ panel_id的组合以保证全局唯一。折叠行collapsed row中的子面板会通过_flatten_panels递归展开后再处理面板类型映射_map_panel_type_to_chart_type将 Grafana 面板类型映射为标准图表类型例如timeseries/graph→ Line、table→ Table、gauge→ Gauge、piechart→ Pie、heatmap→ Heatmap、geomap→ Map、logs→ Table 等未匹配的类型回退为 Other血缘提取yield_dashboard_lineage_details从面板的targets中提取查询语句优先读取rawSql/rawSQL字段兼容 Trino、Athena 等不同 SQL 插件的字段命名差异跳过 Prometheus、Elasticsearch 等非 SQL 数据源类型见NON_SQL_DATASOURCE_TYPES随后通过LineageParser解析 SQL 中的源表再结合db_service_prefix前缀过滤与 OpenMetadata 搜索匹配表实体建立“表 → 仪表盘”的血缘关系。这些流程均以配置小节中的hostPort、apiKey、verifySSL、pageSize为基础运行其中pageSize直接影响第 1、2 步的分页请求次数。五、错误处理与故障排查要点从 client.py 的_make_request可以提炼出以下排查依据401 / 403权限不足客户端会记录 warning 日志“Permission denied for …”并跳过该接口继续后续处理不会中断整个工作流。若发现仪表盘或数据源导入不完整请优先检查 Token 权限是否覆盖 dashboards、folders、datasources 读取Admin 角色为最稳妥选择其他 HTTP 错误与网络异常记录 error 日志后返回空结果对应接口的数据会被跳过Token 格式告警Token 不以glsa_开头时会输出 warning提示使用 Service Account Token——注意这与 401/403 是两类独立问题格式正确但权限不足会触发前者格式不合法则可能在 Grafana 侧直接鉴权失败。上述错误分支在 test_grafana_client.py 中均有覆盖401 返回空列表、403 返回None、500 返回空列表、通用异常返回空列表可以作为排查行为的参考依据。六、相关代码与测试索引如需深入阅读或二次开发可在仓库中定位以下文件连接配置文档openmetadata-ui/src/main/resources/ui/public/locales/en-US/Dashboard/Grafana.md连接配置 JSON Schemaopenmetadata-spec/src/main/resources/json/schema/entity/services/connections/dashboard/grafanaConnection.json连接构建与测试ingestion/src/metadata/ingestion/source/dashboard/grafana/connection.pyAPI 客户端ingestion/src/metadata/ingestion/source/dashboard/grafana/client.py元数据提取主流程ingestion/src/metadata/ingestion/source/dashboard/grafana/metadata.pyAPI 响应模型ingestion/src/metadata/ingestion/source/dashboard/grafana/models.py单元测试ingestion/tests/unit/topology/dashboard/test_grafana_client.py、ingestion/tests/unit/topology/dashboard/test_grafana.py、ingestion/tests/unit/topology/dashboard/test_grafana_lineage.py、ingestion/tests/unit/topology/dashboard/test_grafana_simple.py、ingestion/tests/unit/source/dashboard/grafana/test_connection.py七、小结Grafana 连接器的配置核心可以归结为四点正确的主机地址含 Docker 场景的host.docker.internal特例、glsa_前缀的 Service Account Token推荐 Admin 角色、按环境取舍的 SSL 校验开关、以及按仪表盘规模调优的分页大小。理解这四个参数在 JSON Schema 与 Python 客户端中的映射关系再结合连接测试GET /api/org、分页拉取page/limit与 401/403 告警等源码行为即可在 OpenMetadata 中快速、稳定地完成 Grafana 仪表盘与面板的元数据导入。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考