TDinsight 参考手册

TDinsight 是使用 [Grafana] 对 TDengine TSDB 进行监控的解决方案。

TDengine TSDB 通过 taosKeeper 将服务器的 CPU、内存、硬盘空间、带宽、请求数、磁盘读写速度、慢查询等信息定时写入指定数据库。通过 Grafana 和 TDengine TSDB 数据源插件，TDinsight 将集群状态、节点信息、插入及查询请求、资源使用情况等进行可视化展示，为开发者实时监控 TDengine TSDB 集群运行状态提供了便利。本文将指导用户安装 TDengine TSDB 数据源插件及部署 TDinsight 可视化面板。

前置条件

首先检查下面服务：

• TDengine TSDB 已经安装并正常运行，此仪表盘需要 TDengine TSDB 3.0.0.0 及以上，并开启监控上报配置，具体配置请参考：TDengine TSDB 监控配置。

• taosAdapter 已经安装并正常运行。具体细节请参考：taosAdapter 参考手册

• taosKeeper 已安装并正常运行。具体细节请参考：taosKeeper 参考手册

• Grafana 服务已安装并正常运行。我们建议您使用最新的 Grafana 版本，TDInsight 支持 Grafana 7.5 及以上版本。

  信息

  下文介绍中，都以 Grafana v11.0.0 版本为例，其他版本功能可能有差异，请参考 Grafana 官网。

然后记录以下信息：

• taosAdapter 集群 REST API 地址，如：http://localhost:6041。
• taosAdapter 集群认证信息，可使用用户名及密码。
• taosKeeper 记录监控指标的数据库名称。

安装 TDengine TSDB 数据源插件和配置数据源

安装 Grafana TDengine TSDB 数据源插件和配置数据源的步骤请参考：与 Grafana 集成

导入 TDinsightV3 仪表盘

• 推荐方式：在配置好数据源后，点击“Settings”右侧的“Dashboards”，会显示数据源自带的仪表盘，然后选择“TDengine for 3.x”右侧的“Import”进行导入。
  

• 使用 Dashboard ID 导入：在 Grafana 主界面左侧，依次点击“Dashboards”Tab、右上角“New”选项下的“Import”，输入“TDengine for 3.x”仪表盘的 Dashboard ID 18180，进行导入。

• 使用 JSON 配置导入：

  1. 先去 TDinsight for 3.x 下载 JSON 文件。
  2. 在 Grafana 主界面左侧，依次点击“Dashboards”Tab、右上角“New”选项下的“Import”。
  3. 在“Import via dashboard JSON model”部分粘贴上刚才下载的 JSON 文件内容，最后点击“Import”导入。

导入成功后可以进入这个 Dashboard，在左上角“Log from”选项中选择 taosKeeper 中设置的记录监控指标的数据库就可以看到监控结果。

TDinsightV3 仪表盘详情

TDinsight 仪表盘旨在提供 TDengine TSDB 相关资源的使用情况和状态，比如 dnodes、mnodes、vnodes 和数据库等。 主要分为集群状态、DNodes 概述、MNode 概述、请求、数据库、DNode 资源使用情况和 taosAdapter 监控信息。下面我们分别详细介绍。

集群状态

这部分指标包括集群当前信息和状态。

指标详情（从上到下，从左到右）：

• First EP：当前 TDengine TSDB 集群中的firstEp设置。
• Version：TDengine TSDB 服务器版本（master mnode）。
• Expire Time - 企业版过期时间。
• Used Measuring Points - 企业版已使用的测点数。
• Databases - 数据库个数。
• Connections - 当前连接个数。
• DNodes/MNodes/VGroups/VNodes：每种资源的总数和存活数。
• Classified Connection Counts：当前活跃连接数，按用户、应用和 ip 分类。
• DNodes/MNodes/VGroups/VNodes Alive Percent：每种资源的存活数/总数的比例，启用告警规则，并在资源存活率（1 分钟内平均健康资源比例）不足 100% 时触发。
• Measuring Points Used：启用告警规则的测点数用量（社区版无数据，默认情况下是健康的）。

DNodes 概述

这部分指标包括集群 dnode 基本信息。

指标详情：

• DNodes Status：show dnodes 的简单表格视图。
• DNodes Number：DNodes 数量变化。

MNode 概述

