taosX 参考手册

taosX 是 TDengine Enterprise 中的一个核心组件，提供零代码数据接入的能力，taosX 支持两种运行模式：服务模式和命令行模式。本节讲述如何以这两种方式使用 taosX。要想使用 taosX 需要先安装 TDengine Enterprise 安装包。

命令行模式

命令行格式

taosX 的命令行参数格式如下

1. taosx -f <from-DSN> -t <to-DSN> <其它参数>

taosX 的命令行参数分为三个主要部分：

• -f 指定数据源，即 Source DSN
• -t 指定写入目标，即Sink DSN
• 其它参数

以下参数说明及示例中若无特殊说明 <content> 的格式均为占位符，使用时需要使用实际参数进行替换。

DSN (Data Source Name)

taosX 命令行模式使用 DSN 来表示一个数据源（来源或目的源），典型的 DSN 如下：

1. # url-like
2. <driver>[+<protocol>]://[[<username>:<password>@]<host>:<port>][/<object>][?<p1>=<v1>[&<p2>=<v2>]]
3. |------|------------|---|-----------|-----------|------|------|----------|-----------------------|
4. |driver|   protocol |   | username  | password  | host | port |  object  |  params               |

6. // url 示例
7. tmq+ws://root:taosdata@localhost:6030/db1?timeout=never

[] 中的数据都为可选参数。

1. 不同的驱动 (driver) 拥有不同的参数。driver 包含如下选项:

2. taos：使用查询接口从 TDengine 获取数据

3. tmq：启用数据订阅从 TDengine 获取数据
4. local：数据备份或恢复
5. pi: 启用 pi-connector从 pi 数据库中获取数据
6. opc：启用 opc-connector 从 opc-server 中获取数据
7. mqtt: 启用 mqtt-connector 获取 mqtt-broker 中的数据
8. kafka: 启用 Kafka 连接器从 Kafka Topics 中订阅消息写入
9. influxdb: 启用 influxdb 连接器从 InfluxDB 获取数据

10. csv：从 CSV 文件解析数据

11. +protocol 包含如下选项：

12. +ws: 当 driver 取值为 taos 或 tmq 时使用，表示使用 rest 获取数据。不使用 +ws 则表示使用原生连接获取数据，此时需要 taosx 所在的服务器安装 taosc。

13. +ua: 当 driver 取值为 opc 时使用，表示采集的数据的 opc-server 为 opc-ua

14. +da: 当 driver 取值为 opc 时使用，表示采集的数据的 opc-server 为 opc-da

15. host:port 表示数据源的地址和端口。

16. object 表示具体的数据源，可以是TDengine的数据库、超级表、表，也可以是本地备份文件的路径，也可以是对应数据源服务器中的数据库。
17. username 和 password 表示该数据源的用户名和密码。
18. params 代表了 dsn 的参数。

其它参数

1. --jobs <number> 指定任务并发数，仅支持 tmq 任务
2. -v 用于指定 taosx 的日志级别，-v 表示启用 info 级别日志，-vv 对应 debug，-vvv 对应 trace

使用举例

用户及权限信息导入导出

从集群 A 导出用户名、密码、权限和白名单信息到集群 B：

1. taosx privileges -f "taos://root:taosdata@hostA:6030" \
2. -t "taos+ws://root:password@hostB:6041"

从集群 A 导出用户名、密码、权限和白名单信息到 JSON 文件：

1. taosx privileges -f "taos+ws://root:taosdata@localhost:6041" \
2. -o ./user-pass-privileges-backup.json

从导出的 JSON 文件中恢复到本机：

1. taosx privileges -i ./user-pass-privileges-backup.json -t "taos:///"

可用参数列表：

当 -u/-p 参数应用时，将仅包含指定的信息，不带参数时，表示所有信息（用户名、密码、权限和白名单）。

-w 参数不能单独使用，当其与 -u 一起使用时才有效（单独使用 -u 将不包含白名单）。

从旧版本迁移数据

1. 同步历史数据

同步整个库：

1. taosx run -f 'taos://root:taosdata@localhost:6030/db1' -t 'taos:///db2' -v

同步指定超级表:

1. taosx run \
2. -f 'taos://root:taosdata@localhost:6030/db1?stables=meters' \
3. -t 'taos:///db2' -v

同步子表或普通表，支持 {stable}.{table} 指定超级表的子表，或直接指定表名 {table}

1. taosx run \
2. -f 'taos://root:taosdata@localhost:6030/db1?tables=meters.d0,d1,table1' \
3. -t 'taos:///db2' -v

1. 同步指定时间区间数据 (使用 RFC3339 时间格式，注意带时区 ):

1. taosx run -f 'taos:///db1?start=2022-10-10T00:00:00Z' -t 'taos:///db2' -v

