grafana插件开发快速入门

简介

Panels能够帮助我们通过不同的方式可视化数据，grafana里面已经集成了一些panel，但是我们也可以自定义开发panel，来支持一些官方panel插件不支持的显示。

准备工作

• 安装grafana
• 安装nodejs 12.x
• 安装yarn

npm install yarn -g

环境配置

在开发grafana插件之前，我们先需要配置好grafana的配置环境

grafana将会扫描插件目录，其具体的地址取决于读者的操作系统

1. 在读者电脑新建一个文件夹grafana-plugins，该目录未来为开发插件的工作目录

2. 找到在配置文件（/path/to/grafana/conf/defaults.ini）内的plugins属性，属性值修改成为工作目录的路径

   [paths]
   plugins = "/path/to/grafana-plugins"
    # plugins = D:/grafana-plugins
   

3. 重启grafana加载配置

linux平台，systemctl restart grafana-server
windows平台，任务管理器-》服务-》grafana 右键重新启动

也可以通过docker 启动grafana，具体命令如下：

docker run -d -p 3000:3000 \
  -v "$(pwd)"/grafana-plugins:/var/lib/grafana/plugins \
   --name=grafana grafana/grafana:7.2.0

如果重新添加插件之后需要重启grafana

docker restart grafana

创建一个新的插件

# 进入插件工作目录
cd /path/to/grafana-plugins
# 创建插件
npx @grafana/toolkit plugin:create my-plugin
cd my-plugin
# 下载必要的依赖
yarn install 
# 编译插件
yarn dev 
# 重启grafana 启用插件，这时打开grafana,检查configuration -> plugins，确保系统加载了该插件

image.png

插件剖析

具体插件的代码都不尽相同，但是在我们深入研究之前，我们先看看各个插件共性的部分，每个插件都有plugin.json和module.ts 这2个文件。

plugin.json

grafana开始的时候，将会扫描plugin文件夹下所有子文件下都包含一个plugin.json文件，该文件包含plugin的基本信息，告诉grafana该插件的类型、能力以及依赖：

• type 类型，grafana支持panel,datasource和app
• name用户在插件list中看到的插件名字
• id插件的唯一表示，为了避免和其他插件冲突，最好该名字是grafana账户名开始，可在官网注册你的用户名

更多的plugin.json配置，请查看官网

module.ts

grafana读取了插件的信息之后，需要加载插件，module.ts文件既为加载插件的入口文件，module.ts暴露了插件的实现。

module.ts需要实现如下三个类之一

• PanelPlugin
• DataSourcePlugin
• AppPlugin

panel 插件

从grafana 6开始panel插件使用reactJS组件实现

panel属性

PanelProps 接口暴露panel的运行信息，如轮廓尺寸、当前的时间区间。

我们可以通过props属性访问panel属性

src/SimplePanel.tsx

const { options, data, width, height } = props;

开发流程

下面我们来学习如何开发自己的panel的基本流程，编译grafana然后重启grafana来生效我们的改动

首先我们需要添加panel到dashboard上：

1. 在浏览器上打开grafana.
2. 创建一个新的dashboard，添加一个新的pannel.
3. 从visualizaion类型中选择panel类型.
4. 保存dashboard.

现在我们可以看在页面上看到该panel，尝试着修改panel的代码:

1. 修改文件 SimplePanel.tsx中圆的颜色.
2. 运行yarn dev 编译插件.
3. 在浏览器重新加载，即可看到改变（无需重启grafana）

添加panel配置

有时，我们想为用户提供一些可配置的行为，这时需要panel有参数输入的能力，具体步骤如下：

添加一个配置项

SimpleOptions 是一个用来描述panel 配置对象的一个对象。

在types.ts内添加一个CircleColor 类型来保存用户可以选择的颜色，并在SimpleOptions 内添加color颜色

type SeriesSize = 'sm' | 'md' | 'lg';
type CircleColor = 'red' | 'green' | 'blue';

export interface SimpleOptions {
  text: string;
  showSeriesCount: boolean;
  seriesCountSize: SeriesSize;
  color: CircleColor;
}

添加一个配置控制面板

为了可以配置panel编辑器，我们需要绑定颜色选项和颜色控制器。

grafana支持范围控制器、text输入、开关和radio groups

该场景我们创建一个radio控制器然后绑定可选颜色。

修改文件 src/module.ts,末尾添加如下builder:

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

path熟悉用来绑定这个control到option，我们也可以绑定一个嵌套的控制器，在控制器内options属性声明对应对象即可，如：colors.background.

Grafana builds an options editor for you and displays it in the panel editor sidebar in the Display section.

配置参数的使用

在SimplePanel.tsx文件中添加参数的在图形的应用。
src/SimplePanel.tsx

let color: string;
switch (options.color) {
  case 'red':
    color = theme.palette.redBase;
    break;
  case 'green':
    color = theme.palette.greenBase;
    break;
  case 'blue':
    color = theme.palette.blue95;
    break;
}
Configure the circle to use the color.

<g>
  <circle style={{ fill: color }} r={100} />
</g>

完整的工程请查看：