这部分指标包括集群 mnode 基本信息。

指标详情：

1. MNodes Status：show mnodes 的简单表格视图。
2. MNodes Number：类似于DNodes Number，MNodes 数量变化。

请求统计

这部分指标包括集群执行 sql 的统计指标。

指标详情：

1. Select Request：select 请求数。
2. Delete Request：delete 请求数。
3. Insert Request：insert 请求数。
4. Inserted Rows：实际插入行数。
5. Slow Sql：慢查询数，可以在顶部分时长段过滤。

表统计

这部分指标包括集群中表的统计指标。

指标详情：

1. STables：超级表数量。
2. Total Tables：所有表数量。
3. Tables：所有普通表数量随时间变化图。
4. Tables Number Foreach VGroups：每个 VGroups 包含的表数量。

DNode 资源使用情况

这部分指标包括集群所有数据节点资源使用情况展示，每个数据节点为一个 Row 进行展示。。

指标详情（从上到下，从左到右）：

1. Uptime：从创建 dnode 开始经过的时间。
2. Has MNodes?：当前 dnode 是否为 mnode。
3. CPU Cores：CPU 核数。
4. VNodes Number：当前 dnode 的 VNodes 数量。
5. VNodes Masters：处于 master 角色的 vnode 数量。
6. Current CPU Usage of taosd：taosd 进程的 CPU 使用率。
7. Current Memory Usage of taosd：taosd 进程的内存使用情况。
8. Max Disk Used：taosd 所有数据目录对应的最大磁盘使用率。
9. CPU Usage：进程和系统 CPU 使用率。
10. RAM Usage：RAM 使用指标时间序列视图。
11. Disk Used：多级存储下每个级别使用的磁盘（默认为 level0 级）。
12. Disk IO：磁盘 IO 速率。
13. Net IO：网络 IO，除本机网络之外的总合网络 IO 速率。

taosAdapter 监控

这部分指标包括 taosAdapter rest 和 websocket 请求统计详情。

指标详情：

1. Total：总请求数
2. Successful：总成功数
3. Failed：总失败数
4. Queries：总查询数
5. Writes：总写入数
6. Other：总其他请求数

还有上述分类的细分维度折线图。

预配置告警规则自动导入

涛思总结用户使用经验，整理出 14 个常用的告警规则（alert rule），能够对集群关键指标进行监测并及时上报指标异常、超限等告警信息。
从 TDengine TSDB server 3.3.4.3 版本（tdengine-datasource 3.6.3）开始，TDengine TSDB Datasource 支持预配置告警规则自动导入功能，用户可将 14 个告警规则一键导入 Grafana（11 及以上版本），直接使用。
预配置告警规则导入方法如下图所示，在 tdengine-datasource setting 界面，打开“Load Tengine Alert”开关，点击“Save & test”按钮后，插件会自动加载上述告警规则，规则会放入以数据源名称 + “-alert”的 grafana 告警目录中。如不需要，关闭“Load TDengine Alert”开关，点击“Clear TDengine Alert”旁边的按钮则会清除此数据源已导入的所有告警规则。

导入后，点击 Grafana 左侧“Alert rules” ，可查看当前所有告警规则。 用户只需配置联络点（Contact points），即可获取告警通知。联络点配置方法见告警配置。

14 个告警规则具体配置如下：

