构建数据源后端插件

简介

Grafana 支持多种数据源，包括 Prometheus、MySQL 和 Datadog。但在某些情况下，您可能已经拥有内部指标解决方案，并希望将其添加到 Grafana 仪表板中。本教程将指导您构建一个新的数据源插件来查询数据。

后端组件为您的插件提供了许多附加功能，例如自定义身份验证方法。要了解更多信息，请参阅有关后端插件的文档。

在本教程中，您将

为您的数据源构建后端
为您的数据源实现健康检查
为您的数据源启用Grafana 报警

先决条件

Grafana v10.0 或更高版本
Docker
Go (版本)
Mage
Node.js 的 LTS 版本

创建新插件

Grafana create-plugin 工具是一个 CLI 应用程序，它简化了 Grafana 插件开发，让您可以专注于编写代码。该工具会为您搭建一个入门插件、所有必需的配置以及使用 Docker Compose 构建的开发环境。

在一个新目录中，使用 create-plugin 工具从模板创建插件。当提示您选择插件类型时，选择并对“您是否需要插件的后端部分？”回答“是”
```
npx @grafana/create-plugin@latest
```
进入新创建的插件目录
```
cd <your-plugin>
```
安装依赖项
```
npm install
```
构建插件前端
```
npm run dev
```
在新终端窗口中，构建插件后端
```
mage -v build:linux
```
启动 Grafana
```
docker compose up
```
打开 Grafana（默认为 https://:3000），然后导航到 Administration > Plugins。确保您的插件已列出。

您还可以通过检查日志来验证 Grafana 是否已发现该插件

INFO[01-01|12:00:00] Plugin registered       logger=plugin.loader pluginID=<your-plugin>

现在，让我们验证一下您目前构建的插件是否可以在 Grafana 中创建新数据源时使用

在侧边菜单中，转到 Connections > Data Sources。
点击 Add data source。
搜索您新创建的插件名称并选中它。
输入一个名称，然后点击 Save & Test。如果出现“随机错误”，您可以忽略它 - 这是由下面进一步解释的健康检查导致的。

现在您已经创建了一个新的插件数据源实例，可以在仪表板中使用。

将数据源添加到仪表板

创建一个新的仪表板并添加一个新面板。
在查询选项卡上，选择您刚刚创建的数据源。将渲染一个包含两数据点系列折线图。
保存仪表板。

故障排除

Grafana 未加载我的插件

确保 Grafana 已以开发模式启动。如果您从源代码运行 Grafana，请将以下行添加到您的 conf/custom.ini 文件中

app_mode = development

注意

如果您还没有 conf/custom.ini 文件，请在继续之前创建它。

然后您可以通过在 Grafana 仓库根目录运行 make run & make run-frontend 来以开发模式启动 Grafana。

如果您从二进制文件或 Docker 容器内运行 Grafana，可以通过设置环境变量 GF_DEFAULT_APP_MODE 为 development 来以开发模式启动它。

注意

默认情况下，Grafana 要求对后端插件进行签名。要加载未签名的后端插件，您需要配置 Grafana 以允许未签名的插件。更多信息请参阅插件签名验证。

后端插件的结构

用于构建后端插件的文件夹和文件数据源列于下方：

文件/文件夹	描述
`Magefile.go`	使用 mage 构建文件并非必需，但我们强烈建议您使用它们，以便利用插件 SDK 提供的构建目标。
`/go.mod`	Go 模块依赖。
`/src/plugin.json`	描述插件的 JSON 文件。
`/pkg/main.go`	插件二进制文件的起始点。

plugin.json 文件

所有插件都需要 plugin.json 文件。构建后端插件时，请特别注意以下属性

属性	描述
`backend`	对于后端插件，设置为 `true`。这会告诉 Grafana 在加载插件时应启动一个二进制文件。
`executable`	这是 Grafana 预期启动的可执行文件的名称。请参阅 plugin.json 参考了解详细信息。
`alerting`	如果您的后端数据源支持报警，请设置为 `true`。需要将 `backend` 设置为 `true`。

下一步我们将了解查询端点！

实现数据查询

首先打开 /pkg/plugin/datasource.go 文件。在此文件中，您将看到实现了 backend.QueryDataHandler 接口的 Datasource 结构体。此结构体上的 QueryData 方法是数据源插件执行数据获取的地方。

每个请求包含多个查询，以减少 Grafana 和插件之间的流量。因此您需要遍历查询切片，处理每个查询，然后返回所有查询的结果。

