构建一个面板插件

介绍

面板是你可以在 Grafana 中以不同方式可视化数据的基础构建块之一。Grafana 已包含几种类型的面板，Grafana 插件目录中还有更多可用的面板。

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

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

前提条件

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

创建新插件

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

在一个新目录中，使用 create-plugin 工具从模板创建插件。当提示插件类型时，选择panel:
```
npx @grafana/create-plugin@latest
```
进入新创建的插件目录
```
cd <your-plugin>
```
安装依赖项
```
npm install
```
构建插件
```
npm run dev
```
启动 Grafana
```
docker compose up
```
打开 Grafana（默认地址为 https://:3000），然后前往 Administration > Plugins。确保你的panel插件在那里。

你也可以通过检查日志来验证 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 唯一标识你的插件，应遵循此命名约定：<$组织名称>-<$插件名称>-<$插件类型>。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。默认情况下，可以通过 https://:3000 访问 Grafana。
创建新仪表盘。
- 从菜单中，选择 Dashboards。
- 在右上角，选择 New -> Dashboard。
- 选择 Add Visualization 开始配置你的新面板。
配置 TestData 数据源。在数据源配置模态框中，为该仪表盘选择 TestData DB 数据源。
搜索并选择你的面板插件。在面板配置视图中，转到右侧的 Visualization 列表，搜索你的面板插件并选择它。
保存仪表盘。

备选方案：使用预配置的样本面板仪表盘

你也可以通过预配置的仪表盘查看你的面板运行情况

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

现在你可以查看你的面板了，尝试对面板插件进行更改

在 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 会为你构建一个选项编辑器，并将其显示在面板编辑器侧边栏的 Display 部分。

使用新选项

你快完成了。你已经添加了一个新选项和一个相应的控件来更改值。但插件还没有使用这个选项。让我们来改变这一点。

要将选项值转换为当前主题使用的颜色，请在 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 数据源。

将面板添加到仪表盘时，为其配置数据源以动态填充数据。或者，你可以使用已配置样本数据源的预配置样本面板仪表盘。

使用预配置的样本面板仪表盘

预配置样本面板仪表盘预先配置了 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​

面板插件​

面板属性​

开发工作流程​

将你的面板添加到仪表盘​

备选方案：使用预配置的样本面板仪表盘​

添加面板选项​

添加选项​

添加选项控件​

使用新选项​

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

使用预配置的样本面板仪表盘​

总结​

介绍