插件解剖学

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

本指南将向您介绍 Grafana 插件的必要组件，以及如何对它们进行结构和组织。您将了解由 create-plugin 工具生成的文件夹结构，以及如何使用模板构建和扩展插件。

观看以下视频 以获得 Grafana 插件结构和组件的视觉概述。此视频补充了本指南中的书面内容，并提供了关于 Grafana 插件解剖学的实用见解。

在开始之前

在继续之前，我们建议您先回顾 插件类型和用法指南，以获得对可用插件类型的基本了解。

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

可用的不同插件类型：应用程序、数据源和面板

应用程序插件

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

应用程序插件的组件

页面

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

一个自定义应用程序页面的示例

配置

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

一个应用程序配置页面的示例

UI扩展

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

一个面板可视化的示例

健康检查

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

调用资源

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

嵌套插件

应用程序插件可以将多个插件（如数据源或面板）捆绑成一个可安装的包。这种方法对于需要插件组合才能完全功能的服务很有用。您可以在我们的文档中了解更多关于与嵌套插件一起工作的信息。

数据源插件

数据源插件允许Grafana连接到外部服务，配置查询并显示数据。它们可以包括仅前端或全栈组件（具有后端）。

数据源插件组件

配置编辑器

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

使用secureJson确保您的敏感数据安全存储。阅读我们的指南，了解如何在为数据源插件添加认证。

一个数据源配置编辑器的示例

查询编辑器

查询编辑器允许用户对连接的服务进行查询构造。该编辑器在添加仪表板中的面板、使用探索功能和创建新的警报规则时使用。查询编辑器可以自定义以提供代码编辑器和引导查询构建器。您可以在我们的数据源插件示例中看到如何定义查询编辑器：代码编辑器以及引导查询构建器。

一个示例数据源查询编辑器

健康检查

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

正在执行的数据源健康检查

查询数据

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

这种方法允许高效地处理多个查询，并具有内置的日志记录和错误管理，以确保平稳运行。

请参阅我们数据源示例中的QueryData实现：QueryData实现。

调用资源

自定义端点允许数据源插件公开自定义HTTP API路由以实现服务器端功能。当处理身份验证、高级查询或处理大型数据集时，这特别有用。您可以通过使用CallResourceHandler方法来处理请求并返回数据或状态信息，在后端创建自定义端点。

有关实现自定义端点的示例，请参阅具有后端的应用示例。

面板插件

面板插件通过提供在仪表板中提供独特的数据可视化或其他类似小部件功能的自定义组件来增强Grafana。

面板插件的组件

可视化

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

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

一个面板可视化的示例

面板选项

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

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

右侧自定义面板选项的例子

插件文件夹结构

运行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插件的必备组件和项目结构，我们有一些资源推荐

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

这些资源将指导您详细了解构建、测试和最终发布插件的过程，确保您有一个顺畅的开发过程。