跳到主要内容

插件结构

Grafana 插件允许您通过添加自定义功能（例如新的数据源、可视化或整个应用程序）来扩展 Grafana 的核心功能。

本指南将引导您了解 Grafana 插件的基本组成部分以及如何构建和组织它们。您将了解由 create-plugin 工具生成的文件夹结构，以及接下来如何使用脚手架模板构建和扩展插件。

观看下方视频，直观了解 Grafana 插件的结构和组成部分。此视频补充了本指南中的文字内容，并提供了对 Grafana 插件结构的实用见解。

开始之前​

在继续之前，建议查阅插件类型和用法指南，以对可用的不同类型插件有一个基本了解。

每个 Grafana 插件都由几个基本组件组成，这些组件以不同方式扩展了 Grafana 的功能。首先，我们将探讨三种主要插件类型（应用程序、数据源和面板）的核心部分。

The different available plugin types: app, data source, and panel
可用的不同插件类型：应用程序、数据源和面板

应用程序插件​

应用程序插件提供最大的灵活性，允许开发者构建超越基本可视化或数据交互的自定义体验。它们可以包含自定义页面、用于服务器端逻辑的后端以及连接到 Grafana 核心功能的 UI 扩展。

The components of an app plugin
应用程序插件的组成部分

页面​

应用程序可以添加可通过 Grafana 导航访问的自定义页面。这些页面本质上是 React 组件，允许开发者创建自定义用户界面。要添加页面，开发者可以使用 @grafana/runtime 包中的 PluginPage 组件。您可以在我们的应用程序教程中了解有关添加页面到应用程序的更多信息。

An example custom app page
自定义应用程序页面示例

配置​

应用程序插件通常包含配置页面，用户可以在其中输入必要的设置，例如 API 凭据或其他参数。您可以在我们的应用程序教程中了解有关添加配置页面到应用程序的更多信息。

An example app configuration page
应用程序配置页面示例

UI 扩展​

应用程序插件可以注册和暴露连接到 Grafana 核心功能的 UI 扩展，提供额外的功能或交互点。这些扩展点允许与 Grafana UI 进行强大的集成。您可以在我们的操作指南中了解有关 UI 扩展的更多信息。

An example panel visualization
面板可视化示例

健康检查​

应用程序可以定义健康检查，以确保插件配置正确且正常运行。您可以根据插件的后端逻辑自定义这些检查。有关实现细节，请参阅我们的示例健康检查。

调用资源​

应用程序可以拥有后端来处理服务器端功能，例如进行外部 API 调用或处理更高级的认证方法。CallResourceHandler 方法通常用于此目的。有关实现细节，请参阅我们的带后端的应用程序示例。

嵌套插件​

应用程序插件可以将多个插件（例如数据源或面板）捆绑到单个可安装包中。对于需要多种插件组合才能实现完整功能的服来说，这种方法非常有用。您可以在我们的文档中了解有关处理嵌套插件的更多信息。

数据源插件​

数据源插件允许 Grafana 连接到外部服务、配置查询和显示数据。它们可以包含纯前端或全栈组件（包含后端）。

The components of a Data Source plugin
数据源插件的组成部分

配置编辑器​

配置编辑器是用户在配置数据源的特定实例时提供外部服务的连接详细信息（例如，API 密钥、URL）的地方。要定义配置编辑器，请使用 setConfigEditor() 并传入一个自定义配置组件。您可以在我们的基本数据源插件示例中查看如何定义配置编辑器。

确保您的敏感数据使用 secureJson 安全存储。阅读我们的添加数据源插件认证指南了解更多详情。

An example Data Source config editor
数据源配置编辑器示例

查询编辑器​

查询编辑器允许用户针对连接的服务构建查询。此编辑器在仪表盘中添加面板、使用 Explore 以及创建新的告警规则时使用。查询编辑器可以自定义为提供代码编辑器以及引导式查询构建器。您可以在我们的数据源插件示例中查看如何定义查询编辑器。

An example data source query editor
数据源查询编辑器示例

健康检查​

