构建面板插件

简介

面板是 Grafana 的基本构建块之一，它允许您以不同的方式可视化数据。Grafana 已经内置了几种面板类型，并且在 Grafana 插件目录中提供了更多面板。

要添加对其他可视化的支持，您可以创建自己的面板插件。面板是 ReactJS 组件，可以使用 create-plugin 工具进行脚手架搭建。

有关面板的更多信息，请参阅关于面板的文档。

先决条件

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

创建一个新插件

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

在一个新目录中，使用 create-plugin 工具从模板创建一个插件。当提示插件类型时，选择面板:
```
npx @grafana/create-plugin@latest
```
转到您新创建的插件目录
```
cd <your-plugin>
```
安装依赖项
```
npm install
```
构建插件
```
npm run dev
```
启动 Grafana
```
docker compose up
```
打开 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>。create-plugin 工具会根据您对其提示的响应正确配置此项。

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

`module.ts`

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

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

面板插件

面板属性

PanelProps 接口暴露了关于面板的运行时信息，例如面板尺寸和当前时间范围。

您可以通过 props 参数访问面板属性，如您的插件中所见。

src/components/SimplePanel.tsx
export const SimplePanel: React.FC<Props> = ({ options, data, width, height }) => {

开发工作流程

接下来，您将学习更改面板、构建面板以及重新加载 Grafana 以反映您所做更改的基本工作流程。

首先，您需要将您的面板添加到仪表板

将您的面板添加到仪表板

在浏览器中打开 Grafana。默认情况下，Grafana 可通过 https://127.0.0.1:3000 访问。
创建一个新的仪表板。
- 从菜单中，选择 仪表板。
- 在右上角，选择新建 -> 仪表板。
- 选择 添加可视化 以开始配置您的新面板。
配置 TestData 数据源。在数据源配置模态框中，为此仪表板选择 TestData DB 数据源。
搜索并选择您的面板插件。在面板配置视图中，转到右侧的 可视化 列表，搜索您的面板插件，然后选择它。
保存仪表板。

替代方案：使用预置的示例面板仪表板

您还可以通过预配置的仪表板查看您的面板运行情况

转到 仪表板 并选择 Provisioned Sample Panel Dashboard。
- TestData DB 数据源已经为此仪表板配置了示例数据。
要编辑，请在此仪表板中找到您的面板，然后单击面板右上角的菜单（即，三个垂直点）。
从下拉菜单中，选择编辑以自定义或检查面板的设置。

现在您可以查看您的面板了，尝试更改面板插件

在 SimplePanel.tsx 中，更改圆的填充颜色。例如，将其更改为绿色
src/components/SimplePanel.tsx
```
<circle style={{ fill: theme.visualization.getColorByName('green') }} r={100} />
```
保存文件。
在浏览器中，重新加载 Grafana。更改应该会显示出来。

添加面板选项

有时您希望为面板用户提供一个选项来配置插件的行为。通过为您的插件配置面板选项，您的面板将能够接受用户输入。

在上一步中，您在代码中更改了圆的填充颜色。让我们更改代码，以便插件用户可以从面板编辑器配置颜色。

添加一个选项

面板选项在面板选项对象中定义。SimpleOptions 是一个描述选项对象的接口。

在 types.ts 中，添加一个 CircleColor 类型来保存用户可以选择的颜色
```
type CircleColor = 'red' | 'green' | 'blue';
```
在 SimpleOptions 接口中，添加一个名为 color 的新选项
```
color: CircleColor;
```

这是更新后的选项定义

src/types.ts
type SeriesSize = 'sm' | 'md' | 'lg';
type CircleColor = 'red' | 'green' | 'blue';

// interface defining panel options type
export interface SimpleOptions {
  text: string;
  showSeriesCount: boolean;
  seriesCountSize: SeriesSize;
  color: CircleColor;
}

添加一个选项控件

要从面板编辑器更改选项，您需要将 color 选项绑定到选项控件。

Grafana 支持一系列选项控件，例如文本输入、开关和单选按钮组。

让我们创建一个单选按钮控件并将其绑定到 color 选项。

在构建器的末尾添加控件

src/module.ts
.addRadio({
  path: 'color',
  name: 'Circle color',
  defaultValue: 'red',
  settings: {
    options: [
      {
        value: 'red',
        label: 'Red',
      },
      {
        value: 'green',
        label: 'Green',
      },
      {
        value: 'blue',
        label: 'Blue',
      },
    ],
  }
});

path 用于将控件绑定到选项。您可以通过在选项对象中指定完整路径来将控件绑定到嵌套选项，例如 colors.background。

Grafana 会为您构建一个选项编辑器，并在面板编辑器侧边栏的显示部分中显示它。

使用新选项

您快完成了。您已经添加了一个新选项和一个相应的控件来更改值。但是插件尚未使用该选项。让我们改变这一点。

要将选项值转换为当前主题使用的颜色，请在 SimplePanel.tsx 中的 return 语句之前添加以下语句。
src/components/SimplePanel.tsx
```
let color = theme.visualization.getColorByName(options.color);
```
配置圆以使用该颜色。
src/components/SimplePanel.tsx
```
<g>
  <circle style={{ fill: color }} r={100} />
</g>
```

现在，当您在面板编辑器中更改颜色时，圆的填充颜色也会随之更改。

使用数据帧创建动态面板

大多数面板可视化来自 Grafana 数据源的动态数据。在此步骤中，您将为每个序列创建一个圆，每个圆的半径等于序列中的最后一个值。

信息

要在面板中使用来自查询的数据，您需要设置一个数据源。如果您没有可用的数据源，您可以在开发时使用 TestData 数据源。

将面板添加到仪表板时，请配置数据源以动态填充数据。或者，您可以使用 Provisioned Sample Panel Dashboard，它已经配置了示例数据源。

使用预置的示例面板仪表板

Provisioned Sample Panel Dashboard 预配置了 TestData 数据源。此设置包括用于测试和开发的示例数据。示例数据位于 TestData 数据源的 raw_frame 场景中，并包含两个具有相同时间戳的时间序列，如下表所示。该表显示了由时间戳连接的这两个时间序列

时间戳	标签 1	值 1	标签 2	值 2
2020-12-31 19:00:00	A	10	A	40
2020-12-31 20:00:00	B	20	B	50
2020-12-31 21:00:00	C	15	C	45
2020-12-31 22:00:00	D	25	D	55
2020-12-31 23:00:00	E	30	E	60

此设置允许您使用真实的示例数据测试面板的动态元素，这些数据结构化为多个序列，以实现更复杂的可视化。

面板中数据源查询的结果在面板组件内的 data 属性中可用。

const { data } = props;

data.series 包含从数据源查询返回的序列。每个序列都表示为称为数据帧的数据结构。数据帧类似于表格，其中数据按列或字段存储，而不是按行存储。字段中的每个值共享相同的数据类型，例如字符串、数字或时间。

这是一个数据帧的示例，其中包含时间字段 Time 和数字字段 Value

时间	值
1589189388597	32.4
1589189406480	27.2
1589189513721	15.0

预置示例面板仪表板** 示例数据

时间戳	标签 1	值 1	标签 2	值 2
2020-12-31 19:00:00	A	10	A	40
2020-12-31 20:00:00	B	20	B	50
2020-12-31 21:00:00	C	15	C	45
2020-12-31 22:00:00	D	25	D	55
2020-12-31 23:00:00	E	30	E	60

让我们看看如何从数据帧中检索数据并在可视化中使用它。

通过将以下内容添加到 SimplePanel.tsx 中的 return 语句之前，获取类型为 number 的每个字段的最后一个值
src/components/SimplePanel.tsx
```
const radii = data.series
  .map((series) => series.fields.find((field) => field.type === 'number'))
  .map((field) => field?.values.get(field.values.length - 1));
```
radii 将包含从数据源查询返回的每个序列中的最后一个值。您将使用这些值来设置每个圆的半径。

将 svg 元素更改为以下内容

src/components/SimplePanel.tsx
<svg
  className={styles.svg}
  width={width}
  height={height}
  xmlns="http://www.w3.org/2000/svg"
  xmlnsXlink="http://www.w3.org/1999/xlink"
  viewBox={`0 -${height / 2} ${width} ${height}`}
>
  <g fill={color}>
    {radii.map((radius, index) => {
      const step = width / radii.length;
      return <circle r={radius} transform={`translate(${index * step + step / 2}, 0)`} />;
    })}
  </g>
</svg>

请注意我们如何为 radii 中的每个值创建一个 <circle> 元素

src/components/SimplePanel.tsx
{
  radii.map((radius, index) => {
    const step = width / radii.length;
    return <circle r={radius} transform={`translate(${index * step + step / 2}, 0)`} />;
  });
}

我们在此处使用 transform 在面板中水平分布圆。

重新构建您的插件并通过向面板添加多个查询来尝试它。刷新仪表板。

如果您想了解有关数据帧的更多信息，请查看我们的数据帧简介。

总结

在本教程中，您学习了如何为您的仪表板创建自定义可视化。

简介​

先决条件​

创建一个新插件​

插件的结构​

plugin.json​

module.ts​

面板插件​

面板属性​

开发工作流程​

将您的面板添加到仪表板​

替代方案：使用预置的示例面板仪表板​

添加面板选项​

添加一个选项​

添加一个选项控件​

使用新选项​

使用数据帧创建动态面板​

使用预置的示例面板仪表板​

总结​

简介