规则名称	规则阈值	无监控数据时的行为	数据扫描间隔	持续时间	执行 SQL
dnode 节点的 CPU 负载	均值 > 80%	触发告警	5 分钟	5 分钟	select now(), dnode_ep, last(cpu_system) as cpu_use from log.taosd_dnodes_info where _ts >= (now- 5m) and _ts < now partition by dnode_ep
dnode 节点的的内存	均值 > 60%	触发告警	5 分钟	5 分钟	select now(), dnode_ep, last(mem_engine) / last(mem_total) * 100 as taosd from log.taosd_dnodes_info where _ts >= (now- 5m) and _ts <now partition by dnode_ep
dnode 节点的磁盘容量占用	> 80%	触发告警	5 分钟	5 分钟	select now(), dnode_ep, data_dir_level, data_dir_name, last(used) / last(total) * 100 as used from log.taosd_dnodes_data_dirs where _ts >= (now - 5m) and _ts < now partition by dnode_ep, data_dir_level, data_dir_name
集群授权到期	< 60 天	触发告警	1 天	0 秒	select now(), cluster_id, last(grants_expire_time) / 86400 as expire_time from log.taosd_cluster_info where _ts >= (now - 24h) and _ts < now partition by cluster_id having first(_ts) > 0
测点数达到授权测点数	>= 90%	触发告警	1 天	0 秒	select now(), cluster_id, CASE WHEN max(grants_timeseries_total) > 0.0 THEN max(grants_timeseries_used) /max(grants_timeseries_total) * 100.0 ELSE 0.0 END AS result from log.taosd_cluster_info where _ts >= (now - 30s) and _ts < now partition by cluster_id having timetruncate(first(_ts), 1m) > 0
查询并发请求数	> 100	不触发报警	1 分钟	0 秒	select now() as ts, count(*) as slow_count from performance_schema.perf_queries
慢查询执行最长时间（无时间窗口）	> 300 秒	不触发报警	1 分钟	0 秒	select now() as ts, count(*) as slow_count from performance_schema.perf_queries where exec_usec>300000000
dnode 下线	total != alive	触发告警	30 秒	0 秒	select now(), cluster_id, last(dnodes_total) - last(dnodes_alive) as dnode_offline from log.taosd_cluster_info where _ts >= (now -30s) and _ts < now partition by cluster_id having first(_ts) > 0
vnode 下线	total != alive	触发告警	30 秒	0 秒	select now(), cluster_id, last(vnodes_total) - last(vnodes_alive) as vnode_offline from log.taosd_cluster_info where _ts >= (now - 30s) and _ts < now partition by cluster_id having first(_ts) > 0
数据删除请求数	> 0	不触发报警	30 秒	0 秒	select now(), sum(count) asdelete_countfrom log.taos_sql_req where sql_type = 'delete' and _ts >= (now -30s) and _ts < now
Adapter RESTful 请求失败	> 5	不触发报警	30 秒	0 秒	select now(), sum(fail) asFailedfrom log.adapter_requests where req_type=0 and ts >= (now -30s) and ts < now
Adapter WebSocket 请求失败	> 5	不触发报警	30 秒	0 秒	select now(), sum(fail) asFailedfrom log.adapter_requests where req_type=1 and ts >= (now -30s) and ts < now
dnode 数据上报缺少	< 3	触发告警	180 秒	0 秒	select now(), cluster_id, count(*) as dnode_report from log.taosd_cluster_info where _ts >= (now -180s) and _ts < now partition by cluster_id having timetruncate(first(_ts), 1h) > 0
dnode 重启	max(update_time) > last(update_time)	触发告警	90 秒	0 秒	select now(), dnode_ep, max(uptime) - last(uptime) as dnode_report from log.taosd_dnodes_info where _ts >= (now - 90s) and _ts < now partition by dnode_ep

用户可参考上述告警规则，根据自己业务需求进行修改与完善。
Grafana7.5 及以下版本，Dashboards 与 Alert rules 功能合在一起，而之后的新版本两个功能是分开的。为兼容 Grafana7.5 及以下版本，TDinsight 面板中增加了 Alert Used Only 面板，仅 Grafana7.5 及以下版本需要使用。

升级

下面三种方式都可以进行升级：

• 用图形界面，若有新版本，可以在”TDengine TSDB Datasource“插件页面点击 update 升级。
• 按照手动安装步骤自行安装新的 Grafana 插件和 Dashboard。
• 通过重新运行 TDinsight.sh 脚本升级到最新的 Grafana 插件和 TDinsight Dashboard。

卸载

针对不同的安装方式，卸载时：

• 用图形界面，在”TDengine TSDB Datasource“插件页面点击”Uninstall“卸载。
• 通过 TDinsight.sh 脚本安装的 TDinsight，可以使用命令行 TDinsight.sh -R 清理相关资源。
• 手动安装的 TDinsight，要完全卸载，需要按照顺序清理以下内容：
  1. Grafana 中的 TDinsight Dashboard。
  2. Grafana 中的 Alert rules 告警规则。
  3. Grafana 中的 Data Source 数据源。
  4. 从插件安装目录删除 tdengine-datasource 插件。

附录

TDinsight.sh 详细说明

下面是 TDinsight.sh 的用法详细说明：

