Grafana的Datasource插件开发实践一中介绍了开发datasource需要知道的基本内容。这篇文章中将介绍在项目中具体的开发实践。

Datasource模块

与Grafana的其余部分进行交互，插件文件需要导出以下5个模块：

Datasource  // Required
QueryCtrl  // Required
ConfigCtrl  // Required
QueryOptionsCtrl  // 
AnnotationsQueryCtrl  //

constructor函数

datasource插件与数据源通信，并将数据转换为时间序列。数据源有以下功能：

query(options)  // 用于panel查询数据
testDatasource()  // 用于自定义数据源的页面，测试当前配置的数据源是可用的
annotationQuery(options) // 用于dashboard获取注释信息
metricFindQuery(options) // used by query editor to get metric suggestions.

constructor函数传入的参数有：

constructor(instanceSettings, $q, backendSrv, templateSrv) {}
// instanceSettings对象为：
{
  id: 5,
  jsonData: {
    keepCookies: [],
    tlsAuth: false,
    tlsAuthWithCACert: false,
    tlsSkipVerify: false,
  },
  meta: {
    alerting: false,
    annotations: true,
    baseUrl: "public/plugins/grafana-server-datasource",
    dependencies: {
      grafanaVersion: "3.x.x",
      plugins: [],
    },
    id: "grafana-server-datasource",
    includes: null,
    info: {
      author: {
        name:"liuchunhui",
        url:"https://grafana.com",
      },
      description: "代理服务端作为数据源",
      links: [
        {name: "Github", url: ""},
        {name: "MIT License", url: ""}
      ],
      logos: {
        large:"public/plugins/grafana-server-datasource/img/server-logo.png",
        small:"public/plugins/grafana-server-datasource/img/server-logo.png"
      },
     screenshots:null
     updated:"2018-04-23"
     version:"1.0.0"
    },
    metrics: true,
   module: "plugins/grafana-server-datasource/module",
   name: "代理服务端",
   routes: null,
   type: "datasource",
  }
  name:"代理服务端数据源",
  type:"grafana-server-datasource",
  url:"/api/datasources/proxy/5",
}
// $q 是个函数
// backendSrv对象为：
{
  $http: ƒ p(e),
  $q: ƒ M(t),
  $timeout: ƒ o(o,s,u),
  HTTP_REQUEST_CANCELLED: -1,
  alertSrv: {
   $rootScope: object,
   $timeout: ƒ o(o,s,u)
   list: []
  }
  contextSrv: {
    isEditor: true,
    isGrafanaAdmin: true,
    isSignedIn: true,
    sidemenu: true,
    sidemenuSmallBreakpoint: false,
   user: {  // 当前登录的用户信息
      email:"admin@localhost",
     gravatarUrl:"/avatar/46d229b033af06a191ff2267bca9ae56",
     helpFlags1:0,
     id:1,
     isGrafanaAdmin:true,
     isSignedIn:true,
     lightTheme:true,
     locale:"zh-CN",
     login:"admin",
     name:"admin",
     orgCount:1,
     orgId:1,
     orgName:"Main Org.",
     orgRole:"Admin",
     timezone:"browser",
    },
    version:"5.0.1",
  },
  inFlightRequests:{},
  noBackendCache:true,
}
// templateSrv对象为：
{
  builtIns: {
    __interval:{text: "1s", value: "1s"},
    __interval_ms:{text: "100", value: "100"}
  },
  grafanaVariables: {},
  index:{},
  regex:/\$(\w+)|\[\[([\s\S]+?)(?::(\w+))?\]\]|\${(\w+)(?::(\w+))?}/g
}

query函数

真正去查询数据时要调用的函数。官方提供的数据源有两种不同的结果，time series和table，目前grafana官方所有数据源和面板都支持time series格式，table格式仅由InfluxDB数据源和表格面板支持。我们开发插件时可以自定义类型值，但是要做到开发的datasource插件也适配官方自带的panel插件，那么定义datasource返回的数据格式和grafana的一致。 datasource.query的time series类型响应格式：

[{
   "target":"upper_75",
    "datapoints":[
      [622, 1450754160000],
      [365, 1450754220000]
   ]
}, {
    "target":"upper_90",
    "datapoints":[
      [861, 1450754160000],
      [767, 1450754220000]
    ]
}]

datasource.query的table类型响应格式：

[{
   "columns": [{
      "text": "Time",
        "type": "time",
        "sort": true,
        "desc": true,
   }, {
        "text": "mean",
    }, {
        "text": "sum",
    }],
    "rows": [[
      1457425380000,
        null,
        null
   ], [
      1457425370000,
        1002.76215352,
        1002.76215352
   ]],
    "type": "table"
}]

传递给datasource.query函数的请求对象：