1. 持续同步，restro 指定同步最近 5m 中的数据，并同步新的数据，示例中每 1s 检查一次，excursion 表示允许 500ms 的延时或乱序数据

1. taosx run \
2. -f 'taos:///db1?mode=realtime&restro=5m&interval=1s&excursion=500ms' \
3. -t 'taos:///db2' -v

1. 同步历史数据 + 实时数据：

1. taosx run -f 'taos:///db1?mode=all' -t 'taos:///db2' -v

1. 通过 —transform 或 -T 配置数据同步（仅支持 2.6 到 3.0 以及 3.0 之间同步）过程中对于表名及表字段的一些操作。暂无法通过 Explorer 进行设置。配置说明如下：

1. 1.AddTag，为表添加 TAG。设置示例：-T add-tag:<tag1>=<value1>。
2. 2.表重命名：
3. 2.1 重命名表限定
4. 2.1.1 RenameTable：对所有符合条件的表进行重命名。
5. 2.1.2 RenameChildTable：对所有符合条件的子表进行重命名。
6. 2.1.3 RenameSuperTable：对所有符合条件的超级表进行重命名。
7. 2.2 重命名方式
8. 2.2.1 Prefix：添加前缀。
9. 2.2.2 Suffix：添加后缀。
10. 2.2.3 Template：模板方式。
11. 2.2.4 ReplaceWithRegex：正则替换。taosx 1.1.0 新增。
12. 重命名配置方式：
13. <表限定>:<重命名方式>:<重命名值>
14. 使用示例：
15. 1.为所有表添加前缀 <prefix>
16. --transform rename-table:prefix:<prefix>
17. 2.为符合条件的表替换前缀：prefix1 替换为 prefix2，以下示例中的 <> 为正则表达式的不再是占位符。
18. -T rename-child-table:replace_with_regex:^prefix1(?<old>)::prefix2_$old

20. 示例说明：^prefix1(?<old>) 为正则表达式，该表达式会匹配表名中包含以 prefix1 开始的表名并将后缀部分记录为 old，prefix2$old 则会使用 prefix2 与 old 进行替换。注意：两部分使用关键字符 :: 进行分隔，所以需要保证正则表达式中不能包含该字符。
21. 若有更复杂的替换需求请参考：https://docs.rs/regex/latest/regex/#example-replacement-with-named-capture-groups 或咨询 taosx 开发人员。

23. 3. 使用 CSV 映射文件进行表重命名：以下示例使用 map.csv 文件进行表重命名

25. `-T rename-child-table:map:@./map.csv`

27. CSV 文件 `./map.csv` 格式如下：

29. name1,newname1
30. name2,newname2

需要注意的是：当迁移两端版本不一致，且使用原生连接时，需要在 DSN 中指定 libraryPath，如： taos:///db1?libraryPath=./libtaos.so

导入 CSV 文件数据

基本用法如下：

1. taosx run -f csv:./meters/meters.csv.gz \
2. --parser '@./meters/meters.json' \
3. -t taos:///csv1 -qq

以电表数据为例，CSV 文件如下：

1. tbname,ts,current,voltage,phase,groupid,location
2. d4,2017-07-14T10:40:00+08:00,-2.598076,16,-0.866025,7,California.LosAngles
3. d4,2017-07-14T10:40:00.001+08:00,-2.623859,6,-0.87462,7,California.LosAngles
4. d4,2017-07-14T10:40:00.002+08:00,-2.648843,2,-0.862948,7,California.LosAngles
5. d4,2017-07-14T10:40:00.003+08:00,-2.673019,16,-0.891006,7,California.LosAngles
6. d4,2017-07-14T10:40:00.004+08:00,-2.696382,10,-0.898794,7,California.LosAngles
7. d4,2017-07-14T10:40:00.005+08:00,-2.718924,6,-0.886308,7,California.LosAngles
8. d4,2017-07-14T10:40:00.006+08:00,-2.740636,10,-0.893545,7,California.LosAngles

--parser 用于设置入库参数，示例如下：

1. {
2. "parse": {
3. "ts": { "as": "TIMESTAMP(ms)" },
4. "current": { "as": "FLOAT" },
5. "voltage": { "as": "INT" },
6. "phase": { "as": "FLOAT" },
7. "groupid": { "as": "INT" },
8. "location": { "as": "VARCHAR(24)" }
9. },
10. "model": {
11. "name": "${tbname}",
12. "using": "meters",
13. "tags": ["groupid", "location"],
14. "columns": ["ts", "current", "voltage", "phase"]
15. }
16. }

它将从 ./meters/meters.csv.gz（一个gzip压缩的CSV文件）导入数据到超级表 meters，每一行都插入到指定的表名 - ${tbname} 使用CSV内容中的 tbname 列作为表名（即在 JSON 解析器中的 .model.name）。

