跳到主要内容

插件结构

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 为后缀。 您可以在我们的 E2E 测试指南中了解有关测试插件的更多信息。
  • 其他文件:
    • docker-compose.yaml：仅 Docker 环境需要。 包含用于运行 Grafana 本地开发实例的 Docker 配置。
    • CHANGELOG.md：必需。 记录对插件所做的更改和更新的历史记录。
    • README.md：必需。 提供插件的概述，包括安装说明和使用指南。

下一步​

现在您已经了解了 Grafana 插件的基本组件和项目结构，我们有一些资源可以推荐

  • 教程：通过我们的 Grafana 插件教程深入了解特定的插件开发任务。 这些指南将帮助您创建和自定义数据源、面板和应用程序插件。
  • 插件示例：查看 GitHub 上的 Grafana 插件示例存储库，其中包含展示各种类型插件的示例项目。
  • 社区：加入 Grafana 社区，从其他插件开发人员那里获得建议、分享经验并寻求帮助。
  • 插件发布：当您准备好分享您的插件时，了解如何发布 Grafana 插件。

这些资源将指导您完成构建、测试和最终发布插件的更精细细节，确保您拥有流畅的开发过程。