本篇作者：

IoTDB 社区 -- 张洪胤

本文以 IoTDB V1.0.1 版本为例

本文档介绍了 Apache IoTDB 监控指标通过 Prometheus 的方式进行采集，并且使用 Grafana 的方式进行可视化。

1

监控指标的 Prometheus 格式说明

对于 Metric Name 为 name, Tags 为 K1=V1, ..., Kn=Vn 的监控指标有如下映射，其中 value 为具体值

2

Prometheus 函数说明

2.1

Aggregation operators

参考文档：

https://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators

运算符：

- sum (calculate sum over dimensions)

- min (select minimum over dimensions)

- max (select maximum over dimensions)

- avg (calculate the average over dimensions)

- group (all values in the resulting vector are 1)

- stddev (calculate population standard deviation over dimensions)

- stdvar (calculate population standard variance  over dimensions)

- count (count number of elements in the vector)

- count_values (count number of elements with the same value)

- bottomk (smallest k elements by sample  value)

- topk (largest k elements by sample value)

- quantile(calculate φ-quantile (0 ≤ φ ≤ 1) over  dimensions)

上述所有运算符都可以在所有维度上聚合，也可以通过 without 或者 by 子句来决定聚合方式，对应语法规约为：

<aggr-op> [without|by (<label list>)] ([parameter,] <vector expression>)
or
<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]

2.2

Functions

参考文档：

https://prometheus.io/docs/prometheus/latest/querying/functions/

2.2.1 rate

1. rate(v range-vector): 计算范围向量中时间序列的每秒平均增长率。单调性中断（例如由于目标重启导致的计数器重置）会自动调整。此外，计算外推到时间范围的末端，允许缺失周期与范围的时间段不完全对齐。

2. 示例：以下示例表达式返回范围向量中每个时间序列在过去 5 分钟内测量的每秒 HTTP 请求速率：

rate(http_requests_total{job="api-server"}[5m])

3. 计算原理：rate 通过计算一个新的直方图来作用于原生直方图，其中每个分量（观测值的总和和计数，桶）是 v 中第一个和最后一个原生直方图中相应分量之间的增长率。

4. 适用场景：适用于警报和缓慢移动的计数器。

5. 注意：当将 rate() 与聚合运算符（例如 sum()）或随时间聚合的函数（任何以 _over_time 结尾的函数结合使用时，始终首先采用 rate()，然后进行聚合。否则 rate() 无法在您的目标重新启动时检测到计数器重置。

2.2.2 irate

1. irate(v range-vector)：计算范围向量中时间序列的每秒瞬时增长率（基于最后两个数据点）。单调性中断（例如由于目标重启导致的计数器重置）会自动调整。

2. 示例：以下示例表达式通过查找 5 分钟前两个最近的数据点得出 HTTP 请求的每秒速率：

irate(http_requests_total{job="api-server"}[5m])

3. 适用场景：易变的、快速移动的计数器。

4. 注意：当将 irate() 与聚合运算符（例如 sum()）或随时间聚合的函数（任何以 _over_time 结尾的函数）结合使用时，始终首先采用 irate()，然后进行聚合。否则，irate() 无法在您的目标重新启动时检测到计数器重置。

3

Grafana 可视化绘制

官方文档参考：https://grafana.com/docs/

3.1

创建 Dashboard

如果已有 Dashboard 跳过本步骤即可

1. 点击左侧边栏 Dashboards -> browse 

   a. 已有 Dashboard：点击右侧 Import 按钮导入对应的 Dashboard 即可。

   b. 创建 Dashboard：点击右侧 New Dashboard 按钮。

2. 进入 Dashboard 后点击右上角设置按钮：

   a. 在 General 界面更新 Name，Description，Tag等基础信息，调整 Panel options 为 Shared crosshair，从而保证 tooltip 可以跨 panel 使用。

   b. 在 Variables 界面定义本 Dashboard 的变量：

        i. 添加 job 变量，类型为 Query，对应的Query Options 是 label_values(job)

        ii. 添加 instance 变量，类型为 Query，对应的 Query Options 是 label_values(up{job=~"$job"},instance)

3.2

创建 Panel

优秀绘制参考：

https://play.grafana.org/dashboards

1. 点击右上角：Add Panel，其中 Add a new panel 是添加一个面板，Add a new row 是添加一个行（分组，两个行之间的所有 panel 属于前一个row）。

