构建数据源插件

简介

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

在本教程中，您将

• 构建数据源以可视化正弦波
• 使用查询编辑器构造查询
• 使用配置编辑器配置您的数据源

先决条件

• Grafana v10.0 或更高版本
• LTS 版本的 Node.js

创建一个新的插件

Grafana create-plugin 工具 是一个 CLI 应用程序，它简化了 Grafana 插件开发，让您可以专注于代码。该工具为您提供了一个启动插件、所有必需的配置以及使用 Docker Compose 开发环境的脚手架。

1. 在新的目录中，使用 create-plugin 工具从模板创建一个插件。当提示插件类型时，选择数据源:

   npx @grafana/create-plugin@latest

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

   cd <your-plugin>

3. 安装依赖项

   npm install

4. 构建插件

   npm run dev

5. 启动 Grafana

   docker compose up
6. 打开 Grafana，默认情况下 https://127.0.0.1:3000/，然后转到 管理 > 插件。确保您的数据源插件已在此。

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

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

要了解如何创建后端数据源插件，请参阅构建数据源后端插件

插件的构造

您创建的每个插件至少需要两个文件：plugin.json和src/module.ts。

plugin.json

当Grafana启动时，它会扫描插件目录中包含plugin.json文件的任何子目录。该plugin.json文件包含有关您插件的信息，并告知Grafana您的插件需要哪些功能和依赖项。

虽然某些插件类型可能有特定的配置选项，但让我们看看必填的选项

• type告诉Grafana期望什么类型的插件。Grafana支持三种类型的插件：panel、datasource和app。
• name是用户在插件列表中看到的内容。如果您正在创建数据源，这通常是它连接到的数据库的名称，例如Prometheus、PostgreSQL或Stackdriver。
• id唯一标识您的插件，应遵循以下命名约定：<$organization-name>-<$plugin-name>-<$plugin-type>。创建插件工具会根据您对其提示的响应正确配置此选项。

要查看plugin.json的所有可用配置设置，请参阅plugin.json架构。

module.ts

在发现您的插件后，Grafana会加载module.js文件，这是您插件的入口点。module.js公开了您插件的实现，这取决于您正在构建的插件类型。

具体来说，src/module.ts需要导出一个继承自GrafanaPlugin的类，可以是以下任何一种

• PanelPlugin
• DataSourcePlugin
• AppPlugin

数据源插件

在Grafana中的数据源必须扩展DataSourceApi接口，这需要您定义两个方法：query和testDatasource。

query方法

query方法是任何数据源插件的核心。它接受用户的查询，从外部数据库检索数据，并以Grafana能识别的格式返回数据。

async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse>

options对象包含用户创建的查询，或目标，以及上下文信息，如当前时间间隔。使用这些信息来查询外部数据库。

测试您的数据源

testDatasource实现了您数据源的健康检查。例如，当用户在更改连接设置后点击保存并测试按钮时，Grafana会调用此方法。

async testDatasource()

有关前端数据源中健康检查的示例，请参阅我们的datasource-http插件。

返回数据帧

存在无数种不同的数据库，每种都有自己的查询数据方式。为了能够支持所有不同的数据格式，Grafana将数据合并到一个统一的数据结构中，称为数据帧。

让我们看看如何从query方法中创建和返回一个数据帧。在这个步骤中，你需要将启动插件中的代码更改，以返回一个正弦波。

1. 在当前的query方法中，删除map函数内部的代码。

   query方法现在看起来像这样

   src/datasource.ts

   async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse> {
     const { range } = options;
     const from = range!.from.valueOf();
     const to = range!.to.valueOf();
   
     const data = options.targets.map(target => {
       // Your code goes here.
     });
   
     return { data };
   }

2. 在map函数中，使用lodash/defaults包为未设置的查询属性设置默认值

   src/datasource.ts

   import defaults from 'lodash/defaults';
   
   const query = defaults(target, defaultQuery);

