TDengine 订阅服务功能测试工具 taossubscribe 使用指南：快速验证 Topic 消费与故障定位

TDengine 订阅服务功能测试工具 taossubscribe 使用指南快速验证 Topic 消费与故障定位【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDenginetaossubscribe 是 TDengine Enterprise 巡检工具箱Inspection Toolkit中的订阅服务验证工具用于检验已创建的 TOPIC 是否能够被正常消费并在消费失败时帮助定位订阅投递链路中的问题。本文结合 inspect-tools 索引文档与 TMQ 客户端配置解析源码系统讲解该工具在本地TSDB 自建与云部署两种模式下的用法、配置文件编写、结果文件解读及底层原理读完即可独立完成一次订阅服务的连通性验证与故障排查。工具定位与适用场景在 TDengine 的数据订阅机制TMQ中用户通过 SQL 创建 TOPIC 后消费端基于 Kafka 风格的客户端协议从 taosAdapter 拉取增量数据。实际运维中经常遇到消费者读取订阅消息报错的情况——原因可能是 TOPIC 不存在、group offset 异常、鉴权失败、taosAdapter 端口不通或网络隔离等。taossubscribe 正是为此设计它作为一个现成的 TMQ 消费者直接对指定 TOPIC 发起订阅将整个投递过程的结果完整呈现给运维人员从而把业务代码消费报错收敛为工具可复现、可观察的确定性验证。根据 巡检工具索引该工具与 taosprecheck、taosinspect、taosperf 等共同构成巡检工具箱有以下前提约束目前仅对TDengine Enterprise企业版用户开放要求TDengine v3.1 或更高版本已在 Kylin V10、Ubuntu 20.04.2、CentOS 7.9、LinxOS 6.0.99、openEuler 23.09、Debian 12 等平台上验证通过其他平台或版本请先联系交付代表确认建议以root或具有sudo权限的账号运行。本地部署模式参数与用法本地模式用于消费自建self-hosted的 TDengine 集群即通过 taosAdapter 的 REST/WebSocket 接口连接。可通过-h查看完整语法usage: taossubscribe local [-h] [--config CONFIG] [--backend] --ip IP [--show-data] [--log-level {debug,info}] [--port PORT] optional arguments: -h, --help show this help message and exit --config CONFIG, -f CONFIG Path to config file --backend, -b Run process in backend --ip IP, -i IP Database IP address --show-data, -s Show data in console and save to log --log-level {debug,info}, -l {debug,info} Set log level, default: info (options: debug, info) --port PORT, -p PORT Database port各参数说明如下参数简写含义默认值/说明--config-f配置文件路径不指定时默认加载工具运行当前目录下的配置文件--backend-b后台运行模式默认前台运行--ip-iTDengine 所在机器的 IP 地址必填参数--show-data-s在 console 中打印订阅消息内容并同步保存到日志默认打印--log-level-l日志级别支持debug、info默认info排查问题时可切到debug观察更细粒度的交互过程--port-pTDengine 的 taosAdapter 服务对外开放端口默认6041其中--ip指向 TDengine 主机--port是 taosAdapter 对外提供 REST/WebSocket 服务的端口默认 6041。工具通过 WebSocket 连接配置文件中的td.connect.websocket.schemews建立与 taosAdapter 的会话因此使用前请确认该端口可达、未被防火墙拦截。云部署模式Token 认证云模式面向 TDengine CloudTSDB 云服务场景连接目标不是自建 taosAdapter而是云端的订阅服务端点因此使用--token代替端口做认证usage: taossubscribe cloud [-h] [--config CONFIG] [--backend] --ip IP [--show-data] [--log-level {debug,info}] --token TOKEN optional arguments: -h, --help show this help message and exit --config CONFIG, -f CONFIG Path to config file --backend, -b Run process in backend --ip IP, -i IP Database IP address --show-data, -s Show data in console and save to log --log-level {debug,info}, -l {debug,info} Set log level, default: info (options: debug, info) --token TOKEN, -t TOKEN Cloud access token参数说明参数简写含义说明--config-f配置文件路径不指定时默认加载工具运行当前目录下的配置文件--backend-b后台运行默认前台运行--ip-iTDengine 云服务的访问地址域名或 IP必填参数--show-data-s打印并保存订阅消息内容默认打印--log-level-l日志级别debug、info默认info--token-t连接云服务的 Token 认证信息必填参数从 TDengine Cloud 控制台获取与本地模式的关键差异在于云模式下认证信息通过--token传入不再使用--port连接配置中的账号密码td.connect.user/td.connect.pass会被云端 Token 取代。配置文件TMQ 消费者属性与 Topic 列表工具的配置文件同时承担两件事配置 TMQ 消费者的连接与会话属性以及声明一个或多个待消费的 TOPIC。默认文件名为taossubscribe使用的配置文件放在工具运行当前目录通过-f可指定其他路径。完整示例如下######################################################## # # # Configuration # # # ######################################################## [parameters] td.connect.websocket.scheme ws group.id test_group_01 client.id test_consumer_01 enable.auto.commit true auto.commit.interval.ms 1000 auto.offset.reset earliest msg.with.table.name true td.connect.user root td.connect.pass taosdata1 # 已定义的Topic名称 [topics] t1 test_topic1[parameters] 段消费端核心属性该段的键值对即 TMQ 消费者的配置属性与 TDengine 客户端 TMQ 配置一一对应。对照 clientTmqConf.c 中tmq_conf_set的解析逻辑各属性含义如下配置键示例值含义源码级补充说明td.connect.websocket.schemews连接 taosAdapter 所用的 WebSocket 协议本地模式走ws启用 TLS 的部署可考虑wss对应项group.idtest_group_01消费组 ID源码中校验该值不能包含:TMQ_SEPARATOR_CHAR否则返回配置无效client.idtest_consumer_01消费者客户端标识长度受TSDB_CLIENT_ID_LEN限制enable.auto.committrue是否自动提交消费位点布尔解析parseBoolConf设为false可做只读探测验证auto.commit.interval.ms1000自动提交位点的间隔毫秒源码中校验范围为[0, INT32_MAX]auto.offset.resetearliest无已提交位点时从何处开始消费源码仅接受三个枚举值none、earliest、latest其他值报错返回TMQ_CONF_INVALIDmsg.with.table.nametrue消费消息中是否携带表名布尔解析映射到conf-withTbNametd.connect.userroot连接 TDengine 的用户名字符串复制到conf-usertd.connect.passtaosdata1连接密码字符串复制到conf-pass云模式下通常由 Token 替代除此之外从 tmq_conf_set 实现可以看到 TMQ 还支持更多属性按需也可写入配置文件的[parameters]段例如td.connect.ip/td.connect.port/td.connect.token连接地址与 Token 的等价配置入口端口校验范围1~65535session.timeout.ms会话超时校验范围6000~1800000毫秒heartbeat.interval.ms心跳间隔校验范围1000 ~ session.timeout.ms-1max.poll.interval.ms最大拉取间隔下限 1000 毫秒fetch.max.wait.ms/min.poll.rows拉取等待时长与单次最少返回行数experimental.snapshot.enable、enable.replay、msg.consume.rawdata等进阶开关。[topics] 段待验证的 TOPIC 清单[topics] t1 test_topic1该段采用键 值的映射方式声明一个或多个已定义的 TOPICt1是自定义别名test_topic1是目标 TOPIC 名。工具会依次对列出的每个 TOPIC 发起订阅消费。多个 TOPIC 分行书写即可例如[topics] t1 test_topic1 t2 sensor_topic注意TOPIC 需预先通过 SQLCREATE TOPIC ...在服务端创建。如果目标 TOPIC 不存在工具的消费过程会直接暴露对应的订阅错误这正是其验证 诊断价值所在。更完整的 TOPIC 创建与消费概念可参考 数据订阅TMQ文档 对应章节。结果文件 delivery.log工具运行结束后会在当前目录生成结果文件delivery.log。该文件包含消费订阅服务返回的全部响应信息连接建立、订阅确认、拉取结果、错误信息等当启用--show-data时消费到的消息内容也会一并写入日志。delivery.log是排障的第一手证据当业务侧消费报错时对比本工具在同配置下的输出可快速区分问题位于服务端订阅链路还是业务代码侧。应用示例以下命令均使用-s开启数据打印便于观察消费内容。消费部署在 192.168.0.1 服务器上的自建订阅服务本地模式./taossubscribe local -i 192.168.0.1 -p 6041 -s以 debug 级别、后台方式运行本地模式./taossubscribe local -i 192.168.0.1 -p 6041 -s -l debug -b -f /etc/taos/taossubscribe.conf消费 TDengine Cloud 上的订阅服务云模式使用 Token 认证./taossubscribe cloud -i cloud-host -t token -s执行后若控制台正常输出消息数据且delivery.log无错误记录说明订阅投递链路工作正常若报错则依据delivery.log与debug级别日志逐项核对 IP/端口、Token、group.id与 TOPIC 名即可定位问题。小结taossubscribe 以现成消费者的方式把 TMQ 订阅投递链路变成可一键验证、可留痕复现的操作本地模式经 taosAdapter默认 6041 端口连接自建集群云模式以 Token 连接 TDengine Cloud配置文件负责承载全部消费端属性与待验证 TOPICdelivery.log输出完整订阅响应与消息内容。配合 巡检工具索引 中的环境要求以及 TMQ 配置解析源码 中每个属性的取值约束运维人员可以快速完成订阅服务的连通性验证并将问题精确隔离到连接、鉴权、位点或 TOPIC 定义等环节。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考