Usage:
   ./TDinsight.sh
   ./TDinsight.sh -h|--help
   ./TDinsight.sh -n <ds-name> -a <api-url> -u <user> -p <password>

Install and configure TDinsight dashboard in Grafana on Ubuntu 18.04/20.04 system.

-h, -help,          --help                  Display help

-V, -verbose,       --verbose               Run script in verbose mode. Will print out each step of execution.

-v, --plugin-version <version>              TDengine TSDB datasource plugin version, [default: latest]

-P, --grafana-provisioning-dir <dir>        Grafana provisioning directory, [default: /etc/grafana/provisioning/]
-G, --grafana-plugins-dir <dir>             Grafana plugins directory, [default: /var/lib/grafana/plugins]
-O, --grafana-org-id <number>               Grafana organization id. [default: 1]

-n, --tdengine-ds-name <string>             TDengine TSDB datasource name, no space. [default: TDengine TSDB]
-a, --tdengine-api <url>                    TDengine TSDB REST API endpoint. [default: http://127.0.0.1:6041]
-u, --tdengine-user <string>                TDengine TSDB user name. [default: root]
-p, --tdengine-password <string>            TDengine TSDB password. [default: taosdata]

-i, --tdinsight-uid <string>                Replace with a non-space ASCII code as the dashboard id. [default: tdinsight]
-t, --tdinsight-title <string>              Dashboard title. [default: TDinsight]
-e, --tdinsight-editable                    If the provisioning dashboard could be editable. [default: false]

大多数命令行选项都可以通过环境变量获得同样的效果。

短选项	长选项	环境变量	说明
-v	--plugin-version	TDENGINE_PLUGIN_VERSION	TDengine TSDB 数据源插件版本，默认使用最新版。
-P	--grafana-provisioning-dir	GF_PROVISIONING_DIR	Grafana 配置目录，默认为/etc/grafana/provisioning/
-G	--grafana-plugins-dir	GF_PLUGINS_DIR	Grafana 插件目录，默认为/var/lib/grafana/plugins。
-O	--grafana-org-id	GF_ORG_ID	Grafana 组织 ID，默认为 1。
-n	--tdengine-ds-name	TDENGINE_DS_NAME	TDengine TSDB 数据源名称，默认为 TDengine。
-a	--tdengine-api	TDENGINE_API	TDengine TSDB REST API 端点。默认为http://127.0.0.1:6041。
-u	--tdengine-user	TDENGINE_USER	TDengine TSDB 用户名。 [默认值：root]
-p	--tdengine-password	TDENGINE_PASSWORD	TDengine TSDB 密码。 [默认：taosdata]
-i	--tdinsight-uid	TDINSIGHT_DASHBOARD_UID	TDinsight 仪表盘uid。 [默认值：tdinsight]
-t	--tdinsight-title	TDINSIGHT_DASHBOARD_TITLE	TDinsight 仪表盘标题。 [默认：TDinsight]
-e	--tdinsight-editable	TDINSIGHT_DASHBOARD_EDITABLE	如果配置仪表盘可以编辑。 [默认值：false]

备注

新版本插件使用 Grafana unified alerting 功能，-E 选项不再支持。

假设您在主机 tdengine 上启动 TDengine TSDB 数据库，HTTP API 端口为 6041，用户为 root1，密码为 pass5ord。执行脚本：

./TDinsight.sh -a http://tdengine:6041 -u root1 -p pass5ord

如果要监控多个 TDengine TSDB 集群，则需要设置多个 TDinsight 仪表盘。设置非默认 TDinsight 需要进行一些更改： -n -i -t 选项需要更改为非默认名称，如果使用 内置短信告警功能，-N 和 -L 也应该改变。

sudo ./TDengine.sh -n TDengine-Env1 -a http://another:6041 -u root -p taosdata -i tdinsight-env1 -t 'TDinsight Env1'

请注意，配置数据源、通知 Channel 和仪表盘在前端是不可更改的。您应该再次通过此脚本更新配置或手动更改 /etc/grafana/provisioning 目录（这是 Grafana 的默认目录，根据需要使用-P选项更改）中的配置文件。

特别地，当您使用 Grafana Cloud 或其他组织时，-O 可用于设置组织 ID。 -G 可指定 Grafana 插件安装目录。 -e 参数将仪表盘设置为可编辑。