3. 在datasource.ts顶部创建一个默认查询

   src/datasource.ts

   export const defaultQuery: Partial<MyQuery> = {
     constant: 6.5,
   };

4. 创建一个具有时间字段和数字字段的数据帧

   src/datasource.ts

   const frame = createDataFrame({
     refId: query.refId,
     fields: [
       { name: 'time', type: FieldType.time },
       { name: 'value', type: FieldType.number },
     ],
   });

   refId需要被设置，以告诉Grafana哪个查询生成了这个数据帧。

接下来，我们将实际值添加到数据帧中。不用担心用于计算值的数学。

1. 创建一些辅助变量

   src/datasource.ts

   // duration of the time range, in milliseconds.
   const duration = to - from;
   
   // step determines how close in time (ms) the points will be to each other.
   const step = duration / 1000;

2. 将值添加到数据帧中

   src/datasource.ts

   for (let t = 0; t < duration; t += step) {
     frame.add({ time: from + t, value: Math.sin((2 * Math.PI * t) / duration) });
   }

   frame.add()接受一个对象，其中键对应数据帧中每个字段的名称。

3. 返回数据帧

   src/datasource.ts

   return frame;

4. 通过创建一个新的数据源实例并构建仪表板来尝试一下。

你的数据源现在正在发送Grafana可以可视化的数据帧。接下来，我们将探讨如何通过定义一个查询来控制正弦波的频率。

信息

在这个例子中，我们是从当前的时间范围生成时间戳。这意味着无论你使用什么时间范围，你都会得到相同的图表。在实践中，你会使用数据库返回的时间戳。

定义一个查询

大多数数据源提供了一种查询特定数据的方法。MySQL和PostgreSQL使用SQL，而Prometheus有自己的查询语言，称为PromQL。无论你的数据库使用什么查询语言，Grafana都让你可以构建对其的支持。

通过实现自己的查询编辑器（一个允许用户通过用户友好的图形界面构建自己的查询的React组件）来为你的数据源添加对自定义查询的支持。

查询编辑器可以是一个简单的文本字段，用户在其中编辑原始查询文本，或者它可以提供一个更用户友好的表单，带有下拉菜单和开关，该表单随后被转换为在发送到数据库之前发送的原始查询文本。

定义查询模型

设计你的查询编辑器的第一步是定义它的查询模型。查询模型定义了用户输入到你的数据源的内容。

我们希望能够控制正弦波的频率，所以让我们添加另一个属性。

1. 在查询模型中添加一个名为frequency的新数字属性

   src/types.ts

   export interface MyQuery extends DataQuery {
     queryText?: string;
     constant: number;
     frequency: number;
   }

2. 为新frequency属性设置一个默认值

   src/types.ts

   export const defaultQuery: Partial<MyQuery> = {
     constant: 6.5,
     frequency: 1.0,
   };

将模型绑定到一个表单

现在您已经定义了要支持的查询模型，下一步是将模型绑定到表单。从 grafana/ui 的 FormField 是一个文本字段组件，允许您注册一个监听器，该监听器会在表单字段值变化时被调用。

1. 从 query 对象中定义 frequency 并将一个新的表单字段添加到查询编辑器中，以便在 render 方法中控制新的频率属性。

   src/components/QueryEditor.tsx

   const { queryText, constant, frequency } = query;
   
   <InlineField label="Frequency" labelWidth={16}>
     <Input onChange={onFrequencyChange} value={frequency || ''} />
   </InlineField>;

2. 为新的属性添加事件监听器。

   src/components/QueryEditor.tsx

   const onFrequencyChange = (event: ChangeEvent<HTMLInputElement>) => {
     onChange({ ...query, frequency: parseFloat(event.target.value) });
     // executes the query
     onRunQuery();
   };

   已注册的监听器 onFrequencyChange 调用 onChange 以更新当前查询，使其包含表单字段的值。

   onRunQuery(); 告诉 Grafana 在每次更改后运行查询。对于快速查询，这建议提供更响应的体验。