{
   "range": {
      "from": moment,  // 全局时间筛选起始日期
      "raw": {from: "now-7d", to: "now"},
      "to": moment,  // 全局时间筛选结束日期
   },
    "rangeRaw": {
      "from": "now-7d",
      "to": "now",
    },
   "interval": "15m",
    "intervalMs": 900000,
   "targets": [{  // 定义的查询条件们
      "refId": "A",
      "target": "upper_75" 
   }, {
      "refId": "B", 
      "target": "upper_90" 
   }],
   "format": "json",
   "maxDataPoints": 2495, //decided by the panel
    "cacheTimeout": undefined,
    "panelId": 2,
    "timezone": "browser"
}

query函数示例：

query(options) {  // 返回的结果数据，panel插件会通过监听'data-received'获取到
    
    const params = {  // 封装http请求参数
        from: options.range.from.format('x'),
        to: options.range.to.format('x'),
        targets: options.queries,
    };

    return this.doRequest({  // 发起http请求并返回结果
        url: this.url + '/card-data',  // 要制定公共接口规范
        method: 'POST',
        data: params
    });
}


doRequest(options) {
    options.withCredentials = this.withCredentials;
    options.headers = this.headers;
    return this.backendSrv.datasourceRequest(options);  // datasourceRequest()是grafana提供的请求datasource函数
}

testDatasource函数

当用户在添加新数据源时点击Save＆Test按钮，详细信息首先保存到数据库，然后testDatasource调用数据源插件中定义的函数。此函数向数据源发出查询，验证数据源是否配置的正确可用，确保当用户在新仪表板中编写查询时，数据源已正确配置。函数示例：

/**
 * 当保存并测试数据源时会调用该函数
 * 测试数据源是否正常工
 * return { status: "", message: "", title: "" }
 */
testDatasource() {
    return this.doRequest({
        url: this.url + '/',
        method: 'GET',
    }).then(response => {
        if (response.status === 200) {
            return { status: "success", message: "Data source is working", title: "Success" };
        }
    });
}

annotationQuery函数

注释查询，传递给datasource.annotationQuery函数的请求对象：

{
   "range": { 
      "from": "2016-03-04T04:07:55.144Z", 
      "to": "2016-03-04T07:07:55.144Z" },
   "rangeRaw": { 
      "from": "now-3h", 
      "to": "now" 
   },
   "annotation": {
      "datasource": "generic datasource",
      "enable": true,
      "name": "annotation name"
   }
}

datasource.annotationQuery的预期结果：

[{
   "annotation": {
      "name": "annotation name", //should match the annotation name in grafana
       "enabled": true,
       "datasource": "generic datasource",
    },
    "title": "Cluster outage",
    "time": 1457075272576,
    "text": "Joe causes brain split",
    "tags": "joe, cluster, failure"
}]

可以使用grafana平台的数据库存取'注释'

metricFindQuery 函数

ConfigCtrl模块

当用户编辑或创建此类型的新数据源时，该类将被实例化并视为Angular控制器。该类需要一个静态模板或templateUrl变量，该模板或变量将被渲染为此控制器的视图。 ConfigCtrl类中的this对象内容为：

