Merge pull request #20049 from taosdata/docs/lispqin

doc: update immigrate OpenTSDB data by DataX to TDengine3.0  links

docs/en/25-application/03-immigrate.md → docs/en/25-application/_03-immigrate.md

@@ -184,7 +184,7 @@ TDengine supports the standard JDBC 3.0 interface for manipulating databases, bu
 
 To facilitate historical data migration, we provide a plug-in for the data synchronization tool DataX, which can automatically write data into TDengine.The automatic data migration of DataX can only support the data migration process of a single value model.
 
-For the specific usage of DataX and how to use DataX to write data to TDengine, please refer to [DataX-based TDengine Data Migration Tool](https://www.taosdata.com/blog/2021/10/26/3156.html).
+For the specific usage of DataX and how to use DataX to write data to TDengine, please refer to [DataX-based TDengine Data Migration Tool](https://www.taosdata.com/engineering/16401.html).
 
 After migrating via DataX, we found that we can significantly improve the efficiency of migrating historical data by starting multiple processes and migrating numerous metrics simultaneously. The following are some records of the migration process. We provide these as a reference for application migration.
 

docs/zh/25-application/_03-immigrate.md → docs/zh/25-application/03-immigrate.md

@@ -170,11 +170,110 @@ TDengine 支持标准的 JDBC 3.0 接口操纵数据库，你也可以使用其
 
 ### 1、使用工具自动迁移数据
 
-为了方便历史数据的迁移工作，我们为数据同步工具 DataX 提供了插件，能够将数据自动写入到 TDengine 中，需要注意的是 DataX 的自动化数据迁移只能够支持单值模型的数据迁移过程。
-
-DataX 具体的使用方式及如何使用 DataX 将数据写入 TDengine 请参见[基于 DataX 的 TDengine 数据迁移工具](https://www.taosdata.com/blog/2021/10/26/3156.html)。
-
-在对 DataX 进行迁移实践后，我们发现通过启动多个进程，同时迁移多个 metric 的方式，可以大幅度的提高迁移历史数据的效率，下面是迁移过程中的部分记录，希望这些能为应用迁移工作带来参考。
+为了方便历史数据的迁移工作，我们为数据同步工具 DataX 提供了适配 TDengine 3.0 的插件，能够将数据自动写入到 TDengine 中，需要注意的是 DataX 的自动化数据迁移只能够支持单值模型的数据迁移过程。
+
+#### 1.0 插件功能介绍
+1. TDengine30Reader 提供的功能：
+   1. 支持通过 SQL 进行数据筛选；
+   2. 根据时间间隔进行任务切分；
+   3. 支持 TDengine 的全部数据类型；
+   4. 支持批量读取，通过 batchSize 参数控制批量拉取结果集的大小，提高读取性能。
+2. TDengine30Writer 支持的功能：
+   1. 支持 OpenTSDB 的 json 格式的行协议，使用 TDengine 的 schemaless 方式写入 TDengine。
+   2. 支持批量写入，通过 batchSize 参数控制批量写入的数量，提高写入性能。
+
+#### 1.1 DataX 安装环境准备
+1. 需要安装 TDengine 客户端
+2. 需要安装 JDK 1.8 环境（运行 DataX）
+3. 需要安装 Python 环境（运行 DataX）
+4. 需要 maven 编译环境（如果不编译 DataX 则可以不安装 maven）
+
+#### 1.2 安装
+1. 下载源码
+~~~
+git clone https://github.com/taosdata/DataX.git
+~~~
+2. 编译打包
+~~~
+cd DataX
+mvn -U clean package assembly:assembly -Dmaven.test.skip=true
+~~~
+3. 安装
+~~~
+cp target/datax.tar.gz your_install_dir
+cd your_install_dir
+tar -zxvf dataX.tar.gz
+~~~
+
+#### 1.3 数据迁移 Job 的配置
+以一个从 OpenTSDB 到 TDengine 3.0 版本的数据迁移任务为例，配置文件 opentsdb2tdengine.json 如下：
+~~~
+{
+   "job":{
+     "content":[{
+       "reader": {
+         "name": "opentsdbreader",
+         "parameter": {
+           "endpoint": "http://192.168.1.180:4242",
+           "column": ["weather_temperature"],
+           "beginDateTime": "2021-01-01 00:00:00",
+           "endDateTime": "2021-01-01 01:00:00"
+         }
+       },
+     "writer": {
+       "name": "tdengine30writer",
+       "parameter": {
+            "username": "root",
+            "password": "taosdata",
+            "connection": [
+              {
+                "table": [
+                  "matric1"
+                ],
+                "jdbcUrl": "jdbc:TAOS://192.168.1.101:6030/test?timestampFormat=TIMESTAMP"
+              }
+            ],
+            "batchSize": 1000,
+            "ignoreTagsUnmatched": true
+          }
+       }
+     }],
+     "setting": {
+       "speed": {
+         "channel": 1
+       }
+     }
+   }
+ } 
+~~~
+配置说明：
+1. 上面的配置表示，从 192.168.1.180 的 OpenTSDB，到 192.168.1.101 的 TDengine 的迁移。迁移 metric 为 weather_temperature，时间从 2021-01-01 00:00:00 开始，到 2021-01-01 01:00:00 结束的数据。
+2. reader 使用 datax 的 opentsdbreader，parameter 的配置请参考：[opentsdbreader.md#配置参数](https://github.com/taosdata/DataX/blob/master/opentsdbreader/doc/opentsdbreader.md)
+3. tdengine30writer 的 parameter 中，user，password 为必须项，没有默认值。batchSize 不是必须项，默认值为 1。详细参考：[tdengine30writer.md#配置参数](https://github.com/taosdata/DataX/blob/master/tdengine30writer/doc/tdengine30writer-CN.md)
+4. TDengine 中，如果 dbname 指定的 database 不存在，则需要在迁移前创建数据库。
+
+#### 1.4 执行迁移任务
+~~~
+python bin/datax.py job/opentsdb2tdengine.json
+~~~
+
+#### 1.5 限制条件
+1. 目前，DataX 自带的 opentsdbreader 仅支持 OpenTSDB-2.3.X 版本。详细参考：[opentsdbreader#约束限制](https://github.com/alibaba/DataX/blob/master/opentsdbreader/doc/opentsdbreader.md#5-%E7%BA%A6%E6%9D%9F%E9%99%90%E5%88%B6)
+2. 数据迁移工具依赖 TDengine 客户端中的 `libtaos.so/taos.dll/libtaos.dylib`，需要与服务端对应版本的 TDengine-client。
+
+#### 1.6 其他
+1. FAQ
+   1. 如何估算一个数据迁移任务所需要的资源
+   DataX 的每个 reader 按照自己的 task 切分策略进行任务划分，具体请参考 DataX 的任务调度规则。在估算资源是，需要按照数据迁移的数据量，任务切分规则和网络带宽限制等综合考虑，最好以实际数据迁移测试结果为准。
+   2. TDengine30Writer 的 batchSize 设置多大效率最高？
+   batchSize 是控制批量写入的参数，在获取 batchSize 行纪录后，TDengineWriter 会向 TDengine 发送一次写入请求，这减少了与 TDengine 交互次数，从而提高了性能。从测试结果来看，batchSize 在 500-1000 范围内效率最高。
+   3. job 的配置中 channel 数为多少合适？
+   job 中的 channel 数为流量控制的参数，每个 channel 都需要开辟一块内存，用来缓存数据。如果 channel 设置过大，会引起 OOM，所以 channel 数并不是越大越好。增加 channel 数后，需要提高 JVM 内存大小。从测试结果来看，channel 在 1～6 的范围内都是合适，能够保证 DataX 的流量最大化即可。
+   4. java.sql.SQLException: TDengine ERROR (8000060b): Invalid client value
+   配置文件中 column 中没有配置 tbname，此时会触发行协议数据写入（行协议写入只会自动创建子表名，但需要提前创建好超级表），行协议写入的情况下不支持 TAG 数据类型为非 NCHAR，所以此种情况有两种解决方案：1.将 TAG 全部修改为 NCHAR 类型；2.在 Column 中配置好表名称这样不会触发行协议写入。
+   5. java.sql.SQLException: TDengine ERROR (8000060b): Timestamp data out of range
+   配置文件中 column 中没有配置 tbname，此时会触发行协议数据写入，且 TAG 全部为 NCHAR 类型，此时需要保证时间戳的一列名称为 _ts，而不能是其他名称（行协议写入下，默认将最后的时间戳写入到 _ts 一列，且不能随意命名）。若想避免请使用 tbname 指定表名以避免触发行协议写入。
+2. 在对 DataX 进行迁移实践后，我们发现通过启动多个进程，同时迁移多个 metric 的方式，可以大幅度的提高迁移历史数据的效率，下面是迁移过程中的部分记录，希望这些能为应用迁移工作带来参考。
 
 | DataX 实例个数 (并发进程个数) | 迁移记录速度 （条/秒) |
 | ----------------------------- | --------------------- |