跳到主要内容

构建数据源插件

介绍​

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

在本教程中，您将

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

先决条件​

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

创建新插件​

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

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

    npx @grafana/create-plugin@latest

  2. 进入新创建的插件目录

    cd <your-plugin>

  3. 安装依赖项

    npm install

  4. 构建插件

    npm run dev

  5. 启动 Grafana

    docker compose up

  6. 打开 Grafana（默认地址为 https://:3000），然后转到 Administration > Plugins。确保您的datasource插件已列出。

您还可以通过检查日志来验证 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>。create-plugin 工具会根据您的提示响应正确配置此项。

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

module.ts​

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

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

数据源插件​

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

query 方法​

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

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

options 对象包含用户发出的查询（或称为 targets），以及上下文信息，例如当前时间间隔。使用此信息来查询外部数据库。

测试您的数据源​

testDatasource 实现数据源的健康检查。例如，每当用户更改连接设置后点击 Save & Test 按钮时，Grafana 就会调用此方法。

async testDatasource()

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

返回 Data frames​

数据库种类繁多，每种都有自己的数据查询方式。为了支持所有不同的数据格式，Grafana 将数据整合为一种称为 data frames 的统一数据结构。

让我们看看如何从 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 可以可视化的数据帧。接下来，我们将看看如何通过定义一个 query 来控制正弦波的频率。

信息

在此示例中，我们根据当前时间范围生成时间戳。这意味着无论您使用什么时间范围，都会得到相同的图表。在实际应用中，您应该使用数据库返回的时间戳。

定义查询​

大多数数据源都提供查询特定数据的方式。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,
    };

将模型绑定到表单​

定义了要支持的查询模型后，下一步是将模型绑定到表单。FormField 是 grafana/ui 中的一个文本字段组件，它允许您注册一个监听器，当表单字段的值发生变化时将调用该监听器。

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

    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 示例。

此示例展示了如何使用来自 grafana-runtime 包的 getBackendSrv 函数。

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

提升插件质量​

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