Grafana 的插件开发

我不是女神ヾ 2022-05-12 10:14 240阅读 0赞

<1>推荐一个网址：[http://blog.leanote.com/post/nixon/%E6%8F%92%E4%BB%B6%E5%BC%80%E5%8F%91][http_blog.leanote.com_post_nixon_E6_8F_92_E4_BB_B6_E5_BC_80_E5_8F_91]

Grafana Panel Plugin 开发

# Grafana 插件开发 #

上一次分享提到过Grafana的插件氛围三种类型(Panel, Datasource, App),这一次主要记录Panel类型的插件开发.

## 0. 起手式 ##

根据官网的描述, 插件包一般放在`/var/lib/grafana/plugins`或者`data/plugins`(相对Grafana源码目录). 前者是生产环境, 后者是开发环境. 所以我们这一次选择后者, 毕竟一会儿要从源码修改Grafana的前端代码, 然后启动go语言编写的后端.

> 基础知识准备:   
> angularjs, systemjs, typescript, jquery, echarts, grunt, nodejs and golang.

## 1. 目录结构 ##

先把官网上说明需要的文件目录加上.

> README.md: The only difference from how GitHub renders markdown is that html is not allowed.

实际上并不需要严格按照上述目录存放文件, 关键点在于: 插件目录下需要有`src/`, `dist/`. `src/`中需要有`module.js`和`plugin.json`. 其他开心就好.

所以实际上, 我的目录结构是这样:

## 2. 插件描述文件(.json) ##

然后来认识一个文件, 这个文件是用来描述插件的. 包括插件的**唯一**标识, 名字, 作者, 版本等等. 全文是这样的:

1.  `{`
2.  `"id": "",`
3.  `"type": "",`
4.  `"name": "",`
5.  `"info": {`
6.  `"description": "",`
7.  `"author": {`
8.  `"name": "",`
9.  `"url": ""`
10. `},`
11. `"keywords": [],`
12. `"logos": [`
13. `"small": "",`
14. `"large": ""`
15. `],`
16. `"version": ""`
17. `},`
18. `"dependencies": {`
19. `"grafanaVersion": "",`
20. `"plugins": []`
21. `}`
22. `}`

具体的含义, 参考附录中的官方说明链接. 本次的内容参考源码文件.

## 3. 入口文件 ##

这基本上就是约定, Grafana会从插件包的`dist/`第一个读取的文件就是`module.js`文件. 不管用什么语言编写, 最终都要保证`dist/module.js`可读.

## 4. 可用依赖资源 ##

Grafana的前端模块化方案采用的[Systemjs][]. 如果熟悉任何一种模块化方案都行, 这里的影响并不是很大, 除了需要添加依赖资源. 在插件开发过程中, 开发者是**无法添加任何依赖资源**的. 因为插件是作为Grafana前端整体的一部分在运行. 所有的资源配置都写在Grafana源码目录的`public/app/system.conf.js`文件中, 资源都放在`public/vendor/`目录中.

默认可用资源如下:

1.  `virtual-scroll`
2.  `mousetrap`
3.  `remarkable`
4.  `tether`
5.  `eventemitter3`
6.  `tether-drop`
7.  `moment`
8.  `jquery`
9.  `lodash-src`
10. `lodash`
11. `angular`
12. `bootstrap`
13. `angular-route`
14. `angular-sanitize`
15. `angular-ui`
16. `angular-strap`
17. `angular-dragdrop`
18. `angular-bindonce`
19. `spectrum`
20. `bootstrap-tagsinput`
21. `jquery.flot`
22. `jquery.flot.pie`
23. `jquery.flot.selection`
24. `jquery.flot.stack`
25. `jquery.flot.stackpercent`
26. `jquery.flot.time`
27. `jquery.flot.crosshair`
28. `jquery.flot.fillbelow`
29. `jquery.flot.gauge`
30. `d3`
31. `jquery.flot.dashes`

是的, 像D3, jquery, moment, lodash这些非常有用的图表基础库都有了, 甚至很贴心的连AngularJS全家桶都有. 美中不足的是AngularJS版本偏低: `1.6.1`.

但这一次练习, 我们要用echarts来构建图表. 很遗憾, Grafana没有这项资源. 所以总共需要修改二个地方.

*  将`echarts.min.js`放入`public/vendor/`目录
 *  修改`public/app/system.conf.js`文件, 在`paths`节点中添加代码: `'echarts': 'vendor/echarts.min.js',` 上下文看起来像这样:
    
    1.  `'tether-drop': 'vendor/npm/tether-drop/dist/js/drop.js',`
    2.  `'moment': 'vendor/moment.js',`
    3.  `'echarts': 'vendor/echarts.min.js',`
    4.  `'jquery': 'vendor/jquery/dist/jquery.js',`

## 5. 开始编码 ##

### MetricsPanelCtrl类 ###

准备工作基本完成了, 但是编码之前, 需要认识一个类: `MetricsPanelCtrl`. 这个类的源码文件位于Grafana源码目录下`public/app/features/panel/metrics_panel_ctrl.ts`. `MetricsPanelCtrl`类继承自`PanelCtrl`类, 是我们完成本次Panel类型插件开发必须要用到的. 它主要是解决了以下三个问题:

1.  在进入编辑状态后, 使metrics Tab成为默认面板.
    
    1.  `constructor($scope, $injector) {`
    2.  `super($scope, $injector);`
    3.  `// make metrics tab the default`
    4.  `this.editorTabIndex = 1;`
    5.  `// ... other code`
    6.  `}`
2.  订阅事件:
    
    1.  `this.events.on('refresh', this.onMetricsPanelRefresh.bind(this));`
    2.  `this.events.on('init-edit-mode', this.onInitMetricsPanelEditMode.bind(this));`
    3.  `this.events.on('panel-teardown', this.onPanelTearDown.bind(this));`
3.  提供设置数据源后的响应:
    
    1.  `setDatasource(datasource) {`
    2.  `// ... other code`
    3.   
    4.  `this.panel.datasource = datasource.value;`
    5.  `this.datasourceName = datasource.name;`
    6.  `this.datasource = null;`
    7.  `this.refresh();`
    8.  `}`

### 插件事件 ###

因为文档中并无特别描述, 所以以下是**已知的**插件支持的事件:

*  `refresh` can be used to response when refresh button was clicked.
 *  `init-edit-mode` can be used to add tabs when editing a panel
 *  `panel-teardown` can be used for clean up
 *  `data-received` is an event in that is triggered on data refresh and can be hooked into
 *  `data-snapshot-load` is an event triggered to load data when in snapshot mode.
 *  `data-error` is used to handle errors on dashboard refresh.

### 编写一个controller.js ###

Controller类必须实现link方法或者init方法. 这是Grafana的插件机制决定的. 与此同时, Controller的实例对象也将作为AngularJS组件的上下文对象存在.

1.  `// app/core/directives/plugin_component.ts`
2.  `function getPluginComponentDirective(options) {`
3.  `// other code`
4.  `return function() {`
5.  `return {`
6.  `// other code`
7.  `link: (scope, elem, attrs, ctrl) => {`
8.  `if (ctrl.link) {`
9.  `ctrl.link(scope, elem, attrs, ctrl);`
10. `}`
11. `if (ctrl.init) {`
12. `ctrl.init();`
13. `}`
14. `}`
15. `}`
16. `}`
17. `}`

而这个函数是作为AngularJS的指令处理函数存在的. 所以我们的controller.js看起来至少应该是这样的:

1.  `import { MetricsPanelCtrl } from 'app/plugins/sdk';`
2.   
3.  `export class Controller extends MetricsPanelCtrl {`
4.  `constructor() {`
5.  `// initialize`
6.  `// subscribe events`
7.  `}`
8.   
9.  `link(scope, elem, attrs, ctrl) {`
10. `// impelement linking`
11. `}`
12. `}`

*完整实现细节请参考源码文件.*

是的, 此时还没有界面. 在编写界面之前, 我们先了解一下插件的二种状态.

## 6. 插件状态 ##

插件有二种状态, 一种是只读状态, 一种是编辑状态. 只读状态就是打开一个dashboard时各个Panel表现的状态. 编辑状态是点击”Edit”之后, 进入的可以影响数据源的状态. 我们需要分别为这二种状态编写页面.

*完整实现细节参考源码文件.*

## 7. HTML + CSS ##

Grafana提供一些布局样式和外观样式. 非常不幸, 我没有在官方文档上找到对应的样式说明. 不过幸运的是, 插件目前只有三种, 而且三种都提供了Example代码. 分别是:

[https://github.com/grafana/piechart-panel][https_github.com_grafana_piechart-panel]

[https://github.com/grafana/simple-json-datasource][https_github.com_grafana_simple-json-datasource]

[https://github.com/grafana/kubernetes-app][https_github.com_grafana_kubernetes-app]

这一次练习则是copy的piechart-panel的编辑页面. 用起来有点类似bootstrap的感觉.

好了, 重点来了: **在编写完成界面后, 需要将界面和controller关联在一起.**

只读状态的界面关联方法是在controller.js中声明完Controller类后, 添加静态属性字段:

1.  `Controller.templateUrl = './partials/module.html';`

编辑状态的界面则需要在`init-edit-mode`事件处理函数中注册:

1.  `onInitEditMode() {`
2.  `this.addEditorTab('Options', 'public/plugins/practice-panel/partials/module.editor.html', 2);`
3.  `}`

*完整实现细节参考源码文件.*

## 8. 编译打包 ##

编译Grafana官方使用的是Grunt, 实际上只要按照目录结构来, 用什么打包工具并不重要.

`grunt`

一个练习插件就这么完成了.

## 9. 总结 ##

![success.png][]  
一种数据的四种表现形式. 其中右下角红色的柱状图即本次练习插件.

图表数据Grafana只支持二种, 时序图和非时序图. 非时序图仅返回一个普通的数据结构:

![type\_choice.png][type_choice.png]  
![dev.png][]

## 附录 ##

*  [官方开发指南][Link 1]
 *  [官方插件示例][https_github.com_grafana_piechart-panel]
 *  [插件描述文件说明][Link 2]

[http_blog.leanote.com_post_nixon_E6_8F_92_E4_BB_B6_E5_BC_80_E5_8F_91]: http://blog.leanote.com/post/nixon/%E6%8F%92%E4%BB%B6%E5%BC%80%E5%8F%91
[Systemjs]: https://github.com/systemjs/systemjs
[https_github.com_grafana_piechart-panel]: https://github.com/grafana/piechart-panel
[https_github.com_grafana_simple-json-datasource]: https://github.com/grafana/simple-json-datasource
[https_github.com_grafana_kubernetes-app]: https://github.com/grafana/kubernetes-app
[success.png]: /images/20220512/547014da847b4f2182ab1fdfde785e22.png
[type_choice.png]: /images/20220512/b397e490492d4b909805413c21ca1829.png
[dev.png]: /images/20220512/785f9548bc58429da5857bdac187530d.png
[Link 1]: http://docs.grafana.org/plugins/developing/development/
[Link 2]: http://docs.grafana.org/plugins/developing/plugin.json/