跳转到主要内容

构建数据源后端插件

介绍​

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

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

在本教程中，您将

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

先决条件​

创建一个新的插件​

Grafana 的create-plugin 工具是一个命令行应用程序，它可以简化 Grafana 插件的开发，使您能够专注于代码。该工具使用 Docker Compose 为您搭建了一个初始插件、所有的必需配置和一个开发环境。

  1. 在新目录中，使用 create-plugin 工具从一个模板创建一个插件。当提示插件类型时，选择 并回答“您想要插件的后端部分吗？”

    npx @grafana/create-plugin@latest

  2. 转到您新创建插件的目录

    cd <your-plugin>

  3. 安装依赖项

    npm install

  4. 构建插件前端

    npm run dev

  5. 在新的终端窗口中，构建插件后端

    mage -v build:linux

  6. 启动 Grafana

    docker compose up
  7. 打开 Grafana，默认情况下为 https://127.0.0.1:3000/，然后转到 管理 > 插件。确保您的插件已经在那里。存在。

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

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

现在，让我们验证您迄今为止构建的插件是否可以在创建新数据源时在 Grafana 中使用。

  1. 在侧边菜单中，转到 连接 > 数据源。
  2. 点击 添加数据源。
  3. 搜索您新创建的插件名称并选择它。
  4. 输入一个名称，然后点击 保存 & 测试。如果发生“随机错误”，请忽略它 - 这是下面进一步解释的 健康检查 的结果。

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

要将数据源添加到仪表板中

  1. 创建一个新仪表板并添加一个新的面板。
  2. 在查询选项卡中，选择您刚刚创建的数据源。将渲染一个以两个数据点为一组的系列线条图。
  3. 保存仪表板。

故障排除​

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 以 允许未签名的插件。有关更多信息，请参阅 插件签名验证。

后端插件结构​

用于构建数据源后端的文件夹和文件包括文件/文件夹

描述description
Magefile.go使用 mage 构建文件不是必需的，但我们强烈建议使用它们，以便您可以使用由插件 SDK 提供的构建目标。
/go.modGo 模块依赖。
/src/plugin.json描述插件的 JSON 文件。
/pkg/main.go插件二进制的起点。

plugin.json 文件​

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

属性description
后端将此属性设置为true用于后端插件。这告诉Grafana在加载插件时应该启动一个二进制文件。
可执行文件这是Grafana期望启动的可执行文件名称。有关详细信息，请参考plugin.json参考。
警报如果您的后端数据源支持警报，请将其设置为true。需要将backend设置为true。

下一步我们将查看查询端点！

实现数据查询。

我们从打开/pkg/plugin/datasource.go文件开始。在这个文件中，您将看到实现了后端.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中编辑数据源时，您可以通过保存并测试来验证它是否按预期工作。

在本示例数据源中，健康检查成功的概率是50%。请确保返回适当的错误消息给用户，告知他们数据源中哪些配置错了。

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

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

添加认证。

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

启用Grafana警报。

  1. 将顶级alerting属性设置为true以指定您的插件支持Grafana警报，例如：

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

  2. 重新启动您的Grafana实例。

  3. 在您的网页浏览器中打开Grafana。

  4. 通过导航到您创建的数据源来验证现在是否支持警报。您应该在设置视图中看到“警报支持”消息。

创建一个警报。

备注

以下说明基于Grafana v10.1.1，请咨询文档以获取相应版本的指导。

  1. 在“创建新插件”步骤中打开您之前创建的仪表板。
  2. 编辑现有面板。
  3. 单击面板下方的“警报”标签。
  4. 单击“从该面板创建警报规则”按钮。
  5. 在“表达式”部分中，在“阈值”表达式C中，将“IS ABOVE”设置为15。
  6. 在“阈值”表达式C上单击“设置为警报条件”。您的警报现在应该如下所示。
    Expression section showing B &quot;reduce&quot; with Input: A, Function: Last, Mode: Strict, C Threshold with Input: B, Is Above: 15 and Alert Condition enabled indicator
    显示表达式部分的B "减少"与输入：A，函数：Last，模式：严格，C阈值与输入：B，Is Above：15和警报条件启用指示器
  7. 在“设置警报评估行为”部分中，单击“新建文件夹”按钮，创建一个新的文件夹以存储评估规则。
  8. 然后，单击“新建评估组”按钮，创建一个新的评估组；选择一个名称并将“评估间隔”设置为10s。
  9. 单击“保存规则并退出”按钮。
  10. 保存仪表板。一段时间后，警报规则将进行评估并过渡到“警报”状态。

同时运行多个查询​

备注

此功能仅适用于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)
}

总结​

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