[iotdb] branch master updated: [IOTDB-2619][User Docs] Grafana Plugin: Alerting (#5605)

Wed, 20 Apr 2022 00:34:17 -0700 

This is an automated email from the ASF dual-hosted git repository.

rong pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git


The following commit(s) were added to refs/heads/master by this push:
     new 1b6a0bc26b [IOTDB-2619][User Docs] Grafana Plugin: Alerting  (#5605)
1b6a0bc26b is described below

commit 1b6a0bc26beecfb3db5813a9ecd9ae989ac17047
Author: CloudWise-Lukemiao 
<[email protected]>
AuthorDate: Wed Apr 20 15:34:03 2022 +0800

    [IOTDB-2619][User Docs] Grafana Plugin: Alerting  (#5605)
    
    Co-authored-by: Steve Yurong Su <[email protected]>
---
 .../Ecosystem Integration/Grafana Plugin.md        | 143 ++++++++++++++++++---
 1 file changed, 122 insertions(+), 21 deletions(-)

diff --git a/docs/zh/UserGuide/Ecosystem Integration/Grafana Plugin.md 
b/docs/zh/UserGuide/Ecosystem Integration/Grafana Plugin.md
index 7d5088b1ac..57c0b8a933 100644
--- a/docs/zh/UserGuide/Ecosystem Integration/Grafana Plugin.md 
+++ b/docs/zh/UserGuide/Ecosystem Integration/Grafana Plugin.md 
@@ -38,9 +38,17 @@ Grafana 是开源的指标量监测和可视化工具，可用于展示时序数
 * Grafana 组件下载地址：https://grafana.com/grafana/download
 * 版本 >= 7.0.0
 
+#### grafana-plugin 获取
 
+##### 方案一 grafana-plugin 下载
 
-#### grafana-plugin 下载
+二进制文件下载地址：https://iotdb.apache.org/zh/Download/
+
+##### 方案二 grafana-plugin 单独编译
+
+我们需要编译 IoTDB 仓库 `grafana-plugin` 目录下的前端工程并生成 `dist` 目标目录，具体执行流程如下。
+
+源码下载
 
 * 插件名称: grafana-plugin
 * 下载地址: https://github.com/apache/iotdb.git
@@ -51,14 +59,6 @@ Grafana 是开源的指标量监测和可视化工具，可用于展示时序数
 git clone https://github.com/apache/iotdb.git
 ```
 
-
-
-#### grafana-plugin 编译
-
-##### 方案一
-
-我们需要编译 IoTDB 仓库 `grafana-plugin` 目录下的前端工程并生成 `dist` 目标目录，具体执行流程如下。
-
 您可以采取下面任意一种编译方式：
 
 * 使用 maven 编译，在 `grafana-plugin` 目录下执行：
@@ -67,21 +67,39 @@ git clone https://github.com/apache/iotdb.git
 mvn install package -P compile-grafana-plugin
 ```
 
-* 或使用 yarn 编译，在 `grafana-plugin` 目录下执行：
+* 或使用命令编译，在 `grafana-plugin` 目录下执行：
 
 ```shell
 yarn install
 yarn build
+go get -u github.com/grafana/grafana-plugin-sdk-go
+go mod tidy
+mage -v
+```
+在使用go get -u 命令时有可能会报如下错误，这时我们需要执行`go env -w 
GOPROXY=https://goproxy.cn`，再执行`go get -u 
github.com/grafana/grafana-plugin-sdk-go`
+```
+go get: module github.com/grafana/grafana-plugin-sdk-go: Get 
"https://proxy.golang.org/github.com/grafana/grafana-plugin-sdk-go/@v/list": 
dial tcp 142.251.42.241:443: i/o timeout
 ```
 
 如果编译成功，我们将看到生成的目标文件夹 `dist`，它包含了编译好的 Grafana 前端插件：
 
 <img style="width:100%; max-width:333px; max-height:545px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/grafana-plugin-build.png?raw=true";>
 
-##### 方案二
+##### 方案三 IoTDB 的分发包完整编译
 
 我们也可以通过执行 IoTDB 项目的**打包指令**获取 `grafana-plugin ` 的前端工程和其他配套的 IoTDB 可执行文件。
 
+源码下载
+
+* 插件名称: grafana-plugin
+* 下载地址: https://github.com/apache/iotdb.git
+
+执行下面的命令：
+
+```shell
+git clone https://github.com/apache/iotdb.git
+```
+
 在 IoTDB 仓库的根目录下执行：
 
 ```shell
@@ -210,21 +228,24 @@ FROM 输入框中的内容必须是时间序列的前缀路径，比如 `root.sg
 
 WHERE 输入框为非必须填写项目，填写内容应当是查询的过滤条件，比如 `time > 0`  或者 `s1 < 1024 and s2 > 1024`。
 
-CONTROL 输入框为非必须填写项目，填写内容应当是控制查询类型、输出格式的特殊子句，下面是 CONTROL 输入框中一些合法的输入举例：
+CONTROL 输入框为非必须填写项目，填写内容应当是控制查询类型、输出格式的特殊子句。其中GROUP BY 
输入框支持使用grafana的全局变量来获取当前时间区间变化$__from(起始时间)、$__to(结束时间)，下面是 CONTROL 
输入框中一些合法的输入举例：
 
-*  `group by ([2017-11-01T00:00:00, 2017-11-07T23:00:00), 1d)`
-*  `group by ([2017-11-01 00:00:00, 2017-11-07 23:00:00), 3h, 1d)`
-*  `GROUP BY([2017-11-07T23:50:00, 2017-11-07T23:59:00), 1m) FILL 
(PREVIOUSUNTILLAST)` 
-*  `GROUP BY([2017-11-07T23:50:00, 2017-11-07T23:59:00), 1m) FILL (PREVIOUS, 
1m)`
-*  `GROUP BY([2017-11-07T23:50:00, 2017-11-07T23:59:00), 1m) FILL (LINEAR, 5m, 
5m)`
-*  `group by ((2017-11-01T00:00:00, 2017-11-07T23:00:00], 1d), level=1`
-*  `group by ([0, 20), 2ms, 3ms), level=1`
+*  `GROUP BY ([$__from, $__to), 1d)`
+*  `GROUP BY ([$__from, $__to),3h,1d)`
+*  `GROUP BY ([2017-11-01T00:00:00, 2017-11-07T23:00:00), 1d)`
+*  `GROUP BY ([2017-11-01 00:00:00, 2017-11-07 23:00:00), 3h, 1d)`
+*  `GROUP BY ([$__from, $__to), 1m) FILL (PREVIOUSUNTILLAST)`
+*  `GROUP BY ([2017-11-07T23:50:00, 2017-11-07T23:59:00), 1m) FILL 
(PREVIOUSUNTILLAST)` 
+*  `GROUP BY ([2017-11-07T23:50:00, 2017-11-07T23:59:00), 1m) FILL (PREVIOUS, 
1m)`
+*  `GROUP BY ([2017-11-07T23:50:00, 2017-11-07T23:59:00), 1m) FILL (LINEAR, 
5m, 5m)`
+*  `GROUP BY ((2017-11-01T00:00:00, 2017-11-07T23:00:00], 1d), LEVEL=1`
+*  `GROUP BY ([0, 20), 2ms, 3ms), LEVEL=1`
 
 提示：为了避免OOM问题，不推荐使用select * from root.xx.** 这种语句在Grafana plugin中使用。
 
 #### 变量与模板功能的支持
 
-本插件支持 Grafana 的变量与模板（ https://grafana.com/docs/grafana/v7.0/variables/）功能。
+本插件支持 Grafana 的变量与模板功能。
 
 创建一个新的 Panel 后，点击右上角的设置按钮，如下图所示：
 
@@ -234,7 +255,7 @@ CONTROL 输入框为非必须填写项目，填写内容应当是控制查询类
 
 <img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/addvaribles.png?raw=true";>
 
-输入 `Name`，`Label`，和 `Query`， 点击 `Update` 按钮，如下图所示：
+示例一：输入 `Name`，`Label`，选择Type的`Query`、在Query 中输入show child paths xx ， 点击 
`Update` 按钮，如下图所示：
 
 <img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/variblesinput.png?raw=true";>
 
@@ -242,7 +263,87 @@ CONTROL 输入框为非必须填写项目，填写内容应当是控制查询类
 
 <img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/applyvariables.png?raw=true";>
 
+示例二：变量嵌套使用，如下图所示
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/variblesinput2.png?raw=true";>
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/variblesinput2-1.png?raw=true";>
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/variblesinput2-2.png?raw=true";>
+
+
+示例三：函数变量使用，如下图所示
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/variablesinput3.png?raw=true";>
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/variablesinput3-1.png?raw=true";>
+
+上图中Name 是变量名称也是将来我们在panel中使用的变量名称，Label是变量的展示名称如果为空就显示Name的变量反之则显示Label的名称，
+Type下拉中有Query、Custom、Text box、Constant、DataSource、Interval、Ad hoc 
filters等这些都可以在IoTDB的Grafana Plugin 中使用
+更加详细介绍用法请查看官方手册(https://grafana.com/docs/grafana/latest/variables/)
+
+除了上面的示例外，还支持下面这些语句:
+*  `show storage group`
+*  `show timeseries`
+*  `show child nodes`
+*  `show all ttl`
+*  `show latest timeseries`
+*  `show devices`
+*  `select xx from root.xxx limit xx 等sql 查询`
+
+#### 告警功能
+本插件支持 Grafana alert功能。
+
+1、在 Grafana 侧栏中，将光标悬停在`Alerting`图标上，然后单击`Notification channels`。
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alerting1.png?raw=true";>
+
+2、单击添加频道。
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alerting2.png?raw=true";>
+
+3、填写下面描述的字段或选择选项，Type有好多种类型包括DingDing、Email、Slack、WebHook、Prometheus 
Alertmanager等。
+本次示例Type使用`Prometheus Alertmanager`，需要提前安装好Prometheus 
Alertmanager，更多详细的配置及参数介绍请参考官方文档：https://grafana.com/docs/grafana/v8.0/alerting/old-alerting/notifications/。
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alerting3.png?raw=true";>
+
+4、点击`Test`按钮，出现`Test notification sent`点击`Save`按钮保存
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alerting4.png?raw=true";>
+
+5、创建一个新的 Panel 后，输入查询参数后点击保存然后选择`Alert`点击`Create Alert`，如下图所示：
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alertpanle1.png?raw=true";>
+
+6、填写下面描述的字段或选择选项， 其中`Name`是规则名称，`Evaluate every` 指定调度程序评估警报规则的频率，称为评估间隔，
+`FOR` 指定在触发警报通知之前查询需要在多长时间内违反配置的阈值。`Conditions` 表示查询条件，可以配置多个组合查询条件。
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alertpanle2.jpg?raw=true";>
+
+图中的查询条件：avg() OF query(A,5m,now) IS ABOVE -1
+
+avg()控制如何将每个系列的值减少到可以与阈值进行比较的值。单击该函数可将其更改为另一个聚合函数。
+query(A, 15m, now)，表示从A选项卡执行查询，后两个参数定义时间范围15m，now 表示从15分钟前到现在。
+IS ABOVE -1 定义阈值的类型和阈值。IS ABOVE表示在-1之上，可以单击IS ABOVE更改阈值类型。
+
+提示:警报规则中使用的查询不能包含任何模板变量。目前我们只支持条件之间的AND和OR运算符，它们是串行执行的。
+例如，我们按以下顺序有 3 个条件： 条件：A（计算为：TRUE）或条件：B（计算为：FALSE）和条件：C（计算为：TRUE） 
所以结果将计算为（（对或错）和对）=对。
+更多详细的告警规则可以查看官方文档:https://grafana.com/docs/grafana/latest/alerting/old-alerting/create-alerts/
+
+
+7、点击`Test rule` 按钮出现`firing: true`则配置成功，点击`save` 按钮
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alertpanel3.png?raw=true";>
+
+8、下图为grafana panel 中显示告警
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alertpanel4.png?raw=true";>
+
+9、查看告警规则
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alertPanel5.png?raw=true";>
+
+10、在promehthus alertmanager 中查看告警记录
 
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; 
margin-right:auto; display:block;" 
src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Ecosystem%20Integration/Grafana-plugin/alertpanel6.png?raw=true";>
 
 ### 更多

Reply via email to