服务模式

本节讲述如何以服务模式部署 taosX。以服务模式运行的 taosX，其各项功能需要通过 taosExplorer 上的图形界面来使用。

配置

taosX 支持通过配置文件进行配置。在 Linux 上，默认配置文件路径是 /etc/taos/taosx.toml，在 Windows 上，默认配置文件路径是 C:\\TDengine\\cfg\\taosx.toml，包含以下配置项：

• plugins_home：外部数据源连接器所在目录。
• data_dir：数据文件存放目录。
• instanceId：当前 taosX 服务的实例 ID，如果同一台机器上启动了多个 taosX 实例，必须保证各个实例的实例 ID 互不相同。
• logs_home：日志文件存放目录，taosX 日志文件的前缀为 taosx.log，外部数据源有自己的日志文件名前缀。已弃用，请使用 log.path 代替。
• log_level：日志等级，可选级别包括 error、warn、info、debug、trace，默认值为 info。已弃用，请使用 log.level 代替。
• log_keep_days：日志的最大存储天数，taosX 日志将按天划分为不同的文件。已弃用，请使用 log.keepDays 代替。
• jobs：每个运行时的最大线程数。在服务模式下，线程总数为 jobs*2，默认线程数为当前服务器内核*2。
• serve.listen：是 taosX REST API 监听地址，默认值为 0.0.0.0:6050。
• serve.database_url：taosX 数据库的地址，格式为 sqlite:<path>。
• serve.request_timeout：全局接口 API 超时时间。
• monitor.fqdn：taosKeeper 服务的 FQDN，没有默认值，置空则关闭监控功能。
• monitor.port：taosKeeper 服务的端口，默认6043。
• monitor.interval：向 taosKeeper 发送指标的频率，默认为每 10 秒一次，只有 1 到 10 之间的值才有效。
• log.path：日志文件存放的目录。
• log.level：日志级别，可选值为 “error”, “warn”, “info”, “debug”, “trace”。
• log.compress：日志文件滚动后的文件是否进行压缩。
• log.rotationCount：日志文件目录下最多保留的文件数，超出数量的旧文件被删除。
• log.rotationSize：触发日志文件滚动的文件大小（单位为字节），当日志文件超出此大小后会生成一个新文件，新的日志会写入新文件。
• log.reservedDiskSize：日志所在磁盘停止写入日志的阈值（单位为字节），当磁盘剩余空间达到此大小后停止写入日志。
• log.keepDays：日志文件保存的天数，超过此天数的旧日志文件会被删除。
• log.watching：是否对日志文件中 log.loggers 配置内容的变更进行监听并尝试重载。
• log.loggers：指定模块的日志输出级别，格式为 "modname" = "level"，同时适配 tracing 库语法，可以根据 modname[span{field=value}]=level，其中 level 为日志级别。

如下所示：

1. # data dir
2. #data_dir = "/var/lib/taos/taosx" # on linux/macOS
3. #data_dir = "C:\\TDengine\\data\\taosx" # on windows

5. # number of threads used for tokio workers, default to 0 (means cores * 2)
6. #jobs = 0

8. # enable OpenTelemetry tracing and metrics exporter
9. #otel = false

11. # server instance id
12. #
13. # The instanceId of each instance is unique on the host
14. # instanceId = 16

16. [serve]
17. # listen to ip:port address
18. #listen = "0.0.0.0:6050"

20. # database url
21. #database_url = "sqlite:taosx.db"

23. # default global request timeout which unit is second. This parameter takes effect for certain interfaces that require a timeout setting
24. #request_timeout = 30

26. [monitor]
27. # FQDN of taosKeeper service, no default value
28. #fqdn = "localhost"

30. # Port of taosKeeper service, default 6043
31. #port = 6043

33. # How often to send metrics to taosKeeper, default every 10 seconds. Only value from 1 to 10 is valid.
34. #interval = 10

37. # log configuration
38. [log]
39. # All log files are stored in this directory
40. #
41. #path = "/var/log/taos" # on linux/macOS
42. #path = "C:\\TDengine\\log" # on windows

44. # log filter level
45. #
46. #level = "info"

48. # Compress archived log files or not
49. #
50. #compress = false

52. # The number of log files retained by the current explorer server instance in the `path` directory
53. #
54. #rotationCount = 30

56. # Rotate when the log file reaches this size
57. #
58. #rotationSize = "1GB"

60. # Log downgrade when the remaining disk space reaches this size, only logging `ERROR` level logs
61. #
62. #reservedDiskSize = "1GB"

64. # The number of days log files are retained
65. #
66. #keepDays = 30

68. # Watching the configuration file for log.loggers changes, default to true.
69. #
70. #watching = true