{
  current: {
    name: "代理服务端数据源",  // 数据源名称
    isDefault: true,  // 是否是默认
    type: "grafana-server-datasource",  // 数据源插件的id值
    url: "http://localhost:3001",  // HTTP：数据源对应的url
    access: "proxy",  // HTTP：连接数据源类型，有'direct'和'proxy'两种类型可选
    basicAuth: true,  // Auth：Basic Auth选项
    basicAuthUser: "basic auth user",  // Basic Auth Details：User选项，当basicAuth为true时有效
    basicAuthPassword:"basic auth password",  // Basic Auth Details：Password选项，当basicAuth为true时有效
    withCredentials: true,  // Auth：With Credentials选项
    jsonData: {
     tlsAuth: true,  // Auth：TLS Client Auth选项
      tlsAuthWithCACert: true,  // Auth: With CA Cert选项
      tlsSkipVerify: true,  // Auth: Skip TLS Verification (Insecure)选项值
      keepCookies: ["Advanced Cookoe"],  // Advanced HTTP Settings: cookie的白名单
    },
    secureJsonData: {
      tlsCACert: "TLS Auth CA Cert",  // TLS Auth Details：CA Cert选项，当jsonData下的tlsAuthWithCACert值为true时有效
      tlsClientCert: "TLS Auth Client Cert",  // TLS Auth Details：Client Cert选项，当jsonData下的tlsAuth值为true时有效
      tlsClientKey: "TLS Auth Client Key",  // TLS Auth Details：Client Key选项，当jsonData下的tlsAuth值为true时有效
    },
    secureJsonFields: {},
  },
  meta: {
    baseUrl: "public/plugins/grafana-server-datasource",
    defaultNavUrl: "",
    dependencies: {
      grafanaVersion: "3.x.x",
      plugins: [],
    },
    enabled: false,
    hasUpdate: false,
    id: "grafana-server-datasource",
    includes: null,
    info: {  // plugin.json中配置的信息
     author: {
        name: "liuchunhui", 
        url: "https://grafana.com"
      },
      description: "代理服务端作为数据源",
      links: [
        {name: "Github", url: ""},
        {name: "MIT License", url: ""}
      ],
      logos: {
      large:"public/plugins/grafana-server-datasource/img/server-logo.png",
        small:"public/plugins/grafana-server-datasource/img/server-logo.png"
      },
      screenshots:null,
      updated:"2018-04-23",
      version:"1.0.0"
    },
    jsonData: null,
    latestVersion: "",
    module: "plugins/grafana-server-datasource/module",
    name: "代理服务端",
    pinned: false
    state: "",
    type: "datasource",
}

模板页面中使用grafana封装的angular组件，传入this的current对象，实现HTTP、Auth两个模块的定义：

<datasource-http-settings current="ctrl.current"></datasource-http-settings>

QueryCtrl模块

一个JavaScript类，当用户在面板中编辑指标时，它将被实例化并作为Angular控制器处理。该类必须从app/plugins/sdk.QueryCtrl类继承。该类需要一个静态模板或templateUrl变量，该模板或变量将被渲染为此控制器的视图。当用户在panel面板下，切回到Metrics模块时，会初始化该类。所以我们可以在构造函数中做一些我们自己的事情。比如获取指标维度列表，作为用户筛选的展示条件。

import { QueryCtrl } from 'app/plugins/sdk';
export default class GenericQueryCtrl extends QueryCtrl {
    constructor($scope, $injector) {
        super($scope, $injector);

        // 获取参数列表请求
        this.requestParams().then(response => {
            const targets = response.data.target;
            this.options = response.data.options;
            this.text = response.data.text;
            this.keys = Object.keys(targets);

            for (let key in targets) {
                this.target[key] = this.target[key] || targets[key];

            }
        });
    }
    requestParams() {  // 请求获取参数列表
        const params = {
            header: {
                'Content-Type': 'application/json'
            },
            method: 'GET',
            retry: 0,
            url: this.datasource.url + '/param-list'
        };
        return this.datasource.backendSrv.datasourceRequest(params);  // 使用grafana提供的http请求函数
    }
    onChangeInternal() {  // 刷新面板
        this.panelCtrl.refresh(); // grafana自带方法使面板更新数据
    }

    toggleEditorMode() {  // 是否开启编辑模式
        this.target.rawQuery = !this.target.rawQuery;
    }
}

GenericQueryCtrl.templateUrl = './page/query.html';

QueryCtrl控制器的query.html模板：

<query-editor-row query-ctrl="ctrl" has-text-edit-mode="true">
    <div class="gf-form"
         ng-if="!ctrl.target.rawQuery"
         ng-repeat="key in ctrl.keys">
        <span class="gf-form-label width-7">
            {{ctrl.text[key]}}
        </span>
        <select class="gf-form-input width-25"
                ng-model="ctrl.target[key]"
                ng-change="ctrl.onChangeInternal()">
            <option ng-repeat="option in ctrl.options[key]"
                    value="{{option.name}}">
                {{option.desc}}
            </option>
        </select>
    </div>
    <div ng-if="ctrl.target.rawQuery">
        <textarea class="gf-form-input" rows="5" spellcheck="false" ng-blur="ctrl.onChangeInternal()" />
    </div>
</query-editor-row>

<query-editor-row query-ctrl="ctrl">标签的内容会加入到Add Query模板中，标签中的has-text-edit-mode="true"属性，能开启Toggle Edit Mode功能。 QueryCtrl控制器中的target.rawQuery参数，标记着两种编辑模式的切换，但是这两种模式需要写代码定义。

AnnotationsQueryCtrl模块

当用户在datasource的模板菜单中选择这种类型的数据源时，将被实例化并作为Angular控制器处理的JavaScript类。此类需要一个静态模板或templateUrl变量，该模板或变量将被渲染为此控制器的视图。绑定到此控制器的字段随后会发送到数据库对象annotationQuery函数。在开发插件时能自定义dashboard的Built in query的条件。 AnnotationQueryCtrl代码：

export default class GenericAnnotationsQueryCtrl {}
GenericAnnotationsQueryCtrl.templateUrl = './page/annotationsQuery.html';

annotationsQuery.html代码：

<h5 class="section-heading">注解查询条件设定</h5>
<div class="gf-form-group">
    <div class="gf-form">
        <input type="text" class="gf-form-input" ng-model='ctrl.annotation.query' placeholder="" />
    </div>
</div>

QueryOptionsCtrl模块

一个JavaScript类，当用户在面板中编辑指标时，它将被实例化并作为Angular控制器处理。此控制器负责处理数据源的面板范围设置，如间隔，速率和聚合（如果需要）。此类需要一个静态模板或templateUrl变量，该模板或变量将被渲染为此控制器的视图。

QueryOptionsCtrl代码：

export default class GenericQueryOptionsCtrl {}
GenericQueryOptionsCtrl.templateUrl = './page/queryOptions.html';

queryOptions.html代码：

<section class="grafana-metric-options" >
    <div class="gf-form"></div>
</section>