TDinsight 参考手册

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

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

前置条件

首先检查下面服务：

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

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

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

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

  信息

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

然后记录以下信息：

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

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

安装 Grafana TDengine 数据源插件和配置数据源的步骤请参考：与 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 相关资源的使用情况和状态，比如 dnodes、mnodes、vnodes 和数据库等。 主要分为集群状态、DNodes 概述、MNode 概述、请求、数据库、DNode 资源使用情况和 taosAdapter 监控信息。下面我们分别详细介绍。

集群状态

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

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

• First EP：当前 TDengine 集群中的firstEp设置。
• Version：TDengine 服务器版本（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：总其他请求数

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

预配置告警规则自动导入

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

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

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

规则名称	规则阈值	无监控数据时的行为	数据扫描间隔	持续时间	执行 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
流式计算运行失败	error_code != 0	不触发报警	1 分钟	0 秒	select now(), cluster_id, stream_name, last(cast(error_code as bigint)) as error_code from log.taosd_stream_failure where _ts >= (now - 120s) and _ts < now partition by cluster_id, stream_name having first(_ts) > 0
流式计算重算失败	Failed 状态的重算任务数 > 0	不触发报警	1 分钟	0 秒	select now() as ts, stream_name, recalc_id, progress, message, count(*) as failed from information_schema.ins_stream_recalculates where status = 'Failed' partition by stream_name, recalc_id, progress, message

注意：流式计算运行失败、流式计算重算失败两条规则依赖流式计算可观测性功能，仅 TDengine v3.4.2.7 及以上版本支持；在更早的版本上，这两条规则会处于查询错误状态，不影响其他告警规则。

升级说明：从 tdengine-datasource 4.0.1 及更早版本升级时，已有数据源不会自动获得新版本新增的告警规则。升级到 4.0.2 及以上版本后，打开该数据源的 setting 界面，重新点击一次“Save & test”按钮，插件会把“流式计算运行失败”“流式计算重算失败”两条新规则追加到已有的 alert_1m 规则组中；已有规则及其自定义（阈值、标签、持续时间等）与规则组检查间隔均保持不变，联络点（Contact points）、通知策略（Notification policies）等告警通道配置也不受影响。

用户可参考上述告警规则，根据自己业务需求进行修改与完善。

升级

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

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

卸载

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

• 用图形界面，在“TDengine 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 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 datasource name, no space. [default: TDengine]
-a, --tdengine-api <url>                    TDengine REST API endpoint. [default: http://127.0.0.1:6041]
-u, --tdengine-user <string>                TDengine user name. [default: root]
-p, --tdengine-password <string>            TDengine 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 数据源插件版本，默认使用最新版。
-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 数据源名称，默认为 TDengine。
-a	--tdengine-api	TDENGINE_API	TDengine REST API 端点。默认为http://127.0.0.1:6041。
-u	--tdengine-user	TDENGINE_USER	TDengine 用户名。 [默认值：root]
-p	--tdengine-password	TDENGINE_PASSWORD	TDengine 密码。 [默认：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 数据库，HTTP API 端口为 6041，用户为 root1，密码为 pass5ord。执行脚本：

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

如果要监控多个 TDengine 集群，则需要设置多个 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 参数将仪表盘设置为可编辑。