2. 点击 Add a new Panel，添加一个面板。首先点击右上角，选择当前 Panel 的类型，比较常用的有Time series（时间序列）、Stat（统计）、Gauge（寄存器）等等，可以视情况选择。

3. 以 Timeseries 为例，首先编写对应的 PromQL 执行数据查询。

   a. 在 PromQL 中，可以用 $instance 访问到刚刚在 Dashboard 的 Variables 中配置的 instance 变量，job 变量也是类似的。

   b. 在 Legend 中，可以通过双中括号访问到对应的监控项的对应 Tag 的具体值，比如在下图的例子中，state="blocked/new/runnable/terminated/timed-waiting/waiting"，通过这样的方式修改图例。

   c. 可以通过点击 + Query 在当前面板添加更多时间序列。

4. 在右侧的 Panel Options 中可以更新当前面板的标题、描述并设置面板背景是否透明。

5. 在右侧的 Tooltip 中可以选择不同的类型：

   a. Single：只显示距离鼠标最近的一条。

   b. All：显示鼠标所在时间线的所有条，可以不排 序、升序或降序。

   c. Hidden：不显示。

6. 在右侧的 Legend 可以调整不同的图例：

   a. Mode：List（列表）、Table（表格）、Hidden（不显示）。

   b. Placement：Bottom（放在底部）、Right（放在右侧）。

   c. Legend Values：是否要同时显示对应的时间序列的值。

   d. 如下示例我们将图例放置在右侧，采用表格的形式，并且显示平均值。

7. 在右侧的 Graph Styles 可以调整线的样式，包括 line、bar 和 point 三类：

   a. line：还可以调整插值、线宽、填充透明度、渐变模式、线形、空值连接方法、是否显示等属性。

   b. bar：还可以调整类型、线宽、填充透明度、渐变模式、是否显示点等属性。

   c. points：还可以调整点大小等属性。

   d. 如下示例我们使用线，设置填充透明度为5%，从不显示点。

8. 在右侧的 Axis 可以调整对应的轴信息，包括标签、宽度、纵轴最小值、纵轴最大值等等，一般不需要调整。

9. 在右侧的 Standard options 可以设置单位（有byte, s, ms, us, ns等等，还可以自定义）、显示最小值、显示最大值、精度、展示名称、配色（可以选择单个颜色、根据阈值或者现有配色方案）等。如下示例为自定义单位为 个，最小值设置为 0，最大值设置为 300。

10. 在右侧的 Value mappings 可以添加对应的映射：可以根据值、范围、正则和特殊值（空等）来控制其展示的文本，比如0代表离线，1代表上线，可以通过 value mappings 完成。

11. 在右侧的 Thresholds 则是设置阈值，可以结合 Standard options 中的配色方案使用：

   a. 阈值设置：可以设置绝对阈值、相对阈值（和显示最大值、显示最小值有关）。

   b. 阈值显示：可以选择不显示阈值、显示阈值线、显示阈值阴影和同时显示阈值线和阴影。

   c. 例如设置为 60% 和 80% 的阈值，并且显示阈值吸纳和阴影线。

12. 可以通过 Overrides 来重写部分时间序列的上述某些属性，支持通过名字、名字正则、类型和返回值重写：

   a. 重写的属性具有更高的优先级。

   b. 例如我可以重写 name 为 waiting 的时间序列的颜色为绿色，如下所示：

13. 至此，已经完成了对于 Panel 创建的简单介绍，可以通过在 Dashboard 中拖拽 Panel 改变其位置，也可以通过拖拽 Panel 的右下角来改变 panel 的大小。

4

导出 Grafana

1. 点击左上角的导出按钮：

2. 点击 Export 标签页，并选择 Export for sharing externally，然后点击 save to file 就将对应的 Dashboard 的 json 文件下载到本地了。

3. 最后，将 Dashboard 的 json 上传到 GitHub (docs/UserGuide/Monitor-Alert文件夹下) 的对应位置即可。

作为全球性开源项目，截至目前，Apache IoTDB 已拥有 244 名贡献者、3.1K Stars、820 Forks、8653 Commits。我们为大家提供了参与指南，欢迎越来越多的小伙伴助力 Apache IoTDB 项目的不断发展与前进，迈出加入 Apache IoTDB 社区的第一步！