72. # Customize the log output level of modules, and changes will be applied after modifying the file when log.watching is enabled
73. #
74. # ## Examples:
75. #
76. # crate = "error"
77. # crate::mod1::mod2 = "info"
78. # crate::span[field=value] = "warn"
79. #
80. [log.loggers]
81. #"actix_server::accept" = "warn"
82. #"taos::query" = "warn"

启动

Linux 系统上 taosX 可以通过 Systemd 命令启动：

1. systemctl start taosx

Windows 系统上通过系统管理工具 “Services” 找到 taosX 服务，然后启动它，或者在命令行工具（cmd.exe 或 PowerShell）中执行以下命令启动：

1. sc.exe start taosx

问题排查

1. 修改 taosX 日志级别

taosX 的默认日志级别为 info，要指定不同的级别，请修改配置文件，或使用以下命令行参数：

• error：taosx serve -qq
• debug：taosx serve -q
• info：taosx serve -v
• debug：taosx serve -vv
• trace：taosx serve -vvv

要在 taosX 作为服务运行时指定命令行参数，请参阅配置。

1. 查看 taosX 日志

您可以查看日志文件或使用 journalctl 命令来查看 taosX 的日志。

Linux 下 journalctl 查看日志的命令如下：

1. journalctl -u taosx [-f]

taosX 监控指标

taosX 会将监控指标上报给 taosKeeper，这些监控指标会被 taosKeeper 写入监控数据库，默认是 log 库，可以在 taoskeeper 配置文件中修改。以下是这些监控指标的详细介绍。

taosX 服务

Agent

Connector

taosX 通用数据源任务

taosX TDengine V2 任务

taosX TDengine V3 任务

taosX 其他数据源 任务

这些数据源包括： InfluxDB，OpenTSDB，OPC UA，OPC DA，PI，CSV，MQTT，AVEVA Historian 和 Kafka。

Kafka 数据源相关指标

taosX 数据解析插件

接入 kafka / mqtt 消息中间件时，需要对原始数据进行解析，如果使用 json/regex 等模式解析器无法满足解析需求，同时 UDT(自定义解析脚本) 也无法满足性能要求时，可以自定义数据解析插件。

插件概述

taosX Parser 插件是一个要求用 C/Rust 语言开发的 C ABI 兼容动态库，该动态库要实现约定的 API 并编译为在 taosX 所在运行环境中能够正确运行的动态库，然后复制到约定位置由 taosX 在运行时加载，并在处理数据的 Parsing 阶段调用。

插件部署

完成插件开发后，编译环境需要和目标运行环境兼容，将编译好的插件动态库复制到插件目录下，taosX 启动后，系统首次使用插件时初始化加载插件。可以在 explorer 的 kafka 或者 mqtt 数据接入配置页面中，检查是否加载成功。如下图，如果加载成功，则在解析器选择列表中展示出来。

插件目录在 taosx.toml 配置文件中复用 plugins 配置，追加/parsers作为插件安装路径，默认值在 UNIX 环境下为 /usr/local/taos/plugins/parsers，在 Windows 下为 C:\TDengine\plugins\parsers。

插件 api 说明

1. 获取插件名称

获取插件名，用于前端显示。

函数签名：const char* parser_name()

返回值：字符串。

2. 获取插件版本

插件版本，方便问题定位。

函数签名：const char* parser_version()

返回值：字符串。

3. 配置解析器

将一个字符串参数解析为一个配置对象，仅插件内部使用。

函数签名：parser_resp_t parser_new(char* ctx, uint32_t len);

char* ctx: 用户自定义配置字符串。

uint32_t len: 该字符串的二进制长度（不含 \0）。

返回值：

1. struct parser_resp_t {
2. int e;    // 0 if success.
3. void* p;  // Success if contains.
4. }

当创建对象失败时，e 不为 0。

当创建成功时，e = 0，p 为解析器对象。

4. 解析数据

函数签名：

对输入 payload 进行解析，返回结果为 JSON 格式 [u8] 。返回的 JSON 将使用默认的 JSON 解析器进行完全解码（展开根数组和所有的对象）。

1. const char* parser_mutate(
2. void* parser,
3. const uint8_t* in_ptr, uint32_t in_len,
4. const void* uint8_t* out_ptr, uint32_t* out_len
5. );

void* parser: parser_new 生成的对象指针;

const uint8_t* in_ptr：输入 Payload 的指针;

uint32_t in_len: 输入 Payload 的 bytes 长度（不含 \0）;

const void* uint8_t* out_ptr:输出 JSON 字符串的指针（不含 \0）。当 out_ptr 指向为空时，表示输出为空。

uint32_t * out_len：输出 JSON 字符串长度。

返回值： 当调用成功时，返回值为 NULL。

5. 释放解析器

释放解析器对象内存。

函数签名： void parser_free(void* parser);

void* parser: parser_new 生成的对象指针。