在本教程中，我们提取了一个名为 query 的方法来处理每个查询模型。由于每个插件都有自己独特的查询模型，Grafana 以 JSON 格式将其发送到后端插件。因此插件需要将查询模型 Unmarshal（反序列化）成易于处理的格式。

如您所见，示例只返回静态数字。尝试扩展插件以返回其他类型的数据。

例如，要生成三个时间上等间隔的浮点数，您可以使用以下代码替换生成的两个静态数字

duration := query.TimeRange.To.Sub(query.TimeRange.From)
mid := query.TimeRange.From.Add(duration / 2)

s := rand.NewSource(time.Now().UnixNano())
r := rand.New(s)

lowVal := 10.0
highVal := 20.0
midVal := lowVal + (r.Float64() * (highVal - lowVal))

// add fields.
frame.Fields = append(frame.Fields,
  data.NewField("time", nil, []time.Time{query.TimeRange.From, mid, query.TimeRange.To}),
  data.NewField("values", nil, []float64{lowVal, midVal, highVal}),
)

您可以在我们的文档中阅读更多关于如何构建数据帧的信息。

添加健康检查支持

实现健康检查处理程序允许 Grafana 验证数据源是否已正确配置。

在 Grafana UI 中编辑数据源时，您可以点击 Save & Test 来验证它是否按预期工作。

在此示例数据源中，健康检查有 50% 的成功几率。请确保向用户返回适当的错误消息，告知他们数据源中的配置错误。

打开 /pkg/plugin/datasource.go。在此文件中，您将看到 Datasource 结构体也实现了 backend.CheckHealthHandler 接口。转到 CheckHealth 方法查看如何实现此示例插件的健康检查。

要了解更多信息，请参阅我们示例仓库中的其他健康检查实现。

添加身份验证

实现身份验证使您的插件能够访问受保护的资源，如数据库或 API。要了解更多关于如何使用后端插件进行身份验证的信息，请参阅我们的文档。

启用 Grafana 报警

添加顶级 alerting 属性并将其值设置为 true，以指定您的插件支持 Grafana 报警，例如：

src/plugin.json
{
  ...
  "backend": true,
  "executable": "gpx_simple_datasource_backend",
  "alerting": true,
  "info": {
  ...
}

重启您的 Grafana 实例。
在您的网页浏览器中打开 Grafana。
导航到您创建的数据源，验证是否已支持报警。您应该在设置视图中看到“Alerting supported”消息。

创建报警

注意

以下说明基于 Grafana v10.1.1，请查阅文档中相应版本的报警指导。

打开您在“创建新插件”步骤中创建的仪表板。
编辑现有面板。
点击面板下方的 Alert 选项卡。
点击 Create alert rule from this panel 按钮。
在 Expressions 部分，在 Threshold 表达式 C 中，将 IS ABOVE 设置为 15。
点击 Threshold 表达式 C 上的 Set as alert condition。您的报警现在应该如下图所示。
表达式部分显示 B “减少” 输入：A，函数：最后一个，模式：严格，C 阈值输入：B，高于：15 和报警条件已启用指示器
在 Set alert evaluation behavior 部分，点击 New folder 按钮并创建一个新文件夹来存储评估规则。
然后，点击 New evaluation group 按钮并创建一个新的评估组；选择一个名称并将 Evaluation interval 设置为 10s。
点击 Save rule and exit 按钮。
保存仪表板。一段时间后，报警规则将评估并转换为 Alerting 状态。

并发运行多个查询

注意

此功能仅适用于 Grafana 后端插件 SDK 版本 0.232.0 及更高版本。

默认情况下，单个请求（即单个面板中）中的多个查询会按顺序执行。要并发运行多个查询，您可以使用 SDK 公开的 concurrent.QueryData 函数。

要使用 concurrent.QueryData，请指定如何执行单个查询以及要并发运行的查询数量限制。请注意，最大并发查询数为 10 个。

import (
	...
	"github.com/grafana/grafana-plugin-sdk-go/experimental/concurrent"
	...
)

func (d *Datasource) handleSingleQueryData(ctx context.Context, q concurrent.Query) (res backend.DataResponse) {
  // Implement the query logic here
}

func (d *Datasource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
	return concurrent.QueryData(ctx, req, d.handleSingleQueryData, 10)
}

总结

在本教程中，您为数据源插件创建了后端。

简介​

先决条件​

创建新插件​

故障排除​

Grafana 未加载我的插件​

后端插件的结构​

plugin.json 文件​

实现数据查询​

添加健康检查支持​

添加身份验证​

启用 Grafana 报警​

创建报警​

并发运行多个查询​

总结​

简介