数据源配置页面中的“保存并测试”按钮允许用户验证连接是否工作。插件可以通过添加自定义健康检查来自定义此行为。

A data source health check being performed
正在执行数据源健康检查

查询数据​

QueryData 方法处理多个查询并返回相应的响应。每个查询包含一个 RefID，该 RefID 在 QueryDataResponse 中映射到其响应。该方法遍历查询，单独处理它们，并返回结果或带适当状态码的错误。

这种方法可以有效地处理多个查询，并内置日志记录和错误管理，以确保顺利运行。

查看我们的数据源示例中的 QueryData 实现。

调用资源​

自定义端点允许数据源插件暴露自定义 HTTP API 路由用于服务器端功能。这在处理认证、高级查询或处理大型数据集时特别有用。您可以使用 CallResourceHandler 方法在后端创建自定义端点来处理请求并响应数据或状态信息。

有关如何实现自定义端点的示例，请参阅带后端的应用程序示例。

面板插件​

面板插件通过提供独特的 数据可视化 或其他有用的类似小部件功能来自定义组件，从而增强 Grafana。

The components of a panel plugin
面板插件的组成部分

可视化​

面板插件在 Grafana 仪表盘中提供数据的可视化呈现。要创建自定义可视化，开发者使用 React 组件来定义数据如何在仪表盘上渲染。这种可视化可以是简单的图表，也可以是复杂的交互式小部件。面板的 render() 函数定义了数据如何传递到可视化以及当数据或选项更改时如何处理更新。

有关面板可视化的更多详细信息，请参阅面板插件示例。

An example panel visualization
面板可视化示例

面板选项​

面板选项允许用户自定义面板插件的行为和外观。您可以通过实现 OptionsEditor 组件来定义这些选项，该组件可以暴露与可视化相关的选项。这些选项会传递给面板的 render() 函数，从而允许根据用户输入进行动态更新。

您可以在基本面板示例中查看如何实现面板选项的示例。

An example of custom panel options on the right
右侧自定义面板选项示例

插件文件夹结构​

运行 create-plugin 工具为您插件生成一个新文件夹。插件文件夹遵循标准命名约定（例如，organization-pluginName-pluginType），并包含构建、运行和测试插件所需的所有必要文件。

以下是文件夹布局和关键文件概览

myorg-myplugin-datasource/
├── pkg/
│   ├── main.go
│   └── plugin/
├── src/
│   ├── module.ts
│   ├── plugin.json
└── tests/
├── CHANGELOG.md
├── docker-compose.yaml
├── go.mod
├── package.json
├── LICENSE
├── Magefile.go
├── README.md
注意

create-plugin CLI 工具正在不断改进，因此本文档与您的脚手架插件项目之间可能存在细微差异。

关键插件文件​

以下文件对于您的插件开发和功能至关重要

  • 前端代码 (src/)：必需。此目录包含插件的所有前端代码。此处需要注意的主要文件是 plugin.json 和 module.ts。
    • plugin.json：存储有关插件的元数据，包括描述、支持的 Grafana 版本和依赖项等信息。
    • module.ts：插件前端逻辑的入口点。
  • 后端代码 (pkg/)：如果您的插件有后端组件，则为必需。如果您的插件包含后端功能，代码将驻留在该目录中，通常在 pkg/plugin/ 内。后端插件使用 Go 语言编写，main.go 是后端逻辑的入口点。
  • 测试文件 (tests/)：可选，但强烈建议确保插件质量。此文件夹包含您的插件测试文件，前端测试通常以 .spec.ts 为后缀。您可以在我们的端到端测试指南中了解有关测试插件的更多信息。
  • 其他文件:
    • docker-compose.yaml：仅在 Docker 环境中必需。包含用于运行本地 Grafana 开发实例的 Docker 配置。
    • CHANGELOG.md：必需。记录插件更改和更新的历史。
    • README.md：必需。提供插件概览，包括安装说明和使用指南。

后续步骤​

现在您已经了解了 Grafana 插件的基本组成部分和项目结构，我们推荐以下资源

这些资源将引导您了解构建、测试并最终发布插件的更多细节，确保您的开发过程顺利。