使用属性

新的查询模型现在可以在我们的 query 方法中使用。

1. 在 query 方法中，使用 frequency 属性来调整我们的方程。

   src/datasource.ts

   frame.add({ time: from + t, value: Math.sin((2 * Math.PI * query.frequency * t) / duration) });

2. 通过更改您面板的查询中的频率来尝试。

启用数据源配置

要访问特定的数据源，您通常需要配置诸如主机名、凭据或身份验证方法等项。一个 配置编辑器 允许您的用户配置数据源插件以满足他们的需求。

配置编辑器的外观类似于查询编辑器，因为它定义了一个模型并将其绑定到表单。

由于在我们的正弦波示例中实际上并未连接到外部数据库，因此我们并不真的需要很多选项。但是，为了向您展示您可以如何添加选项，我们将添加 波形分辨率 作为选项。

分辨率控制数据点之间的时间间隔有多近。更高的分辨率意味着更接近的点，但这会以处理更多数据为代价。

定义选项模型

1. 将一个新的数字属性 resolution 添加到选项模型。

   src/types.ts

   export interface MyDataSourceOptions extends DataSourceJsonData {
     path?: string;
     resolution?: number;
   }

将模型绑定到表单

就像查询编辑器一样，配置编辑器中的表单字段在值变化时调用已注册的监听器。

1. 将一个新的表单字段添加到查询编辑器中，以控制新的分辨率选项。

   src/components/ConfigEditor.tsx

   <InlineField label="Resolution" labelWidth={12}>
     <Input onChange={onResolutionChange} value={jsonData.resolution || ''} placeholder="Enter a number" width={40} />
   </InlineField>

2. 为新的选项添加事件监听器。

   src/components/ConfigEditor.tsx

   const onResolutionChange = (event: ChangeEvent<HTMLInputElement>) => {
     const jsonData = {
       ...options.jsonData,
       resolution: parseFloat(event.target.value),
     };
     onOptionsChange({ ...options, jsonData });
   };

   onResolutionChange 监听器调用 onOptionsChange 以使用表单字段的值更新当前选项。

使用选项

1. 为 DataSource 类创建一个名为 resolution 的属性。

   src/datasource.ts

   export class DataSource extends DataSourceApi<MyQuery, MyDataSourceOptions> {
     resolution: number;
   
     constructor(instanceSettings: DataSourceInstanceSettings<MyDataSourceOptions>) {
       super(instanceSettings);
   
       this.resolution = instanceSettings.jsonData.resolution || 1000.0;
     }
   
     // ...

2. 在 query 方法中，使用 resolution 属性来更改我们计算步长的方式。

   src/datasource.ts

   const step = duration / this.resolution;

3. 通过配置新的数据源并更改分辨率的值来尝试。

摘要

在本教程中，您构建了一个完整的 Grafana 数据源插件，该插件使用查询编辑器来控制要可视化的数据。您添加了数据源选项，通常用于设置连接选项等。

了解更多

从外部API获取数据

大多数Grafana的数据源将返回来自外部API的数据。本教程尝试保持简单，不需要额外服务。要了解如何实现，请使用datasource-http 示例。

此示例展示了如何使用来自getBackendSrv 函数，该函数位于grafana-runtime 包。

虽然您可以使用类似axios 或 Fetch API 的工具进行请求，但我们建议使用 getBackendSrv，因为它通过Grafana服务器代理请求，而不是直接从浏览器发起请求。在向外部API发起认证请求时，我们强烈推荐这样做。有关外部请求认证的更多信息，请参阅为数据源插件添加认证。

提高插件质量

要了解更多关于高级插件开发主题，请参阅以下内容

• 添加变量支持
• 添加注释支持
• 添加Explore查询支持
• 构建日志数据源