diff --git a/.github/workflows/alioss-check.yml b/.github/workflows/alioss-check.yml index cfa696fbb..353e8dbcc 100644 --- a/.github/workflows/alioss-check.yml +++ b/.github/workflows/alioss-check.yml @@ -1,9 +1,6 @@ name: Check alioss in Changed Files on: - push: - branches: - - main pull_request: branches: - main @@ -11,7 +8,7 @@ on: workflow_dispatch: jobs: - todo-check: + img-check: runs-on: ubuntu-latest steps: @@ -26,13 +23,20 @@ jobs: git switch -c check_branch # Get the diff of the changes - DIFF=$(git diff origin/$GITHUB_BASE_REF check_branch) - - + echo Get the diff of the changes + DIFF=$(git diff origin/$GITHUB_BASE_REF check_branch -- . ':(exclude).github/workflows/alioss-check.yml') + if [ -z "$DIFF" ]; then + echo "No changes detected." + exit 0 + fi + # Check the diff for alioss - if echo "$DIFF" | grep -Eq '^\+.*(alioss)'; then - echo "alioss found in the changes. Please use upload to src/.vuepress/public/img." - # exit 1 - else - echo "No alioss found in changed content." + echo Check the diff for alioss + ALIOSS=$(echo "$DIFF" | grep -E '^\+.*(alioss)' | wc -l) + if [ "$ALIOSS" -eq 0 ]; then + echo "No alioss found in changed content."; + exit 0 fi + echo "alioss found in the changes. Please use upload to src/.vuepress/public/img." + echo "$DIFF" | grep -E '^\+.*(alioss)' | tee -a output.log + exit 1 diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts index 3db38da9b..e0b7acbc2 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts @@ -99,6 +99,8 @@ export const zhSidebar = { // children: 'structure', children: [ { text: '命令行工具', link: 'CLI' }, + { text: '监控工具', link: 'Monitor-Tool_apache' }, + { text: '集群管理工具', link: 'Maintenance-Tool_apache' }, ], }, { diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts index d7e01d492..4470c65a0 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts @@ -101,6 +101,9 @@ export const zhSidebar = { // children: 'structure', children: [ { text: '命令行工具', link: 'CLI' }, + { text: '监控工具', link: 'Monitor-Tool_timecho' }, + { text: '测试工具', link: 'Benchmark' }, + { text: '集群管理工具', link: 'Maintenance-Tool_timecho' }, ], }, { diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Benchmark.md b/src/zh/UserGuide/Master/Table/Tools-System/Benchmark.md new file mode 100644 index 000000000..aa7251fae --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Tools-System/Benchmark.md @@ -0,0 +1,370 @@ + + +# 测试工具 + +## 1 基本概述 + +IoT-benchmark 是基于 Java 和大数据环境开发的时序数据库基准测试工具，由清华大学软件学院研发并开源。它使用方便，支持多种写入以及查询方式，支持存储测试信息和结果以供进一步查询或分析，支持与 Tableau 集成以可视化测试结果。 + +下图1-1囊括了测试基准流程及其他扩展功能。这些流程可以由IoT-benchmark 统一来完成。IoT Benchmark 支持多种工作负载，包括**纯写入、纯查询、写入查询混合**等，支持**软硬件系统监控、测试指标度量**等监控功能，还实现了**初始化数据库自动化、测试数据分析及系统参数优化**等功能。 + +![](/img/bm1.png) + +图1-1 + +借鉴 YCSB 测试工具将工作负载生成、性能指标测量和数据库接口三个组件分离的设计思想，IoT-benchmark 的模块化设计如图1-2所示。与基于 YCSB 的测试工具系统不同的是，IoT-benchmark 增加了系统监控模块，支持测试数据和系统指标监控数据的持久化。此外也增加了一些特别针对时序数据场景的特殊负载测试功能，如支持物联网场景的批量写入和多种乱序数据写入模式。 + +![](/img/bm2.png) + +图1-2 + + +目前 IoT-benchmark 支持如下时间序列数据库、版本和连接方式： + +| 数据库 | 版本 | 连接方式 | +| :-------------- | :-------------- | :------------------------------------------------------- | +| InfluxDB | v1.x v2.0 | SDK | +| TimescaleDB | -- | jdbc | +| OpenTSDB | -- | Http Request | +| QuestDB | v6.0.7 | jdbc | +| TDengine | v2.2.0.2 | jdbc | +| VictoriaMetrics | v1.64.0 | Http Request | +| KairosDB | -- | Http Request | +| IoTDB | v2.0 v1.x v0.13 | jdbc、sessionByTablet、sessionByRecord、sessionByRecords | + +表1-1大数据测试基准对比 + +## 2 安装运行 + +### 前置条件 + +1. Java 8 +2. Maven 3.6+ +3. 对应的合适版本的数据库，如 Apache IoTDB 1.0 + + + +### 获取方式 + +- 获取二进制包：进入[这里](https://github.com/thulab/iot-benchmark/releases) 下载需要的安装包。下载下来为一个压缩文件，选择文件夹解压即可使用。 +- 源代码编译（可用户 Apache IoTDB 2.0 的测试）： + - 第一步（编译 IoTDB Session 最新包）：进入[官网](https://github.com/apache/iotdb/tree/rc/2.0.1)下载 IoTDB 源码，在根目录下运行命令 mvn clean package install -pl session -am -DskipTests 编译 IoTDB Session 的最新包。 + - 第二步（编译 IoTDB Benchmark 测试包）：进入[官网](https://github.com/thulab/iot-benchmark)下载源码，在根目录下运行 mvn clean package install -pl iotdb-2.0 -am -DskipTests 编译测试 Apache IoTDB 2.0版本的测试包，测试包位置与根目录的相对路径为 ./iotdb-2.0/target/iotdb-2.0-0.0.1/iotdb-2.0-0.0.1 + + +### 测试包结构 + +测试包的目录结构如下所示。其中测试配置文件为conf/config.properties，测试启动脚本为benchmark\.sh (Linux & MacOS) 和 benchmark.bat (Windows)，详细文件用途见下表所示。 + +```Shell +-rw-r--r--. 1 root root 2881 1月 10 01:36 benchmark.bat +-rwxr-xr-x. 1 root root 314 1月 10 01:36 benchmark.sh +drwxr-xr-x. 2 root root 24 1月 10 01:36 bin +-rwxr-xr-x. 1 root root 1140 1月 10 01:36 cli-benchmark.sh +drwxr-xr-x. 2 root root 107 1月 10 01:36 conf +drwxr-xr-x. 2 root root 4096 1月 10 01:38 lib +-rw-r--r--. 1 root root 11357 1月 10 01:36 LICENSE +-rwxr-xr-x. 1 root root 939 1月 10 01:36 rep-benchmark.sh +-rw-r--r--. 1 root root 14 1月 10 01:36 routine +``` + +| 名称 | 子文件 | 用途 | +| :--------------- | :---------------- | :------------------------ | +| benchmark.bat | - | Windows环境运行启动脚本 | +| benchmark.sh | - | Linux/Mac环境运行启动脚本 | +| bin | startup.sh | 初始化脚本文件夹 | +| conf | config.properties | 测试场景配置文件 | +| lib | - | 依赖库文件 | +| LICENSE | - | 许可文件 | +| cli-benchmark.sh | - | 一键化启动脚本 | +| routine | | 多项测试配置文件 | +| rep-benchmark.sh | | 多项测试启动脚本 | + +表1-2文件和文件夹列表用途 + +### 执行测试 + +1. 按照测试需求修改配置文件，主要参数介绍见 1.2 节，对应配置文件为conf/config.properties，**比如测试Apache IoTDB 1.0，则需要修改 DB_SWITCH=IoTDB-100-SESSION_BY_TABLET** +2. 启动被测时间序列数据库 +3. 通过运行 +4. 启动IoT-benchmark执行测试。执行中观测被测时间序列数据库和IoT-benchmark状态，执行完毕后查看结果和分析测试过程。 + +### 结果说明 + +测试的所有日志文件被存放于 logs 文件夹下，测试的结果在测试完成后被存放到 data/csvOutput 文件夹下，例如测试后我们得到了如下的结果矩阵： + +![](/img/bm4.png) + +- Result Matrix + - OkOperation：成功的对应操作次数 + - OkPoint：对于写入操作，是成功写入的点数；对于查询操作，是成功查询到的点数。 + - FailOperation：失败的对应操作次数 + - FailPoint：对于写入操作是写入失败的点数 +- Latency(mx) Matrix + - AVG：操作平均耗时 + - MIN：操作最小耗时 + - Pn：操作整体分布的对应分位值，比如P25是下四分位数 + + + +## 主要参数 + + +### IoTDB服务模型 + +参数`IoTDB_DIALECT_MODE`支持tree、table,默认值为tree。 + +- 当被测数据库为IoTDB-2.0及以上版本时需指定sql_dialect, 并且一个IoTDB只能指定一种。 +- sql_dialect等于table时，要满足：device数为table数的整数倍，table数为database数的整数倍 +- sql_dialect等于tree时，要满足：device数量 >= database数量 +- 表模型模式下，调整参数如下： + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :---------------------- | :------- | :------- | :----------------------------------------------------------- | +| IoTDB_TABLE_NAME_PREFIX | 字符串 | table_ | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，表名称前缀 | +| DATA_CLIENT_NUMBER | 整数 | 10 | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，client数为table数的整数倍 | +| SENSOR_NUMBER | 整数 | 10 | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，则控制属性列数量 | +| IoTDB_TABLE_NUMBER | 整数 | 1 | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，表的数量 | + +### 工作模式 + +工作模式参数“`BENCHMARK_WORK_MODE`”可选项有如下四种模式： + +- 常用测试模式：结合配置`OPERATION_PROPORTION`参数达到“纯写入”、“纯查询”和“读写混合”的测试操作。 +- 生成数据模式：为了生成可以重复使用的数据集，iot-benchmark提供生成数据集的模式，生成数据集到FILE_PATH，以供后续使用正确性写入模式和正确性查询模式使用。 +- 单数据库正确性写入模式：为了验证数据集写入的正确性，您可以使用该模式写入生成数据模式中生成的数据集，目前该模式仅支持IoTDB v1.0 及更新的版本和InfluxDB v1.x。 +- 单数据库正确性查询模式：在运行这个模式之前需要先使用正确性写入模式写入数据到数据库。为了验证数据集写入的正确性，您可以使用该模式查询写入到数据库中的数据集，目前该模式仅支持IoTDB v1.0 和 InfluxDB v1.x。 + +| **模式名称** | **BENCHMARK_WORK_MODE** | **模式内容** | +| :--------------------- | :---------------------- | :------------------------------- | +| 常规测试模式 | testWithDefaultPath | 支持多种读和写操作的混合负载 | +| 生成数据模式 | generateDataMode | 生成Benchmark本身识别的数据 | +| 单数据库正确性写入模式 | verificationWriteMode | 需要配置 FILE_PATH 以及 DATA_SET | +| 单数据库正确性查询模式 | verificationQueryMode | 需要配置 FILE_PATH 以及 DATA_SET | + +### 服务器连接信息 + +工作模式指定后，被测时序数据库的信息会通过如下参数告知IoT-benchmark + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :----------- | :------- | :-------------------------- | :---------------------------------------------- | +| DB_SWITCH | 字符串 | IoTDB-200-SESSION_BY_TABLET | 被测时序数据库类型 | +| HOST | 字符串 | 127.0.0.1 | 被测时序数据库网络地址 | +| PORT | 整数 | 6667 | 被测时序数据库网络端口 | +| USERNAME | 字符串 | root | 被测时序数据库登录用户名 | +| PASSWORD | 字符串 | root | 被测时序数据库登录用户的密码 | +| DB_NAME | 字符串 | test | 被测时序数据库名称 | +| TOKEN | 字符串 | | 被测时序数据库连接认证Token（InfluxDB 2.0使用） | + +### 写入场景 + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :------------------------- | :------- | :------------------------ | :----------------------------------------------------------- | +| CLIENT_NUMBER | 整数 | 100 | 客户端总数 | +| GROUP_NUMBER | 整数 | 20 | 数据库的数量；仅针对IoTDB。 | +| DEVICE_NUMBER | 整数 | 100 | 设备总数 | +| SENSOR_NUMBER | 整数 | 300 | 每个设备的传感器总数； **如果使用 IoTDB 表模型，则控制属性列数量** | +| INSERT_DATATYPE_PROPORTION | 字符串 | 1:1:1:1:1:1 | 设备的数据类型比例，BOOLEAN:INT32:INT64:FLOAT:DOUBLE:TEXT | +| POINT_STEP | 整数 | 1000 | 数据间时间戳间隔，即生成的数据两个时间戳之间的固定长度。 | +| OP_MIN_INTERVAL | 整数 | 0 | 操作最小执行间隔：若操作耗时大于该值则立即执行下一个，否则等待 (OP_MIN_INTERVAL-实际执行时间) ms；如果为0，则参数不生效；如果为-1，则其值和POINT_STEP一致 | +| IS_OUT_OF_ORDER | 布尔 | false | 是否乱序写入 | +| OUT_OF_ORDER_RATIO | 浮点数 | 0.3 | 乱序写入的数据比例 | +| BATCH_SIZE_PER_WRITE | 整数 | 1 | 批写入数据行数（一次写入多少行数据） | +| START_TIME | 时间 | 2022-10-30T00:00:00+08:00 | 写入数据的开始时间戳；以该时间戳为起点开始模拟创建数据时间戳。 | +| LOOP | 整数 | 86400 | 总操作次数：具体每种类型操作会按OPERATION_PROPORTION定义的比例划分 | +| OPERATION_PROPORTION | 字符 | 1:0:0:0:0:0:0:0:0:0:0 | # 各操作的比例,按照顺序为 写入:Q1:Q2:Q3:Q4:Q5:Q6:Q7:Q8:Q9:Q10, 请注意使用英文冒号。比例中的每一项是整数。 | + + +### 查询场景 + +| 参数名称 | 类型 | 示例 | 系统描述 | +| :------------------- | :--- | :-------------------- | :----------------------------------------------------------- | +| QUERY_DEVICE_NUM | 整数 | 2 | 每条查询语句中查询涉及到的设备数量 | +| QUERY_SENSOR_NUM | 整数 | 2 | 每条查询语句中查询涉及到的传感器数量 | +| QUERY_AGGREGATE_FUN | 字符 | count | 在聚集查询中使用的聚集函数，比如count、avg、sum、max_time等 | +| STEP_SIZE | 整数 | 1 | 时间过滤条件的时间起点变化步长，若设为0则每个查询的时间过滤条件是一样的，单位：POINT_STEP | +| QUERY_INTERVAL | 整数 | 250000 | 起止时间的查询中开始时间与结束时间之间的时间间隔，和Group By中的时间间隔 | +| QUERY_LOWER_VALUE | 整数 | -5 | 条件查询子句时的参数，where xxx > QUERY_LOWER_VALUE | +| GROUP_BY_TIME_UNIT | 整数 | 20000 | Group by语句中的组的大小 | +| LOOP | 整数 | 10 | 总操作次数：具体每种类型操作会按OPERATION_PROPORTION定义的比例划分 | +| OPERATION_PROPORTION | 字符 | 0:0:0:0:0:0:0:0:0:0:1 | 写入:Q1:Q2:Q3:Q4:Q5:Q6:Q7:Q8:Q9:Q10 | + + +### 操作比例 + +| 编号 | 查询类型 | IoTDB 示例 SQL | +| :--- | :--------------------------- | :----------------------------------------------------------- | +| Q1 | 精确点查询 | select v1 from root.db.d1 where time = ? | +| Q2 | 时间范围查询 | select v1 from root.db.d1 where time > ? and time < ? | +| Q3 | 带值过滤的时间范围查询 | select v1 from root.db.d1 where time > ? and time < ? and v1 > ? | +| Q4 | 时间范围聚合查询 | select count(v1) from root.db.d1 where and time > ? and time < ? | +| Q5 | 带值过滤的全时间范围聚合查询 | select count(v1) from root.db.d1 where v1 > ? | +| Q6 | 带值过滤的时间范围聚合查询 | select count(v1) from root.db.d1 where v1 > ? and time > ? and time < ? | +| Q7 | 时间分组聚合查询 | select count(v1) from root.db.d1 group by ([?, ?), ?, ?) | +| Q8 | 最新点查询 | select last v1 from root.db.d1 | +| Q9 | 倒序范围查询 | select v1 from root.sg.d1 where time > ? and time < ? order by time desc | +| Q10 | 倒序带值过滤的范围查询 | select v1 from root.sg.d1 where time > ? and time < ? and v1 > ? order by time desc | + +### 测试过程和测试结果持久化 + +IoT-benchmark目前支持通过配置参数将测试过程和测试结果持久化: + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :-------------------- | :------- | :-------- | :----------------------------------------------------------- | +| TEST_DATA_PERSISTENCE | 字符串 | None | 结果持久化选择，支持None，IoTDB，MySQL和CSV | +| RECORD_SPLIT | 布尔 | true | 是否将结果划分后输出到多个记录, IoTDB 暂时不支持 | +| RECORD_SPLIT_MAX_LINE | 整数 | 10000000 | 记录行数的上限（每个数据库表或CSV文件按照总行数为1千万切分存放） | +| TEST_DATA_STORE_IP | 字符串 | 127.0.0.1 | 输出数据库的IP地址 | +| TEST_DATA_STORE_PORT | 整数 | 6667 | 输出数据库的端口号 | +| TEST_DATA_STORE_DB | 字符串 | result | 输出数据库的名称 | +| TEST_DATA_STORE_USER | 字符串 | root | 输出数据库的用户名 | +| TEST_DATA_STORE_PW | 字符串 | root | 输出数据库的用户密码 | + +- 如果我们设置“`TEST_DATA_PERSISTENCE=CSV`”，测试执行时和执行完毕后我们可以在IoT-benchmark根目录下看到新生成的`data`文件夹，其下包含`csv`文件夹记录测试过程；`csvOutput`文件夹记录测试结果。 +- 如果我们设置“`TEST_DATA_PERSISTENCE=MySQL`”，它会在测试开始前在指定的MySQL数据库中创建命名如“testWithDefaultPath_被测数据库名称_备注_测试启动时间”的数据表记录测试过程；会在名为“CONFIG”的数据表（如果不存在则创建该表），写入本次测试的配置信息；当测试完成时会在名为“FINAL_RESULT”的数据表（如果不存在则创建该表）中写入本次测试结果。 + +### 自动化脚本 + +#### 一键化启动脚本 + +您可以通过`cli-benchmark.sh`脚本一键化启动IoTDB、监控的IoTDB Benchmark和测试的IoTDB Benchmark，但需要注意该脚本启动时会清理IoTDB中的**所有数据**，请谨慎使用。 + +首先，您需要修改`cli-benchmark.sh`中的`IOTDB_HOME`参数为您本地的IoTDB所在的文件夹。 + +然后您可以使用脚本启动测试 + +```Bash +> ./cli-benchmark.sh +``` + +测试完成后您可以在`logs`文件夹中查看测试相关日志，在`server-logs`文件夹中查看监控相关日志。 + +#### 自动执行多项测试 + +通常，除非与其他测试结果进行比较，否则单个测试是没有意义的。因此，我们提供了一个接口来通过一次启动执行多个测试。 + +- 配置 routine + +这个文件的每一行应该是每个测试过程会改变的参数（否则就变成复制测试）。例如，"例程"文件是： + +```Plain +LOOP=10 DEVICE_NUMBER=100 TEST +LOOP=20 DEVICE_NUMBER=50 TEST +LOOP=50 DEVICE_NUMBER=20 TEST +``` + +然后依次执行3个LOOP参数分别为10、20、50的测试过程。 + +> 注意： +> +> 您可以使用“LOOP=20 DEVICE_NUMBER=10 TEST”等格式更改每个测试中的多个参数，不允许使用不必要的空间。 关键字"TEST"意味着新的测试开始。如果您更改不同的参数，更改后的参数将保留在下一次测试中。 + +- 开始测试 + +配置文件routine后，您可以通过启动脚本启动多测试任务： + +```Bash +> ./rep-benchmark.sh +``` + +然后测试信息将显示在终端中。 + +> 注意： +> +> 如果您关闭终端或失去与客户端机器的连接，测试过程将终止。 如果输出传输到终端，则与任何其他情况相同。 + +使用此接口通常需要很长时间，您可能希望将测试过程作为守护程序执行。这样，您可以通过启动脚本将测试任务作为守护程序启动： + +```Bash +> ./rep-benchmark.sh > /dev/null 2>&1 & +``` + +在这种情况下，如果您想知道发生了什么，可以通过以下命令查看日志信息： + +```Bash +> cd ./logs +> tail -f log_info.log +``` + +## 测试示例 + +以IoTDB 2.0为例，使用IoT-Benchemark测试表模型写入及查询，修改IoT-Benchemark配置文件如下： + +```Properties +----------------------Main Configurations---------------------- +BENCHMARK_WORK_MODE=testWithDefaultPath +IoTDB_DIALECT_MODE=TABLE +DB_SWITCH=IoTDB-200-SESSION_BY_TABLET +GROUP_NUMBER=1 +IoTDB_TABLE_NUMBER=1 +DEVICE_NUMBER=60 +REAL_INSERT_RATE=1.0 +SENSOR_NUMBER=10 +OPERATION_PROPORTION=1:0:0:0:0:0:0:0:0:0:0:0 +SCHEMA_CLIENT_NUMBER=10 +DATA_CLIENT_NUMBER=10 +LOOP=10 +BATCH_SIZE_PER_WRITE=10 +DEVICE_NUM_PER_WRITE=1 +START_TIME=2025-01-01T00:00:00+08:00 +POINT_STEP=1000 +INSERT_DATATYPE_PROPORTION=1:1:1:1:1:1:0:0:0:0 +VECTOR=true +``` + +在被测数据库正常运行下，启动IoT-Benchmark服务，等待执行结束后，可查看打印结果如下： + +```Shell +Create schema cost 0.88 second +Test elapsed time (not include schema creation): 4.60 second +----------------------------------------------------------Result Matrix---------------------------------------------------------- +Operation okOperation okPoint failOperation failPoint throughput(point/s) +INGESTION 600 60000 0 0 13054.42 +PRECISE_POINT 0 0 0 0 0.00 +TIME_RANGE 0 0 0 0 0.00 +VALUE_RANGE 0 0 0 0 0.00 +AGG_RANGE 0 0 0 0 0.00 +AGG_VALUE 0 0 0 0 0.00 +AGG_RANGE_VALUE 0 0 0 0 0.00 +GROUP_BY 0 0 0 0 0.00 +LATEST_POINT 0 0 0 0 0.00 +RANGE_QUERY_DESC 0 0 0 0 0.00 +VALUE_RANGE_QUERY_DESC 0 0 0 0 0.00 +GROUP_BY_DESC 0 0 0 0 0.00 +--------------------------------------------------------------------------------------------------------------------------------- + +--------------------------------------------------------------------------Latency (ms) Matrix-------------------------------------------------------------------------- +Operation AVG MIN P10 P25 MEDIAN P75 P90 P95 P99 P999 MAX SLOWEST_THREAD +INGESTION 41.77 0.95 1.41 2.27 6.76 24.14 63.42 127.18 1260.92 1265.72 1265.49 2581.91 +PRECISE_POINT 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +TIME_RANGE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +VALUE_RANGE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +AGG_RANGE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +AGG_VALUE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +AGG_RANGE_VALUE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +GROUP_BY 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +LATEST_POINT 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +RANGE_QUERY_DESC 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +VALUE_RANGE_QUERY_DESC 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +GROUP_BY_DESC 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +----------------------------------------------------------------------------------------------------------------------------------------------------------------------- +``` \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Maintenance-Tool_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/Maintenance-Tool_apache.md new file mode 100644 index 000000000..57b527ccb --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Tools-System/Maintenance-Tool_apache.md @@ -0,0 +1,229 @@ + + +# 集群管理工具 + +## 数据文件夹概览工具 + +IoTDB数据文件夹概览工具用于打印出数据文件夹的结构概览信息，工具位置为 tools/tsfile/print-iotdb-data-dir。 + +### 用法 + +- Windows: + +```bash +.\print-iotdb-data-dir.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-iotdb-data-dir.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"IoTDB_data_dir_overview.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-iotdb-data-dir.bat D:\github\master\iotdb\data\datanode\data +```````````````````````` +Starting Printing the IoTDB Data Directory Overview +```````````````````````` +output save path:IoTDB_data_dir_overview.txt +data dir num:1 +143 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +|============================================================== +|D:\github\master\iotdb\data\datanode\data +|--sequence +| |--root.redirect0 +| | |--1 +| | | |--0 +| |--root.redirect1 +| | |--2 +| | | |--0 +| |--root.redirect2 +| | |--3 +| | | |--0 +| |--root.redirect3 +| | |--4 +| | | |--0 +| |--root.redirect4 +| | |--5 +| | | |--0 +| |--root.redirect5 +| | |--6 +| | | |--0 +| |--root.sg1 +| | |--0 +| | | |--0 +| | | |--2760 +|--unsequence +|============================================================== +````````````````````````` + +## TsFile概览工具 + +TsFile概览工具用于以概要模式打印出一个TsFile的内容，工具位置为 tools/tsfile/print-tsfile。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-sketch.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-tsfile-sketch.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"TsFile_sketch_view.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile.bat D:\github\master\1669359533965-1-0-0.tsfile D:\github\master\sketch.txt +```````````````````````` +Starting Printing the TsFile Sketch +```````````````````````` +TsFile path:D:\github\master\1669359533965-1-0-0.tsfile +Sketch save path:D:\github\master\sketch.txt +148 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +-------------------------------- TsFile Sketch -------------------------------- +file path: D:\github\master\1669359533965-1-0-0.tsfile +file length: 2974 + + POSITION| CONTENT + -------- ------- + 0| [magic head] TsFile + 6| [version number] 3 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1, num of Chunks:3 + 7| [Chunk Group Header] + | [marker] 0 + | [deviceID] root.sg1.d1 + 20| [Chunk] of root.sg1.d1.s1, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [chunk header] marker=5, measurementID=s1, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 893| [Chunk] of root.sg1.d1.s2, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [chunk header] marker=5, measurementID=s2, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 1766| [Chunk] of root.sg1.d1.s3, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [chunk header] marker=5, measurementID=s3, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1 ends + 2656| [marker] 2 + 2657| [TimeseriesIndex] of root.sg1.d1.s1, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [ChunkIndex] offset=20 + 2728| [TimeseriesIndex] of root.sg1.d1.s2, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [ChunkIndex] offset=893 + 2799| [TimeseriesIndex] of root.sg1.d1.s3, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [ChunkIndex] offset=1766 + 2870| [IndexOfTimerseriesIndex Node] type=LEAF_MEASUREMENT + | + | +||||||||||||||||||||| [TsFileMetadata] begins + 2891| [IndexOfTimerseriesIndex Node] type=LEAF_DEVICE + | + | + | [meta offset] 2656 + | [bloom filter] bit vector byte array length=31, filterSize=256, hashFunctionSize=5 +||||||||||||||||||||| [TsFileMetadata] ends + 2964| [TsFileMetadataSize] 73 + 2968| [magic tail] TsFile + 2974| END of TsFile +---------------------------- IndexOfTimerseriesIndex Tree ----------------------------- + [MetadataIndex:LEAF_DEVICE] + └──────[root.sg1.d1,2870] + [MetadataIndex:LEAF_MEASUREMENT] + └──────[s1,2657] +---------------------------------- TsFile Sketch End ---------------------------------- +````````````````````````` + +解释： + +- 以"|"为分隔，左边是在TsFile文件中的实际位置，右边是梗概内容。 +- "|||||||||||||||||||||"是为增强可读性而添加的导引信息，不是TsFile中实际存储的数据。 +- 最后打印的"IndexOfTimerseriesIndex Tree"是对TsFile文件末尾的元数据索引树的重新整理打印，便于直观理解，不是TsFile中存储的实际数据。 + +## TsFile Resource概览工具 + +TsFile resource概览工具用于打印出TsFile resource文件的内容，工具位置为 tools/tsfile/print-tsfile-resource-files。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-resource-files.bat +``` + +- Linux or MacOs: + +``` +./print-tsfile-resource-files.sh +``` + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +147 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +230 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +231 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +233 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +237 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file folder D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 finished. +````````````````````````` + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +178 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +186 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +187 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +188 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +192 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource finished. +````````````````````````` diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Maintenance-Tool_timecho.md b/src/zh/UserGuide/Master/Table/Tools-System/Maintenance-Tool_timecho.md new file mode 100644 index 000000000..1c206edc5 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Tools-System/Maintenance-Tool_timecho.md @@ -0,0 +1,1013 @@ + + +# 集群管理工具 + +## 集群管理工具 + +IoTDB 集群管理工具是一款易用的运维工具（企业版工具）。旨在解决 IoTDB 分布式系统多节点的运维难题，主要包括集群部署、集群启停、弹性扩容、配置更新、数据导出等功能，从而实现对复杂数据库集群的一键式指令下发，极大降低管理难度。本文档将说明如何用集群管理工具远程部署、配置、启动和停止 IoTDB 集群实例。 + +### 环境准备 + +本工具为 TimechoDB（基于IoTDB的企业版数据库）配套工具，您可以联系您的销售获取工具下载方式。 + +IoTDB 要部署的机器需要依赖jdk 8及以上版本、lsof、netstat、unzip功能如果没有请自行安装，可以参考文档最后的一节环境所需安装命令。 + +提示:IoTDB集群管理工具需要使用有root权限的账号 + +### 部署方法 + +#### 下载安装 + +本工具为TimechoDB（基于IoTDB的企业版数据库）配套工具，您可以联系您的销售获取工具下载方式。 + +注意：由于二进制包仅支持GLIBC2.17 及以上版本，因此最低适配Centos7版本 + +* 在iotd目录内输入以下指令后： + +```bash +bash install-iotdbctl.sh +``` + +即可在之后的 shell 内激活 iotdbctl 关键词，如检查部署前所需的环境指令如下所示： + +```bash +iotdbctl cluster check example +``` + +* 也可以不激活iotd直接使用 <iotdbctl absolute path>/sbin/iotdbctl 来执行命令，如检查部署前所需的环境： + +```bash +/sbin/iotdbctl cluster check example +``` + +### 系统结构 + +IoTDB集群管理工具主要由config、logs、doc、sbin目录组成。 + +* `config`存放要部署的集群配置文件如果要使用集群部署工具需要修改里面的yaml文件。 +* `logs` 存放部署工具日志，如果想要查看部署工具执行日志请查看`logs/iotd_yyyy_mm_dd.log`。 +* `sbin` 存放集群部署工具所需的二进制包。 +* `doc` 存放用户手册、开发手册和推荐部署手册。 + + +### 集群配置文件介绍 + +* 在`iotdbctl/config` 目录下有集群配置的yaml文件，yaml文件名字就是集群名字yaml 文件可以有多个，为了方便用户配置yaml文件在iotd/config目录下面提供了`default_cluster.yaml`示例。 +* yaml 文件配置由`global`、`confignode_servers`、`datanode_servers`、`grafana_server`、`prometheus_server`四大部分组成 +* global 是通用配置主要配置机器用户名密码、IoTDB本地安装文件、Jdk配置等。在`iotdbctl/config`目录中提供了一个`default_cluster.yaml`样例数据， + 用户可以复制修改成自己集群名字并参考里面的说明进行配置IoTDB集群，在`default_cluster.yaml`样例中没有注释的均为必填项，已经注释的为非必填项。 + +例如要执行`default_cluster.yaml`检查命令则需要执行命令`iotdbctl cluster check default_cluster`即可， +更多详细命令请参考下面命令列表。 + + + +| 参数 | 说明 | 是否必填 | +|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------| +| iotdb_zip_dir | IoTDB 部署分发目录，如果值为空则从`iotdb_download_url`指定地址下载 | 非必填 | +| iotdb_download_url | IoTDB 下载地址，如果`iotdb_zip_dir` 没有值则从指定地址下载 | 非必填 | +| jdk_tar_dir | jdk 本地目录，可使用该 jdk 路径进行上传部署至目标节点。 | 非必填 | +| jdk_deploy_dir | jdk 远程机器部署目录，会将 jdk 部署到该目录下面，与下面的`jdk_dir_name`参数构成完整的jdk部署目录即 `/` | 非必填 | +| jdk_dir_name | jdk 解压后的目录名称默认是jdk_iotdb | 非必填 | +| iotdb_lib_dir | IoTDB lib 目录或者IoTDB 的lib 压缩包仅支持.zip格式 ，仅用于IoTDB升级，默认处于注释状态，如需升级请打开注释修改路径即可。如果使用zip文件请使用zip 命令压缩iotdb/lib目录例如 zip -r lib.zip apache\-iotdb\-1.2.0/lib/* | 非必填 | +| user | ssh登陆部署机器的用户名 | 必填 | +| password | ssh登录的密码, 如果password未指定使用pkey登陆, 请确保已配置节点之间ssh登录免密钥 | 非必填 | +| pkey | 密钥登陆如果password有值优先使用password否则使用pkey登陆 | 非必填 | +| ssh_port | ssh登录端口 | 必填 | +| iotdb_admin_user | iotdb服务用户名默认root | 非必填 | +| iotdb_admin_password | iotdb服务密码默认root | 非必填 | +| deploy_dir | IoTDB 部署目录，会把 IoTDB 部署到该目录下面与下面的`iotdb_dir_name`参数构成完整的IoTDB 部署目录即 `/` | 必填 | +| iotdb_dir_name | IoTDB 解压后的目录名称默认是iotdb | 非必填 | +| datanode-env.sh | 对应`iotdb/config/datanode-env.sh` ,在`global`与`confignode_servers`同时配置值时优先使用`confignode_servers`中的值 | 非必填 | +| confignode-env.sh | 对应`iotdb/config/confignode-env.sh`,在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值 | 非必填 | +| iotdb-common.properties | 对应`iotdb/config/iotdb-common.properties` | 非必填 | +| cn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`confignode_servers`同时配置值时优先使用`confignode_servers`中的值，对应`iotdb/config/iotdb-system.properties`中的`cn_seed_config_node` | 必填 | +| dn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值，对应`iotdb/config/iotdb-system.properties`中的`dn_seed_config_node` | 必填 | + +其中datanode-env.sh 和confignode-env.sh 可以配置额外参数extra_opts，当该参数配置后会在datanode-env.sh 和confignode-env.sh 后面追加对应的值，可参考default_cluster.yaml，配置示例如下: +datanode-env.sh: +extra_opts: | +IOTDB_JMX_OPTS="$IOTDB_JMX_OPTS -XX:+UseG1GC" +IOTDB_JMX_OPTS="$IOTDB_JMX_OPTS -XX:MaxGCPauseMillis=200" + + +* confignode_servers 是部署IoTDB Confignodes配置，里面可以配置多个Confignode + 默认将第一个启动的ConfigNode节点node1当作Seed-ConfigNode + +| 参数 | 说明 | 是否必填 | +|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------| +| name | Confignode 名称 | 必填 | +| deploy_dir | IoTDB config node 部署目录 | 必填｜ | +| cn_internal_address | 对应iotdb/内部通信地址，对应`iotdb/config/iotdb-system.properties`中的`cn_internal_address` | 必填 | +| cn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`confignode_servers`同时配置值时优先使用`confignode_servers`中的值，对应`iotdb/config/iotdb-confignode.properties`中的`cn_seed_config_node` | 必填 | +| cn_internal_port | 内部通信端口，对应`iotdb/config/iotdb-system.properties`中的`cn_internal_port` | 必填 | +| cn_consensus_port | 对应`iotdb/config/iotdb-system.properties`中的`cn_consensus_port` | 非必填 | +| cn_data_dir | 对应`iotdb/config/iotdb-system.properties`中的`cn_data_dir` | 必填 | +| iotdb-system.properties | 对应`iotdb/config/iotdb-system.properties`在`global`与`confignode_servers`同时配置值优先使用confignode_servers中的值 | 非必填 | + +* datanode_servers 是部署IoTDB Datanodes配置，里面可以配置多个Datanode + +| 参数 | 说明 | 是否必填 | +| -------------------------- | ------------------------------------------------------------ | -------- | +| name | Datanode 名称 | 必填 | +| deploy_dir | IoTDB data node 部署目录，注:该目录不能与下面的IoTDB config node部署目录相同 | 必填 | +| dn_rpc_address | datanode rpc 地址对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_address` | 必填 | +| dn_internal_address | 内部通信地址，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_address` | 必填 | +| dn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值，对应`iotdb/config/iotdb-datanode.properties`中的`dn_seed_config_node`，推荐使用 SeedConfigNode | 必填 | +| dn_rpc_port | datanode rpc端口地址，对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_port` | 必填 | +| dn_internal_port | 内部通信端口，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_port` | 必填 | +| iotdb-system.properties | 对应`iotdb/config/iotdb-system.properties`在`global`与`datanode_servers`同时配置值优先使用`datanode_servers`中的值 | 非必填 | + + +| 参数 | 说明 |是否必填| +|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--- | +| name | Datanode 名称 |必填| +| deploy_dir | IoTDB data node 部署目录 |必填| +| dn_rpc_address | datanode rpc 地址对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_address` |必填| +| dn_internal_address | 内部通信地址，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_address` |必填| +| dn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值，对应`iotdb/config/iotdb-system.properties`中的`dn_seed_config_node` |必填| +| dn_rpc_port | datanode rpc端口地址，对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_port` |必填| +| dn_internal_port | 内部通信端口，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_port` |必填| +| iotdb-system.properties | 对应`iotdb/config/iotdb-common.properties`在`global`与`datanode_servers`同时配置值优先使用`datanode_servers`中的值 |非必填| + +* grafana_server 是部署Grafana 相关配置 + +| 参数 | 说明 | 是否必填 | +|--------------------|------------------|-------------------| +| grafana_dir_name | grafana 解压目录名称 | 非必填默认grafana_iotdb | +| host | grafana 部署的服务器ip | 必填 | +| grafana_port | grafana 部署机器的端口 | 非必填，默认3000 | +| deploy_dir | grafana 部署服务器目录 | 必填 | +| grafana_tar_dir | grafana 压缩包位置 | 必填 | +| dashboards | dashboards 所在的位置 | 非必填,多个用逗号隔开 | + +* prometheus_server 是部署Prometheus 相关配置 + +| 参数 | 说明 | 是否必填 | +|--------------------------------|------------------|-----------------------| +| prometheus_dir_name | prometheus 解压目录名称 | 非必填默认prometheus_iotdb | +| host | prometheus 部署的服务器ip | 必填 | +| prometheus_port | prometheus 部署机器的端口 | 非必填，默认9090 | +| deploy_dir | prometheus 部署服务器目录 | 必填 | +| prometheus_tar_dir | prometheus 压缩包位置 | 必填 | +| storage_tsdb_retention_time | 默认保存数据天数 默认15天 | 非必填 | +| storage_tsdb_retention_size | 指定block可以保存的数据大小默认512M ，注意单位KB, MB, GB, TB, PB, EB | 非必填 | + +如果在config/xxx.yaml的`iotdb-system.properties`和`iotdb-system.properties`中配置了metrics,则会自动把配置放入到promethues无需手动修改 + +注意:如何配置yaml key对应的值包含特殊字符如:等建议整个value使用双引号，对应的文件路径中不要使用包含空格的路径，防止出现识别出现异常问题。 + +### 使用场景 + +#### 清理数据场景 + +* 清理集群数据场景会删除IoTDB集群中的data目录以及yaml文件中配置的`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`和`ext`目录。 +* 首先执行停止集群命令、然后在执行集群清理命令。 +```bash +iotdbctl cluster stop default_cluster +iotdbctl cluster clean default_cluster +``` + +#### 集群销毁场景 + +* 集群销毁场景会删除IoTDB集群中的`data`、`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`、`ext`、`IoTDB`部署目录、 + grafana部署目录和prometheus部署目录。 +* 首先执行停止集群命令、然后在执行集群销毁命令。 + + +```bash +iotdbctl cluster stop default_cluster +iotdbctl cluster destroy default_cluster +``` + +#### 集群升级场景 + +* 集群升级首先需要在config/xxx.yaml中配置`iotdb_lib_dir`为要上传到服务器的jar所在目录路径（例如iotdb/lib）。 +* 如果使用zip文件上传请使用zip 命令压缩iotdb/lib目录例如 zip -r lib.zip apache-iotdb-1.2.0/lib/* +* 执行上传命令、然后执行重启IoTDB集群命令即可完成集群升级 + +```bash +iotdbctl cluster dist-lib default_cluster +iotdbctl cluster restart default_cluster +``` + +#### 集群配置文件的热部署场景 + +* 首先修改在config/xxx.yaml中配置。 +* 执行分发命令、然后执行热部署命令即可完成集群配置的热部署 + +```bash +iotdbctl cluster dist-conf default_cluster +iotdbctl cluster reload default_cluster +``` + +#### 集群扩容场景 + +* 首先修改在config/xxx.yaml中添加一个datanode 或者confignode 节点。 +* 执行集群扩容命令 +```bash +iotdbctl cluster scaleout default_cluster +``` + +#### 集群缩容场景 + +* 首先在config/xxx.yaml中找到要缩容的节点名字或者ip+port（其中confignode port 是cn_internal_port、datanode port 是rpc_port） +* 执行集群缩容命令 +```bash +iotdbctl cluster scalein default_cluster +``` + +#### 已有IoTDB集群，使用集群部署工具场景 + +* 配置服务器的`user`、`passwod`或`pkey`、`ssh_port` +* 修改config/xxx.yaml中IoTDB 部署路径，`deploy_dir`（IoTDB 部署目录）、`iotdb_dir_name`(IoTDB解压目录名称,默认是iotdb) + 例如IoTDB 部署完整路径是`/home/data/apache-iotdb-1.1.1`则需要修改yaml文件`deploy_dir:/home/data/`、`iotdb_dir_name:apache-iotdb-1.1.1` +* 如果服务器不是使用的java_home则修改`jdk_deploy_dir`(jdk 部署目录)、`jdk_dir_name`(jdk解压后的目录名称,默认是jdk_iotdb)，如果使用的是java_home 则不需要修改配置 + 例如jdk部署完整路径是`/home/data/jdk_1.8.2`则需要修改yaml文件`jdk_deploy_dir:/home/data/`、`jdk_dir_name:jdk_1.8.2` +* 配置`cn_seed_config_node`、`dn_seed_config_node` +* 配置`confignode_servers`中`iotdb-system.properties`里面的`cn_internal_address`、`cn_internal_port`、`cn_consensus_port`、`cn_system_dir`、 + `cn_consensus_dir`里面的值不是IoTDB默认的则需要配置否则可不必配置 +* 配置`datanode_servers`中`iotdb-system.properties`里面的`dn_rpc_address`、`dn_internal_address`、`dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`等 +* 执行初始化命令 + +```bash +iotdbctl cluster init default_cluster +``` + +#### 一键部署IoTDB、Grafana和Prometheus 场景 + +* 配置`iotdb-system.properties` 打开metrics接口 +* 配置Grafana 配置，如果`dashboards` 有多个就用逗号隔开，名字不能重复否则会被覆盖。 +* 配置Prometheus配置，IoTDB 集群配置了metrics 则无需手动修改Prometheus 配置会根据哪个节点配置了metrics，自动修改Prometheus 配置。 +* 启动集群 + +```bash +iotdbctl cluster start default_cluster +``` + +更加详细参数请参考上方的 集群配置文件介绍 + + +### 命令格式 + +本工具的基本用法为： +```bash +iotdbctl cluster [params (Optional)] +``` +* key 表示了具体的命令。 + +* cluster name 表示集群名称(即`iotdbctl/config` 文件中yaml文件名字)。 + +* params 表示了命令的所需参数(选填)。 + +* 例如部署default_cluster集群的命令格式为： + +```bash +iotdbctl cluster deploy default_cluster +``` + +* 集群的功能及参数列表如下： + +| 命令 | 功能 | 参数 | +|-----------------|-------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| check | 检测集群是否可以部署 | 集群名称列表 | +| clean | 清理集群 | 集群名称 | +| deploy/dist-all | 部署集群 | 集群名称 ,-N,模块名称(iotdb、grafana、prometheus可选),-op force(可选) | +| list | 打印集群及状态列表 | 无 | +| start | 启动集群 | 集群名称,-N,节点名称(nodename、grafana、prometheus可选) | +| stop | 关闭集群 | 集群名称,-N,节点名称(nodename、grafana、prometheus可选) ,-op force(nodename、grafana、prometheus可选) | +| restart | 重启集群 | 集群名称,-N,节点名称(nodename、grafana、prometheus可选),-op force(强制停止)/rolling(滚动重启) | +| show | 查看集群信息，details字段表示展示集群信息细节 | 集群名称, details(可选) | +| destroy | 销毁集群 | 集群名称,-N,模块名称(iotdb、grafana、prometheus可选) | +| scaleout | 集群扩容 | 集群名称 | +| scalein | 集群缩容 | 集群名称，-N，集群节点名字或集群节点ip+port | +| reload | 集群热加载 | 集群名称 | +| dist-conf | 集群配置文件分发 | 集群名称 | +| dumplog | 备份指定集群日志 | 集群名称,-N,集群节点名字 -h 备份至目标机器ip -pw 备份至目标机器密码 -p 备份至目标机器端口 -path 备份的目录 -startdate 起始时间 -enddate 结束时间 -loglevel 日志类型 -l 传输速度 | +| dumpdata | 备份指定集群数据 | 集群名称, -h 备份至目标机器ip -pw 备份至目标机器密码 -p 备份至目标机器端口 -path 备份的目录 -startdate 起始时间 -enddate 结束时间 -l 传输速度 | +| dist-lib | lib 包升级 | 集群名字(升级完后请重启) | +| init | 已有集群使用集群部署工具时，初始化集群配置 | 集群名字，初始化集群配置 | +| status | 查看进程状态 | 集群名字 | +| acitvate | 激活集群 | 集群名字 | +| dist-plugin | 上传plugin(udf,trigger,pipe)到集群 | 集群名字,-type 类型 U(udf)/T(trigger)/P(pipe) -file /xxxx/trigger.jar,上传完成后需手动执行创建udf、pipe、trigger命令 | +| upgrade | 滚动升级 | 集群名字 | +| health_check | 健康检查 | 集群名字,-N,节点名称(可选) | +| backup | 停机备份 | 集群名字,-N,节点名称(可选) | +| importschema | 元数据导入 | 集群名字,-N,节点名称(必填) -param 参数 | +| exportschema | 元数据导出 | 集群名字,-N,节点名称(必填) -param 参数 | + + +### 详细命令执行过程 + +下面的命令都是以default_cluster.yaml 为示例执行的，用户可以修改成自己的集群文件来执行 + +#### 检查集群部署环境命令 + +```bash +iotdbctl cluster check default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 验证目标节点是否能够通过 SSH 登录 + +* 验证对应节点上的 JDK 版本是否满足IoTDB jdk1.8及以上版本、服务器是否按照unzip、是否安装lsof 或者netstat + +* 如果看到下面提示`Info:example check successfully!` 证明服务器已经具备安装的要求， + 如果输出`Error:example check fail!` 证明有部分条件没有满足需求可以查看上面的输出的Error日志(例如:`Error:Server (ip:172.20.31.76) iotdb port(10713) is listening`)进行修复， + 如果检查jdk没有满足要求，我们可以自己在yaml 文件中配置一个jdk1.8 及以上版本的进行部署不影响后面使用， + 如果检查lsof、netstat或者unzip 不满足要求需要在服务器上自行安装。 + +#### 部署集群命令 + +```bash +iotdbctl cluster deploy default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 根据`confignode_servers` 和`datanode_servers`中的节点信息上传IoTDB压缩包和jdk压缩包(如果yaml中配置`jdk_tar_dir`和`jdk_deploy_dir`值) + +* 根据yaml文件节点配置信息生成并上传`iotdb-system.properties` + +```bash +iotdbctl cluster deploy default_cluster -op force +``` +注意：该命令会强制执行部署，具体过程会删除已存在的部署目录重新部署 + +*部署单个模块* +```bash +# 部署grafana模块 +iotdbctl cluster deploy default_cluster -N grafana +# 部署prometheus模块 +iotdbctl cluster deploy default_cluster -N prometheus +# 部署iotdb模块 +iotdbctl cluster deploy default_cluster -N iotdb +``` + +#### 启动集群命令 + +```bash +iotdbctl cluster start default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 启动confignode，根据yaml配置文件中`confignode_servers`中的顺序依次启动同时根据进程id检查confignode是否正常，第一个confignode 为seek config + +* 启动datanode，根据yaml配置文件中`datanode_servers`中的顺序依次启动同时根据进程id检查datanode是否正常 + +* 如果根据进程id检查进程存在后，通过cli依次检查集群列表中每个服务是否正常，如果cli链接失败则每隔10s重试一次直到成功最多重试5次 + + +*启动单个节点命令* +```bash +#按照IoTDB 节点名称启动 +iotdbctl cluster start default_cluster -N datanode_1 +#按照IoTDB 集群ip+port启动，其中port对应confignode的cn_internal_port、datanode的rpc_port +iotdbctl cluster start default_cluster -N 192.168.1.5:6667 +#启动grafana +iotdbctl cluster start default_cluster -N grafana +#启动prometheus +iotdbctl cluster start default_cluster -N prometheus +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件 + +* 根据提供的节点名称或者ip:port找到对于节点位置信息,如果启动的节点是`data_node`则ip使用yaml 文件中的`dn_rpc_address`、port 使用的是yaml文件中datanode_servers 中的`dn_rpc_port`。 + 如果启动的节点是`config_node`则ip使用的是yaml文件中confignode_servers 中的`cn_internal_address` 、port 使用的是`cn_internal_port` + +* 启动该节点 + +说明：由于集群部署工具仅是调用了IoTDB集群中的start-confignode.sh和start-datanode.sh 脚本， +在实际输出结果失败时有可能是集群还未正常启动，建议使用status命令进行查看当前集群状态(iotdbctl cluster status xxx) + + +#### 查看IoTDB集群状态命令 + +```bash +iotdbctl cluster show default_cluster +#查看IoTDB集群详细信息 +iotdbctl cluster show default_cluster details +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 依次在datanode通过cli执行`show cluster details` 如果有一个节点执行成功则不会在后续节点继续执行cli直接返回结果 + + +#### 停止集群命令 + + +```bash +iotdbctl cluster stop default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 根据`datanode_servers`中datanode节点信息，按照配置先后顺序依次停止datanode节点 + +* 根据`confignode_servers`中confignode节点信息，按照配置依次停止confignode节点 + +*强制停止集群命令* + +```bash +iotdbctl cluster stop default_cluster -op force +``` +会直接执行kill -9 pid 命令强制停止集群 + +*停止单个节点命令* + +```bash +#按照IoTDB 节点名称停止 +iotdbctl cluster stop default_cluster -N datanode_1 +#按照IoTDB 集群ip+port停止(ip+port是按照datanode中的ip+dn_rpc_port获取唯一节点或confignode中的ip+cn_internal_port获取唯一节点) +iotdbctl cluster stop default_cluster -N 192.168.1.5:6667 +#停止grafana +iotdbctl cluster stop default_cluster -N grafana +#停止prometheus +iotdbctl cluster stop default_cluster -N prometheus +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件 + +* 根据提供的节点名称或者ip:port找到对应节点位置信息，如果停止的节点是`data_node`则ip使用yaml 文件中的`dn_rpc_address`、port 使用的是yaml文件中datanode_servers 中的`dn_rpc_port`。 + 如果停止的节点是`config_node`则ip使用的是yaml文件中confignode_servers 中的`cn_internal_address` 、port 使用的是`cn_internal_port` + +* 停止该节点 + +说明：由于集群部署工具仅是调用了IoTDB集群中的stop-confignode.sh和stop-datanode.sh 脚本，在某些情况下有可能iotdb集群并未停止。 + + +#### 清理集群数据命令 + +```bash +iotdbctl cluster clean default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`配置信息 + +* 根据`confignode_servers`、`datanode_servers`中的信息，检查是否还有服务正在运行， + 如果有任何一个服务正在运行则不会执行清理命令 + +* 删除IoTDB集群中的data目录以及yaml文件中配置的`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`和`ext`目录。 + + + +#### 重启集群命令 + +```bash +iotdbctl cluster restart default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 + +* 执行上述的停止集群命令(stop),然后执行启动集群命令(start) 具体参考上面的start 和stop 命令 + +*强制重启集群命令* + +```bash +iotdbctl cluster restart default_cluster -op force +``` +会直接执行kill -9 pid 命令强制停止集群，然后启动集群 + +*重启单个节点命令* + +```bash +#按照IoTDB 节点名称重启datanode_1 +iotdbctl cluster restart default_cluster -N datanode_1 +#按照IoTDB 节点名称重启confignode_1 +iotdbctl cluster restart default_cluster -N confignode_1 +#重启grafana +iotdbctl cluster restart default_cluster -N grafana +#重启prometheus +iotdbctl cluster restart default_cluster -N prometheus +``` + +#### 集群缩容命令 + +```bash +#按照节点名称缩容 +iotdbctl cluster scalein default_cluster -N nodename +#按照ip+port缩容(ip+port按照datanode中的ip+dn_rpc_port获取唯一节点，confignode中的ip+cn_internal_port获取唯一节点) +iotdbctl cluster scalein default_cluster -N ip:port +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 判断要缩容的confignode节点和datanode是否只剩一个，如果只剩一个则不能执行缩容 + +* 然后根据ip:port或者nodename 获取要缩容的节点信息，执行缩容命令，然后销毁该节点目录，如果缩容的节点是`data_node`则ip使用yaml 文件中的`dn_rpc_address`、port 使用的是yaml文件中datanode_servers 中的`dn_rpc_port`。 + 如果缩容的节点是`config_node`则ip使用的是yaml文件中confignode_servers 中的`cn_internal_address` 、port 使用的是`cn_internal_port` + + +提示：目前一次仅支持一个节点缩容 + +#### 集群扩容命令 + +```bash +iotdbctl cluster scaleout default_cluster +``` +* 修改config/xxx.yaml 文件添加一个datanode 节点或者confignode节点 + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 找到要扩容的节点，执行上传IoTDB压缩包和jdb包(如果yaml中配置`jdk_tar_dir`和`jdk_deploy_dir`值)并解压 + +* 根据yaml文件节点配置信息生成并上传`iotdb-system.properties` + +* 执行启动该节点命令并校验节点是否启动成功 + +提示：目前一次仅支持一个节点扩容 + +#### 销毁集群命令 +```bash +iotdbctl cluster destroy default_cluster +``` + +* cluster-name 找到默认位置的 yaml 文件 + +* 根据`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`中node节点信息，检查是否节点还在运行， + 如果有任何一个节点正在运行则停止销毁命令 + +* 删除IoTDB集群中的`data`以及yaml文件配置的`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`、`ext`、`IoTDB`部署目录、 + grafana部署目录和prometheus部署目录 + +*销毁单个模块* +```bash +# 销毁grafana模块 +iotdbctl cluster destroy default_cluster -N grafana +# 销毁prometheus模块 +iotdbctl cluster destroy default_cluster -N prometheus +# 销毁iotdb模块 +iotdbctl cluster destroy default_cluster -N iotdb +``` + +#### 分发集群配置命令 +```bash +iotdbctl cluster dist-conf default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 + +* 根据yaml文件节点配置信息生成并依次上传`iotdb-system.properties`到指定节点 + +#### 热加载集群配置命令 +```bash +iotdbctl cluster reload default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 根据yaml文件节点配置信息依次在cli中执行`load configuration` + +#### 集群节点日志备份 +```bash +iotdbctl cluster dumplog default_cluster -N datanode_1,confignode_1 -startdate '2023-04-11' -enddate '2023-04-26' -h 192.168.9.48 -p 36000 -u root -pw root -path '/iotdb/logs' -logs '/root/data/db/iotdb/logs' +``` +* 根据 cluster-name 找到默认位置的 yaml 文件 + +* 该命令会根据yaml文件校验datanode_1,confignode_1 是否存在，然后根据配置的起止日期(startdate<=logtime<=enddate)备份指定节点datanode_1,confignode_1 的日志数据到指定服务`192.168.9.48` 端口`36000` 数据备份路径是 `/iotdb/logs` ，IoTDB日志存储路径在`/root/data/db/iotdb/logs`(非必填，如果不填写-logs xxx 默认从IoTDB安装路径/logs下面备份日志) + +| 命令 | 功能 | 是否必填 | +|------------|------------------------------------| ---| +| -h | 存放备份数据机器ip |否| +| -u | 存放备份数据机器用户名 |否| +| -pw | 存放备份数据机器密码 |否| +| -p | 存放备份数据机器端口(默认22) |否| +| -path | 存放备份数据的路径(默认当前路径) |否| +| -loglevel | 日志基本有all、info、error、warn(默认是全部) |否| +| -l | 限速(默认不限速范围0到104857601 单位Kbit/s) |否| +| -N | 配置文件集群名称多个用逗号隔开 |是| +| -startdate | 起始时间(包含默认1970-01-01) |否| +| -enddate | 截止时间(包含) |否| +| -logs | IoTDB 日志存放路径，默认是（{iotdb}/logs） |否| + +#### 集群节点数据备份 +```bash +iotdbctl cluster dumpdata default_cluster -granularity partition -startdate '2023-04-11' -enddate '2023-04-26' -h 192.168.9.48 -p 36000 -u root -pw root -path '/iotdb/datas' +``` +* 该命令会根据yaml文件获取leader 节点，然后根据起止日期(startdate<=logtime<=enddate)备份数据到192.168.9.48 服务上的/iotdb/datas 目录下 + +| 命令 | 功能 | 是否必填 | +| ---|---------------------------------| ---| +|-h| 存放备份数据机器ip |否| +|-u| 存放备份数据机器用户名 |否| +|-pw| 存放备份数据机器密码 |否| +|-p| 存放备份数据机器端口(默认22) |否| +|-path| 存放备份数据的路径(默认当前路径) |否| +|-granularity| 类型partition |是| +|-l| 限速(默认不限速范围0到104857601 单位Kbit/s) |否| +|-startdate| 起始时间(包含) |是| +|-enddate| 截止时间(包含) |是| + +#### 集群lib包上传(升级) +```bash +iotdbctl cluster dist-lib default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 上传lib包 + +注意执行完升级后请重启IoTDB 才能生效 + +#### 集群初始化 +```bash +iotdbctl cluster init default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 +* 初始化集群配置 + +#### 查看集群进程状态 +```bash +iotdbctl cluster status default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 +* 展示集群的存活状态 + +#### 集群授权激活 + +集群激活默认是通过输入激活码激活，也可以通过-op license_path 通过license路径激活 + +* 默认激活方式 +```bash +iotdbctl cluster activate default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`配置信息 +* 读取里面的机器码 +* 等待输入激活码 + +```bash +Machine code: +Kt8NfGP73FbM8g4Vty+V9qU5lgLvwqHEF3KbLN/SGWYCJ61eFRKtqy7RS/jw03lHXt4MwdidrZJ== +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKgGXEGzMms25+u== +Please enter the activation code: +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKg=，lTF1Dur1AElXIi/5jPV9h0XCm8ziPd9/R+tMYLsze1oAPxE87+Nwws= +Activation successful +``` +* 激活单个节点 + +```bash +iotdbctl cluster activate default_cluster -N confignode1 +``` + +* 通过license路径方式激活 + +```bash +iotdbctl cluster activate default_cluster -op license_path +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`配置信息 +* 读取里面的机器码 +* 等待输入激活码 + +```bash +Machine code: +Kt8NfGP73FbM8g4Vty+V9qU5lgLvwqHEF3KbLN/SGWYCJ61eFRKtqy7RS/jw03lHXt4MwdidrZJ== +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKgGXEGzMms25+u== +Please enter the activation code: +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKg=，lTF1Dur1AElXIi/5jPV9h0XCm8ziPd9/R+tMYLsze1oAPxE87+Nwws= +Activation successful +``` +* 激活单个节点 + +```bash +iotdbctl cluster activate default_cluster -N confignode1 -op license_path +``` + +* 通过license路径方式激活 + +```bash +iotdbctl cluster activate default_cluster -op license_path +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`配置信息 +* 读取里面的机器码 +* 等待输入激活码 + +### 集群plugin分发 +```bash +#分发udf +iotdbctl cluster dist-plugin default_cluster -type U -file /xxxx/udf.jar +#分发trigger +iotdbctl cluster dist-plugin default_cluster -type T -file /xxxx/trigger.jar +#分发pipe +iotdbctl cluster dist-plugin default_cluster -type P -file /xxxx/pipe.jar +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取 `datanode_servers`配置信息 + +* 上传udf/trigger/pipe jar包 + +上传完成后需要手动执行创建udf/trigger/pipe命令 + +### 集群滚动升级 +```bash +iotdbctl cluster upgrade default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 上传lib包 +* confignode 执行停止、替换lib包、启动，然后datanode执行停止、替换lib包、启动 + + + +### 集群健康检查 +```bash +iotdbctl cluster health_check default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 +* 每个节点执行health_check.sh + +* 单个节点健康检查 +```bash +iotdbctl cluster health_check default_cluster -N datanode_1 +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行health_check.sh + + +### 集群停机备份 +```bash +iotdbctl cluster backup default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 +* 每个节点执行backup.sh + +* 单个节点健康检查 +```bash +iotdbctl cluster backup default_cluster -N datanode_1 +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行backup.sh + +说明：多个节点部署到单台机器，只支持 quick 模式 + +### 集群元数据导入 + +```bash +iotdbctl cluster importschema default_cluster -N datanode1 -param "-s ./dump0.csv -fd ./failed/ -lpf 10000" +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行元数据导入import-schema.sh + +其中 -param的参数如下: + +| 命令 | 功能 | 是否必填 | +|-----|---------------------------------|------| +| -s |指定想要导入的数据文件，这里可以指定文件或者文件夹。如果指定的是文件夹，将会把文件夹中所有的后缀为csv的文件进行批量导入。 | 是 | +| -fd |指定一个目录来存放导入失败的文件，如果没有指定这个参数，失败的文件将会被保存到源数据的目录中，文件名为是源文件名加上.failed的后缀。 | 否 | +| -lpf |用于指定每个导入失败文件写入数据的行数，默认值为10000 | 否 | + + + +### 集群元数据导出 + +```bash +iotdbctl cluster exportschema default_cluster -N datanode1 -param "-t ./ -pf ./pattern.txt -lpf 10 -t 10000" +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行元数据导入export-schema.sh + +其中 -param的参数如下: + +| 命令 | 功能 | 是否必填 | +|-----|------------------------------------------------------------|------| +| -t | 为导出的CSV文件指定输出路径 | 是 | +| -path |指定导出元数据的path pattern,指定该参数后会忽略-s参数例如：root.stock.** | 否 | +| -pf |如果未指定-path，则需指定该参数，指定查询元数据路径所在文件路径，支持 txt 文件格式，每个待导出的路径为一行。 | 否 | +| -lpf |指定导出的dump文件最大行数，默认值为10000。 | 否 | +| -timeout |指定session查询时的超时时间，单位为ms | 否 | + + + +### 集群部署工具样例介绍 +在集群部署工具安装目录中config/example 下面有3个yaml样例，如果需要可以复制到config 中进行修改即可 + +| 名称 | 说明 | +|-----------------------------|------------------------------------------------| +| default_1c1d.yaml | 1个confignode和1个datanode 配置样例 | +| default_3c3d.yaml | 3个confignode和3个datanode 配置样例 | +| default_3c3d_grafa_prome | 3个confignode和3个datanode、Grafana、Prometheus配置样例 | + +## 数据文件夹概览工具 + +IoTDB数据文件夹概览工具用于打印出数据文件夹的结构概览信息，工具位置为 tools/tsfile/print-iotdb-data-dir。 + +### 用法 + +- Windows: + +```bash +.\print-iotdb-data-dir.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-iotdb-data-dir.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"IoTDB_data_dir_overview.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-iotdb-data-dir.bat D:\github\master\iotdb\data\datanode\data +```````````````````````` +Starting Printing the IoTDB Data Directory Overview +```````````````````````` +output save path:IoTDB_data_dir_overview.txt +data dir num:1 +143 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +|============================================================== +|D:\github\master\iotdb\data\datanode\data +|--sequence +| |--root.redirect0 +| | |--1 +| | | |--0 +| |--root.redirect1 +| | |--2 +| | | |--0 +| |--root.redirect2 +| | |--3 +| | | |--0 +| |--root.redirect3 +| | |--4 +| | | |--0 +| |--root.redirect4 +| | |--5 +| | | |--0 +| |--root.redirect5 +| | |--6 +| | | |--0 +| |--root.sg1 +| | |--0 +| | | |--0 +| | | |--2760 +|--unsequence +|============================================================== +````````````````````````` + +## TsFile概览工具 + +TsFile概览工具用于以概要模式打印出一个TsFile的内容，工具位置为 tools/tsfile/print-tsfile。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-sketch.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-tsfile-sketch.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"TsFile_sketch_view.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile.bat D:\github\master\1669359533965-1-0-0.tsfile D:\github\master\sketch.txt +```````````````````````` +Starting Printing the TsFile Sketch +```````````````````````` +TsFile path:D:\github\master\1669359533965-1-0-0.tsfile +Sketch save path:D:\github\master\sketch.txt +148 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +-------------------------------- TsFile Sketch -------------------------------- +file path: D:\github\master\1669359533965-1-0-0.tsfile +file length: 2974 + + POSITION| CONTENT + -------- ------- + 0| [magic head] TsFile + 6| [version number] 3 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1, num of Chunks:3 + 7| [Chunk Group Header] + | [marker] 0 + | [deviceID] root.sg1.d1 + 20| [Chunk] of root.sg1.d1.s1, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [chunk header] marker=5, measurementID=s1, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 893| [Chunk] of root.sg1.d1.s2, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [chunk header] marker=5, measurementID=s2, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 1766| [Chunk] of root.sg1.d1.s3, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [chunk header] marker=5, measurementID=s3, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1 ends + 2656| [marker] 2 + 2657| [TimeseriesIndex] of root.sg1.d1.s1, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [ChunkIndex] offset=20 + 2728| [TimeseriesIndex] of root.sg1.d1.s2, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [ChunkIndex] offset=893 + 2799| [TimeseriesIndex] of root.sg1.d1.s3, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [ChunkIndex] offset=1766 + 2870| [IndexOfTimerseriesIndex Node] type=LEAF_MEASUREMENT + | + | +||||||||||||||||||||| [TsFileMetadata] begins + 2891| [IndexOfTimerseriesIndex Node] type=LEAF_DEVICE + | + | + | [meta offset] 2656 + | [bloom filter] bit vector byte array length=31, filterSize=256, hashFunctionSize=5 +||||||||||||||||||||| [TsFileMetadata] ends + 2964| [TsFileMetadataSize] 73 + 2968| [magic tail] TsFile + 2974| END of TsFile +---------------------------- IndexOfTimerseriesIndex Tree ----------------------------- + [MetadataIndex:LEAF_DEVICE] + └──────[root.sg1.d1,2870] + [MetadataIndex:LEAF_MEASUREMENT] + └──────[s1,2657] +---------------------------------- TsFile Sketch End ---------------------------------- +````````````````````````` + +解释： + +- 以"|"为分隔，左边是在TsFile文件中的实际位置，右边是梗概内容。 +- "|||||||||||||||||||||"是为增强可读性而添加的导引信息，不是TsFile中实际存储的数据。 +- 最后打印的"IndexOfTimerseriesIndex Tree"是对TsFile文件末尾的元数据索引树的重新整理打印，便于直观理解，不是TsFile中存储的实际数据。 + +## TsFile Resource概览工具 + +TsFile resource概览工具用于打印出TsFile resource文件的内容，工具位置为 tools/tsfile/print-tsfile-resource-files。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-resource-files.bat +``` + +- Linux or MacOs: + +``` +./print-tsfile-resource-files.sh +``` + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +147 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +230 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +231 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +233 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +237 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file folder D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 finished. +````````````````````````` + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +178 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +186 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +187 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +188 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +192 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource finished. +````````````````````````` diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool.md b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool.md new file mode 100644 index 000000000..1a2986f69 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool.md @@ -0,0 +1,23 @@ +--- +redirectTo: Monitor-Tool_apache.html +--- + diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md new file mode 100644 index 000000000..c2cdc0510 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md @@ -0,0 +1,170 @@ + + + +# Prometheus + +监控工具的部署可参考文档 [监控面板部署](../Deployment-and-Maintenance/Monitoring-panel-deployment.md) 章节。 + +## 监控指标的 Prometheus 映射关系 + +> 对于 Metric Name 为 name, Tags 为 K1=V1, ..., Kn=Vn 的监控指标有如下映射，其中 value 为具体值 + +| 监控指标类型 | 映射关系 | +| ---------------- |--------------------------------| +| Counter | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| AutoGauge、Gauge | name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| Histogram | name_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | +| Rate | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m1"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m5"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m15"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="mean"} value | +| Timer | name_seconds_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | + +## 修改配置文件 + +1) 以 DataNode 为例，修改 iotdb-system.properties 配置文件如下： + +```properties +dn_metric_reporter_list=PROMETHEUS +dn_metric_level=CORE +dn_metric_prometheus_reporter_port=9091 +``` + +2) 启动 IoTDB DataNode + +3) 打开浏览器或者用```curl``` 访问 ```http://servier_ip:9091/metrics```, 就能得到如下 metric 数据： + +``` +... +# HELP file_count +# TYPE file_count gauge +file_count{name="wal",} 0.0 +file_count{name="unseq",} 0.0 +file_count{name="seq",} 2.0 +... +``` + +## Prometheus + Grafana + +如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana +可视化监控指标。 + +IoTDB、Prometheus、Grafana三者的关系如下图所示: + +![iotdb_prometheus_grafana](/img/UserGuide/System-Tools/Metrics/iotdb_prometheus_grafana.png) + +1. IoTDB在运行过程中持续收集监控指标数据。 +2. Prometheus以固定的间隔（可配置）从IoTDB的HTTP接口拉取监控指标数据。 +3. Prometheus将拉取到的监控指标数据存储到自己的TSDB中。 +4. Grafana以固定的间隔（可配置）从Prometheus查询监控指标数据并绘图展示。 + +从交互流程可以看出，我们需要做一些额外的工作来部署和配置Prometheus和Grafana。 + +比如，你可以对Prometheus进行如下的配置（部分参数可以自行调整）来从IoTDB获取监控数据 + +```yaml +job_name: pull-metrics +honor_labels: true +honor_timestamps: true +scrape_interval: 15s +scrape_timeout: 10s +metrics_path: /metrics +scheme: http +follow_redirects: true +static_configs: + - targets: + - localhost:9091 +``` + +更多细节可以参考下面的文档： + +[Prometheus安装使用文档](https://prometheus.io/docs/prometheus/latest/getting_started/) + +[Prometheus从HTTP接口拉取metrics数据的配置说明](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) + +[Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) + +[Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) + +## Apache IoTDB Dashboard + +`Apache IoTDB Dashboard`是 IoTDB 企业版的配套产品，支持统一集中式运维管理，可通过一个监控面板监控多个集群。你可以联系商务获取到 Dashboard 的 Json文件。 + + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20default%20cluster.png) + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20cluster2.png) + + +### 集群概览 + +可以监控包括但不限于： +- 集群总CPU核数、总内存空间、总硬盘空间 +- 集群包含多少个ConfigNode与DataNode +- 集群启动时长 +- 集群写入速度 +- 集群各节点当前CPU、内存、磁盘使用率 +- 分节点的信息 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%A6%82%E8%A7%88.png) + +### 数据写入 + +可以监控包括但不限于： +- 写入平均耗时、耗时中位数、99%分位耗时 +- WAL文件数量与尺寸 +- 节点 WAL flush SyncBuffer 耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%86%99%E5%85%A5.png) + +### 数据查询 + +可以监控包括但不限于： +- 节点查询加载时间序列元数据耗时 +- 节点查询读取时间序列耗时 +- 节点查询修改时间序列元数据耗时 +- 节点查询加载Chunk元数据列表耗时 +- 节点查询修改Chunk元数据耗时 +- 节点查询按照Chunk元数据过滤耗时 +- 节点查询构造Chunk Reader耗时的平均值 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%9F%A5%E8%AF%A2.png) + +### 存储引擎 + +可以监控包括但不限于： +- 分类型的文件数量、大小 +- 处于各阶段的TsFile数量、大小 +- 各类任务的数量与耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%AD%98%E5%82%A8%E5%BC%95%E6%93%8E.png) + +### 系统监控 + +可以监控包括但不限于： +- 系统内存、交换内存、进程内存 +- 磁盘空间、文件数、文件尺寸 +- JVM GC时间占比、分类型的GC次数、GC数据量、各年代的堆内存占用 +- 网络传输速率、包发送速率 + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E5%86%85%E5%AD%98%E4%B8%8E%E7%A1%AC%E7%9B%98.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9Fjvm.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E7%BD%91%E7%BB%9C.png) diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_timecho.md b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_timecho.md new file mode 100644 index 000000000..9ee1b5d4b --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_timecho.md @@ -0,0 +1,170 @@ + + + +# 监控工具 + +监控工具的部署可参考文档 [监控面板部署](../Deployment-and-Maintenance/Monitoring-panel-deployment.md) 章节。 + +## 监控指标的 Prometheus 映射关系 + +> 对于 Metric Name 为 name, Tags 为 K1=V1, ..., Kn=Vn 的监控指标有如下映射，其中 value 为具体值 + +| 监控指标类型 | 映射关系 | +| ---------------- | ------------------------------------------------------------ | +| Counter | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| AutoGauge、Gauge | name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| Histogram | name_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | +| Rate | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m1"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m5"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m15"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="mean"} value | +| Timer | name_seconds_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | + +## 修改配置文件 + +1) 以 DataNode 为例，修改 iotdb-system.properties 配置文件如下： + +```properties +dn_metric_reporter_list=PROMETHEUS +dn_metric_level=CORE +dn_metric_prometheus_reporter_port=9091 +``` + +2) 启动 IoTDB DataNode + +3) 打开浏览器或者用```curl``` 访问 ```http://servier_ip:9091/metrics```, 就能得到如下 metric 数据： + +``` +... +# HELP file_count +# TYPE file_count gauge +file_count{name="wal",} 0.0 +file_count{name="unseq",} 0.0 +file_count{name="seq",} 2.0 +... +``` + +## Prometheus + Grafana + +如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana +可视化监控指标。 + +IoTDB、Prometheus、Grafana三者的关系如下图所示: + +![iotdb_prometheus_grafana](/img/UserGuide/System-Tools/Metrics/iotdb_prometheus_grafana.png) + +1. IoTDB在运行过程中持续收集监控指标数据。 +2. Prometheus以固定的间隔（可配置）从IoTDB的HTTP接口拉取监控指标数据。 +3. Prometheus将拉取到的监控指标数据存储到自己的TSDB中。 +4. Grafana以固定的间隔（可配置）从Prometheus查询监控指标数据并绘图展示。 + +从交互流程可以看出，我们需要做一些额外的工作来部署和配置Prometheus和Grafana。 + +比如，你可以对Prometheus进行如下的配置（部分参数可以自行调整）来从IoTDB获取监控数据 + +```yaml +job_name: pull-metrics +honor_labels: true +honor_timestamps: true +scrape_interval: 15s +scrape_timeout: 10s +metrics_path: /metrics +scheme: http +follow_redirects: true +static_configs: + - targets: + - localhost:9091 +``` + +更多细节可以参考下面的文档： + +[Prometheus安装使用文档](https://prometheus.io/docs/prometheus/latest/getting_started/) + +[Prometheus从HTTP接口拉取metrics数据的配置说明](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) + +[Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) + +[Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) + +## Apache IoTDB Dashboard + +我们提供了Apache IoTDB Dashboard，支持统一集中式运维管理，可通过一个监控面板监控多个集群。 + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20default%20cluster.png) + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20cluster2.png) + +你可以在企业版中获取到 Dashboard 的 Json文件。 + +### 集群概览 + +可以监控包括但不限于： +- 集群总CPU核数、总内存空间、总硬盘空间 +- 集群包含多少个ConfigNode与DataNode +- 集群启动时长 +- 集群写入速度 +- 集群各节点当前CPU、内存、磁盘使用率 +- 分节点的信息 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%A6%82%E8%A7%88.png) + +### 数据写入 + +可以监控包括但不限于： +- 写入平均耗时、耗时中位数、99%分位耗时 +- WAL文件数量与尺寸 +- 节点 WAL flush SyncBuffer 耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%86%99%E5%85%A5.png) + +### 数据查询 + +可以监控包括但不限于： +- 节点查询加载时间序列元数据耗时 +- 节点查询读取时间序列耗时 +- 节点查询修改时间序列元数据耗时 +- 节点查询加载Chunk元数据列表耗时 +- 节点查询修改Chunk元数据耗时 +- 节点查询按照Chunk元数据过滤耗时 +- 节点查询构造Chunk Reader耗时的平均值 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%9F%A5%E8%AF%A2.png) + +### 存储引擎 + +可以监控包括但不限于： +- 分类型的文件数量、大小 +- 处于各阶段的TsFile数量、大小 +- 各类任务的数量与耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%AD%98%E5%82%A8%E5%BC%95%E6%93%8E.png) + +### 系统监控 + +可以监控包括但不限于： +- 系统内存、交换内存、进程内存 +- 磁盘空间、文件数、文件尺寸 +- JVM GC时间占比、分类型的GC次数、GC数据量、各年代的堆内存占用 +- 网络传输速率、包发送速率 + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E5%86%85%E5%AD%98%E4%B8%8E%E7%A1%AC%E7%9B%98.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9Fjvm.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E7%BD%91%E7%BB%9C.png) diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Benchmark.md b/src/zh/UserGuide/latest-Table/Tools-System/Benchmark.md new file mode 100644 index 000000000..aa7251fae --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Tools-System/Benchmark.md @@ -0,0 +1,370 @@ + + +# 测试工具 + +## 1 基本概述 + +IoT-benchmark 是基于 Java 和大数据环境开发的时序数据库基准测试工具，由清华大学软件学院研发并开源。它使用方便，支持多种写入以及查询方式，支持存储测试信息和结果以供进一步查询或分析，支持与 Tableau 集成以可视化测试结果。 + +下图1-1囊括了测试基准流程及其他扩展功能。这些流程可以由IoT-benchmark 统一来完成。IoT Benchmark 支持多种工作负载，包括**纯写入、纯查询、写入查询混合**等，支持**软硬件系统监控、测试指标度量**等监控功能，还实现了**初始化数据库自动化、测试数据分析及系统参数优化**等功能。 + +![](/img/bm1.png) + +图1-1 + +借鉴 YCSB 测试工具将工作负载生成、性能指标测量和数据库接口三个组件分离的设计思想，IoT-benchmark 的模块化设计如图1-2所示。与基于 YCSB 的测试工具系统不同的是，IoT-benchmark 增加了系统监控模块，支持测试数据和系统指标监控数据的持久化。此外也增加了一些特别针对时序数据场景的特殊负载测试功能，如支持物联网场景的批量写入和多种乱序数据写入模式。 + +![](/img/bm2.png) + +图1-2 + + +目前 IoT-benchmark 支持如下时间序列数据库、版本和连接方式： + +| 数据库 | 版本 | 连接方式 | +| :-------------- | :-------------- | :------------------------------------------------------- | +| InfluxDB | v1.x v2.0 | SDK | +| TimescaleDB | -- | jdbc | +| OpenTSDB | -- | Http Request | +| QuestDB | v6.0.7 | jdbc | +| TDengine | v2.2.0.2 | jdbc | +| VictoriaMetrics | v1.64.0 | Http Request | +| KairosDB | -- | Http Request | +| IoTDB | v2.0 v1.x v0.13 | jdbc、sessionByTablet、sessionByRecord、sessionByRecords | + +表1-1大数据测试基准对比 + +## 2 安装运行 + +### 前置条件 + +1. Java 8 +2. Maven 3.6+ +3. 对应的合适版本的数据库，如 Apache IoTDB 1.0 + + + +### 获取方式 + +- 获取二进制包：进入[这里](https://github.com/thulab/iot-benchmark/releases) 下载需要的安装包。下载下来为一个压缩文件，选择文件夹解压即可使用。 +- 源代码编译（可用户 Apache IoTDB 2.0 的测试）： + - 第一步（编译 IoTDB Session 最新包）：进入[官网](https://github.com/apache/iotdb/tree/rc/2.0.1)下载 IoTDB 源码，在根目录下运行命令 mvn clean package install -pl session -am -DskipTests 编译 IoTDB Session 的最新包。 + - 第二步（编译 IoTDB Benchmark 测试包）：进入[官网](https://github.com/thulab/iot-benchmark)下载源码，在根目录下运行 mvn clean package install -pl iotdb-2.0 -am -DskipTests 编译测试 Apache IoTDB 2.0版本的测试包，测试包位置与根目录的相对路径为 ./iotdb-2.0/target/iotdb-2.0-0.0.1/iotdb-2.0-0.0.1 + + +### 测试包结构 + +测试包的目录结构如下所示。其中测试配置文件为conf/config.properties，测试启动脚本为benchmark\.sh (Linux & MacOS) 和 benchmark.bat (Windows)，详细文件用途见下表所示。 + +```Shell +-rw-r--r--. 1 root root 2881 1月 10 01:36 benchmark.bat +-rwxr-xr-x. 1 root root 314 1月 10 01:36 benchmark.sh +drwxr-xr-x. 2 root root 24 1月 10 01:36 bin +-rwxr-xr-x. 1 root root 1140 1月 10 01:36 cli-benchmark.sh +drwxr-xr-x. 2 root root 107 1月 10 01:36 conf +drwxr-xr-x. 2 root root 4096 1月 10 01:38 lib +-rw-r--r--. 1 root root 11357 1月 10 01:36 LICENSE +-rwxr-xr-x. 1 root root 939 1月 10 01:36 rep-benchmark.sh +-rw-r--r--. 1 root root 14 1月 10 01:36 routine +``` + +| 名称 | 子文件 | 用途 | +| :--------------- | :---------------- | :------------------------ | +| benchmark.bat | - | Windows环境运行启动脚本 | +| benchmark.sh | - | Linux/Mac环境运行启动脚本 | +| bin | startup.sh | 初始化脚本文件夹 | +| conf | config.properties | 测试场景配置文件 | +| lib | - | 依赖库文件 | +| LICENSE | - | 许可文件 | +| cli-benchmark.sh | - | 一键化启动脚本 | +| routine | | 多项测试配置文件 | +| rep-benchmark.sh | | 多项测试启动脚本 | + +表1-2文件和文件夹列表用途 + +### 执行测试 + +1. 按照测试需求修改配置文件，主要参数介绍见 1.2 节，对应配置文件为conf/config.properties，**比如测试Apache IoTDB 1.0，则需要修改 DB_SWITCH=IoTDB-100-SESSION_BY_TABLET** +2. 启动被测时间序列数据库 +3. 通过运行 +4. 启动IoT-benchmark执行测试。执行中观测被测时间序列数据库和IoT-benchmark状态，执行完毕后查看结果和分析测试过程。 + +### 结果说明 + +测试的所有日志文件被存放于 logs 文件夹下，测试的结果在测试完成后被存放到 data/csvOutput 文件夹下，例如测试后我们得到了如下的结果矩阵： + +![](/img/bm4.png) + +- Result Matrix + - OkOperation：成功的对应操作次数 + - OkPoint：对于写入操作，是成功写入的点数；对于查询操作，是成功查询到的点数。 + - FailOperation：失败的对应操作次数 + - FailPoint：对于写入操作是写入失败的点数 +- Latency(mx) Matrix + - AVG：操作平均耗时 + - MIN：操作最小耗时 + - Pn：操作整体分布的对应分位值，比如P25是下四分位数 + + + +## 主要参数 + + +### IoTDB服务模型 + +参数`IoTDB_DIALECT_MODE`支持tree、table,默认值为tree。 + +- 当被测数据库为IoTDB-2.0及以上版本时需指定sql_dialect, 并且一个IoTDB只能指定一种。 +- sql_dialect等于table时，要满足：device数为table数的整数倍，table数为database数的整数倍 +- sql_dialect等于tree时，要满足：device数量 >= database数量 +- 表模型模式下，调整参数如下： + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :---------------------- | :------- | :------- | :----------------------------------------------------------- | +| IoTDB_TABLE_NAME_PREFIX | 字符串 | table_ | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，表名称前缀 | +| DATA_CLIENT_NUMBER | 整数 | 10 | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，client数为table数的整数倍 | +| SENSOR_NUMBER | 整数 | 10 | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，则控制属性列数量 | +| IoTDB_TABLE_NUMBER | 整数 | 1 | IoTDB 表模型下(IoTDB_DIALECT_MODE=table)，表的数量 | + +### 工作模式 + +工作模式参数“`BENCHMARK_WORK_MODE`”可选项有如下四种模式： + +- 常用测试模式：结合配置`OPERATION_PROPORTION`参数达到“纯写入”、“纯查询”和“读写混合”的测试操作。 +- 生成数据模式：为了生成可以重复使用的数据集，iot-benchmark提供生成数据集的模式，生成数据集到FILE_PATH，以供后续使用正确性写入模式和正确性查询模式使用。 +- 单数据库正确性写入模式：为了验证数据集写入的正确性，您可以使用该模式写入生成数据模式中生成的数据集，目前该模式仅支持IoTDB v1.0 及更新的版本和InfluxDB v1.x。 +- 单数据库正确性查询模式：在运行这个模式之前需要先使用正确性写入模式写入数据到数据库。为了验证数据集写入的正确性，您可以使用该模式查询写入到数据库中的数据集，目前该模式仅支持IoTDB v1.0 和 InfluxDB v1.x。 + +| **模式名称** | **BENCHMARK_WORK_MODE** | **模式内容** | +| :--------------------- | :---------------------- | :------------------------------- | +| 常规测试模式 | testWithDefaultPath | 支持多种读和写操作的混合负载 | +| 生成数据模式 | generateDataMode | 生成Benchmark本身识别的数据 | +| 单数据库正确性写入模式 | verificationWriteMode | 需要配置 FILE_PATH 以及 DATA_SET | +| 单数据库正确性查询模式 | verificationQueryMode | 需要配置 FILE_PATH 以及 DATA_SET | + +### 服务器连接信息 + +工作模式指定后，被测时序数据库的信息会通过如下参数告知IoT-benchmark + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :----------- | :------- | :-------------------------- | :---------------------------------------------- | +| DB_SWITCH | 字符串 | IoTDB-200-SESSION_BY_TABLET | 被测时序数据库类型 | +| HOST | 字符串 | 127.0.0.1 | 被测时序数据库网络地址 | +| PORT | 整数 | 6667 | 被测时序数据库网络端口 | +| USERNAME | 字符串 | root | 被测时序数据库登录用户名 | +| PASSWORD | 字符串 | root | 被测时序数据库登录用户的密码 | +| DB_NAME | 字符串 | test | 被测时序数据库名称 | +| TOKEN | 字符串 | | 被测时序数据库连接认证Token（InfluxDB 2.0使用） | + +### 写入场景 + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :------------------------- | :------- | :------------------------ | :----------------------------------------------------------- | +| CLIENT_NUMBER | 整数 | 100 | 客户端总数 | +| GROUP_NUMBER | 整数 | 20 | 数据库的数量；仅针对IoTDB。 | +| DEVICE_NUMBER | 整数 | 100 | 设备总数 | +| SENSOR_NUMBER | 整数 | 300 | 每个设备的传感器总数； **如果使用 IoTDB 表模型，则控制属性列数量** | +| INSERT_DATATYPE_PROPORTION | 字符串 | 1:1:1:1:1:1 | 设备的数据类型比例，BOOLEAN:INT32:INT64:FLOAT:DOUBLE:TEXT | +| POINT_STEP | 整数 | 1000 | 数据间时间戳间隔，即生成的数据两个时间戳之间的固定长度。 | +| OP_MIN_INTERVAL | 整数 | 0 | 操作最小执行间隔：若操作耗时大于该值则立即执行下一个，否则等待 (OP_MIN_INTERVAL-实际执行时间) ms；如果为0，则参数不生效；如果为-1，则其值和POINT_STEP一致 | +| IS_OUT_OF_ORDER | 布尔 | false | 是否乱序写入 | +| OUT_OF_ORDER_RATIO | 浮点数 | 0.3 | 乱序写入的数据比例 | +| BATCH_SIZE_PER_WRITE | 整数 | 1 | 批写入数据行数（一次写入多少行数据） | +| START_TIME | 时间 | 2022-10-30T00:00:00+08:00 | 写入数据的开始时间戳；以该时间戳为起点开始模拟创建数据时间戳。 | +| LOOP | 整数 | 86400 | 总操作次数：具体每种类型操作会按OPERATION_PROPORTION定义的比例划分 | +| OPERATION_PROPORTION | 字符 | 1:0:0:0:0:0:0:0:0:0:0 | # 各操作的比例,按照顺序为 写入:Q1:Q2:Q3:Q4:Q5:Q6:Q7:Q8:Q9:Q10, 请注意使用英文冒号。比例中的每一项是整数。 | + + +### 查询场景 + +| 参数名称 | 类型 | 示例 | 系统描述 | +| :------------------- | :--- | :-------------------- | :----------------------------------------------------------- | +| QUERY_DEVICE_NUM | 整数 | 2 | 每条查询语句中查询涉及到的设备数量 | +| QUERY_SENSOR_NUM | 整数 | 2 | 每条查询语句中查询涉及到的传感器数量 | +| QUERY_AGGREGATE_FUN | 字符 | count | 在聚集查询中使用的聚集函数，比如count、avg、sum、max_time等 | +| STEP_SIZE | 整数 | 1 | 时间过滤条件的时间起点变化步长，若设为0则每个查询的时间过滤条件是一样的，单位：POINT_STEP | +| QUERY_INTERVAL | 整数 | 250000 | 起止时间的查询中开始时间与结束时间之间的时间间隔，和Group By中的时间间隔 | +| QUERY_LOWER_VALUE | 整数 | -5 | 条件查询子句时的参数，where xxx > QUERY_LOWER_VALUE | +| GROUP_BY_TIME_UNIT | 整数 | 20000 | Group by语句中的组的大小 | +| LOOP | 整数 | 10 | 总操作次数：具体每种类型操作会按OPERATION_PROPORTION定义的比例划分 | +| OPERATION_PROPORTION | 字符 | 0:0:0:0:0:0:0:0:0:0:1 | 写入:Q1:Q2:Q3:Q4:Q5:Q6:Q7:Q8:Q9:Q10 | + + +### 操作比例 + +| 编号 | 查询类型 | IoTDB 示例 SQL | +| :--- | :--------------------------- | :----------------------------------------------------------- | +| Q1 | 精确点查询 | select v1 from root.db.d1 where time = ? | +| Q2 | 时间范围查询 | select v1 from root.db.d1 where time > ? and time < ? | +| Q3 | 带值过滤的时间范围查询 | select v1 from root.db.d1 where time > ? and time < ? and v1 > ? | +| Q4 | 时间范围聚合查询 | select count(v1) from root.db.d1 where and time > ? and time < ? | +| Q5 | 带值过滤的全时间范围聚合查询 | select count(v1) from root.db.d1 where v1 > ? | +| Q6 | 带值过滤的时间范围聚合查询 | select count(v1) from root.db.d1 where v1 > ? and time > ? and time < ? | +| Q7 | 时间分组聚合查询 | select count(v1) from root.db.d1 group by ([?, ?), ?, ?) | +| Q8 | 最新点查询 | select last v1 from root.db.d1 | +| Q9 | 倒序范围查询 | select v1 from root.sg.d1 where time > ? and time < ? order by time desc | +| Q10 | 倒序带值过滤的范围查询 | select v1 from root.sg.d1 where time > ? and time < ? and v1 > ? order by time desc | + +### 测试过程和测试结果持久化 + +IoT-benchmark目前支持通过配置参数将测试过程和测试结果持久化: + +| **参数名称** | **类型** | **示例** | **系统描述** | +| :-------------------- | :------- | :-------- | :----------------------------------------------------------- | +| TEST_DATA_PERSISTENCE | 字符串 | None | 结果持久化选择，支持None，IoTDB，MySQL和CSV | +| RECORD_SPLIT | 布尔 | true | 是否将结果划分后输出到多个记录, IoTDB 暂时不支持 | +| RECORD_SPLIT_MAX_LINE | 整数 | 10000000 | 记录行数的上限（每个数据库表或CSV文件按照总行数为1千万切分存放） | +| TEST_DATA_STORE_IP | 字符串 | 127.0.0.1 | 输出数据库的IP地址 | +| TEST_DATA_STORE_PORT | 整数 | 6667 | 输出数据库的端口号 | +| TEST_DATA_STORE_DB | 字符串 | result | 输出数据库的名称 | +| TEST_DATA_STORE_USER | 字符串 | root | 输出数据库的用户名 | +| TEST_DATA_STORE_PW | 字符串 | root | 输出数据库的用户密码 | + +- 如果我们设置“`TEST_DATA_PERSISTENCE=CSV`”，测试执行时和执行完毕后我们可以在IoT-benchmark根目录下看到新生成的`data`文件夹，其下包含`csv`文件夹记录测试过程；`csvOutput`文件夹记录测试结果。 +- 如果我们设置“`TEST_DATA_PERSISTENCE=MySQL`”，它会在测试开始前在指定的MySQL数据库中创建命名如“testWithDefaultPath_被测数据库名称_备注_测试启动时间”的数据表记录测试过程；会在名为“CONFIG”的数据表（如果不存在则创建该表），写入本次测试的配置信息；当测试完成时会在名为“FINAL_RESULT”的数据表（如果不存在则创建该表）中写入本次测试结果。 + +### 自动化脚本 + +#### 一键化启动脚本 + +您可以通过`cli-benchmark.sh`脚本一键化启动IoTDB、监控的IoTDB Benchmark和测试的IoTDB Benchmark，但需要注意该脚本启动时会清理IoTDB中的**所有数据**，请谨慎使用。 + +首先，您需要修改`cli-benchmark.sh`中的`IOTDB_HOME`参数为您本地的IoTDB所在的文件夹。 + +然后您可以使用脚本启动测试 + +```Bash +> ./cli-benchmark.sh +``` + +测试完成后您可以在`logs`文件夹中查看测试相关日志，在`server-logs`文件夹中查看监控相关日志。 + +#### 自动执行多项测试 + +通常，除非与其他测试结果进行比较，否则单个测试是没有意义的。因此，我们提供了一个接口来通过一次启动执行多个测试。 + +- 配置 routine + +这个文件的每一行应该是每个测试过程会改变的参数（否则就变成复制测试）。例如，"例程"文件是： + +```Plain +LOOP=10 DEVICE_NUMBER=100 TEST +LOOP=20 DEVICE_NUMBER=50 TEST +LOOP=50 DEVICE_NUMBER=20 TEST +``` + +然后依次执行3个LOOP参数分别为10、20、50的测试过程。 + +> 注意： +> +> 您可以使用“LOOP=20 DEVICE_NUMBER=10 TEST”等格式更改每个测试中的多个参数，不允许使用不必要的空间。 关键字"TEST"意味着新的测试开始。如果您更改不同的参数，更改后的参数将保留在下一次测试中。 + +- 开始测试 + +配置文件routine后，您可以通过启动脚本启动多测试任务： + +```Bash +> ./rep-benchmark.sh +``` + +然后测试信息将显示在终端中。 + +> 注意： +> +> 如果您关闭终端或失去与客户端机器的连接，测试过程将终止。 如果输出传输到终端，则与任何其他情况相同。 + +使用此接口通常需要很长时间，您可能希望将测试过程作为守护程序执行。这样，您可以通过启动脚本将测试任务作为守护程序启动： + +```Bash +> ./rep-benchmark.sh > /dev/null 2>&1 & +``` + +在这种情况下，如果您想知道发生了什么，可以通过以下命令查看日志信息： + +```Bash +> cd ./logs +> tail -f log_info.log +``` + +## 测试示例 + +以IoTDB 2.0为例，使用IoT-Benchemark测试表模型写入及查询，修改IoT-Benchemark配置文件如下： + +```Properties +----------------------Main Configurations---------------------- +BENCHMARK_WORK_MODE=testWithDefaultPath +IoTDB_DIALECT_MODE=TABLE +DB_SWITCH=IoTDB-200-SESSION_BY_TABLET +GROUP_NUMBER=1 +IoTDB_TABLE_NUMBER=1 +DEVICE_NUMBER=60 +REAL_INSERT_RATE=1.0 +SENSOR_NUMBER=10 +OPERATION_PROPORTION=1:0:0:0:0:0:0:0:0:0:0:0 +SCHEMA_CLIENT_NUMBER=10 +DATA_CLIENT_NUMBER=10 +LOOP=10 +BATCH_SIZE_PER_WRITE=10 +DEVICE_NUM_PER_WRITE=1 +START_TIME=2025-01-01T00:00:00+08:00 +POINT_STEP=1000 +INSERT_DATATYPE_PROPORTION=1:1:1:1:1:1:0:0:0:0 +VECTOR=true +``` + +在被测数据库正常运行下，启动IoT-Benchmark服务，等待执行结束后，可查看打印结果如下： + +```Shell +Create schema cost 0.88 second +Test elapsed time (not include schema creation): 4.60 second +----------------------------------------------------------Result Matrix---------------------------------------------------------- +Operation okOperation okPoint failOperation failPoint throughput(point/s) +INGESTION 600 60000 0 0 13054.42 +PRECISE_POINT 0 0 0 0 0.00 +TIME_RANGE 0 0 0 0 0.00 +VALUE_RANGE 0 0 0 0 0.00 +AGG_RANGE 0 0 0 0 0.00 +AGG_VALUE 0 0 0 0 0.00 +AGG_RANGE_VALUE 0 0 0 0 0.00 +GROUP_BY 0 0 0 0 0.00 +LATEST_POINT 0 0 0 0 0.00 +RANGE_QUERY_DESC 0 0 0 0 0.00 +VALUE_RANGE_QUERY_DESC 0 0 0 0 0.00 +GROUP_BY_DESC 0 0 0 0 0.00 +--------------------------------------------------------------------------------------------------------------------------------- + +--------------------------------------------------------------------------Latency (ms) Matrix-------------------------------------------------------------------------- +Operation AVG MIN P10 P25 MEDIAN P75 P90 P95 P99 P999 MAX SLOWEST_THREAD +INGESTION 41.77 0.95 1.41 2.27 6.76 24.14 63.42 127.18 1260.92 1265.72 1265.49 2581.91 +PRECISE_POINT 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +TIME_RANGE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +VALUE_RANGE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +AGG_RANGE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +AGG_VALUE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +AGG_RANGE_VALUE 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +GROUP_BY 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +LATEST_POINT 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +RANGE_QUERY_DESC 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +VALUE_RANGE_QUERY_DESC 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +GROUP_BY_DESC 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 +----------------------------------------------------------------------------------------------------------------------------------------------------------------------- +``` \ No newline at end of file diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Maintenance-Tool_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/Maintenance-Tool_apache.md new file mode 100644 index 000000000..57b527ccb --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Tools-System/Maintenance-Tool_apache.md @@ -0,0 +1,229 @@ + + +# 集群管理工具 + +## 数据文件夹概览工具 + +IoTDB数据文件夹概览工具用于打印出数据文件夹的结构概览信息，工具位置为 tools/tsfile/print-iotdb-data-dir。 + +### 用法 + +- Windows: + +```bash +.\print-iotdb-data-dir.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-iotdb-data-dir.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"IoTDB_data_dir_overview.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-iotdb-data-dir.bat D:\github\master\iotdb\data\datanode\data +```````````````````````` +Starting Printing the IoTDB Data Directory Overview +```````````````````````` +output save path:IoTDB_data_dir_overview.txt +data dir num:1 +143 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +|============================================================== +|D:\github\master\iotdb\data\datanode\data +|--sequence +| |--root.redirect0 +| | |--1 +| | | |--0 +| |--root.redirect1 +| | |--2 +| | | |--0 +| |--root.redirect2 +| | |--3 +| | | |--0 +| |--root.redirect3 +| | |--4 +| | | |--0 +| |--root.redirect4 +| | |--5 +| | | |--0 +| |--root.redirect5 +| | |--6 +| | | |--0 +| |--root.sg1 +| | |--0 +| | | |--0 +| | | |--2760 +|--unsequence +|============================================================== +````````````````````````` + +## TsFile概览工具 + +TsFile概览工具用于以概要模式打印出一个TsFile的内容，工具位置为 tools/tsfile/print-tsfile。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-sketch.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-tsfile-sketch.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"TsFile_sketch_view.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile.bat D:\github\master\1669359533965-1-0-0.tsfile D:\github\master\sketch.txt +```````````````````````` +Starting Printing the TsFile Sketch +```````````````````````` +TsFile path:D:\github\master\1669359533965-1-0-0.tsfile +Sketch save path:D:\github\master\sketch.txt +148 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +-------------------------------- TsFile Sketch -------------------------------- +file path: D:\github\master\1669359533965-1-0-0.tsfile +file length: 2974 + + POSITION| CONTENT + -------- ------- + 0| [magic head] TsFile + 6| [version number] 3 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1, num of Chunks:3 + 7| [Chunk Group Header] + | [marker] 0 + | [deviceID] root.sg1.d1 + 20| [Chunk] of root.sg1.d1.s1, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [chunk header] marker=5, measurementID=s1, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 893| [Chunk] of root.sg1.d1.s2, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [chunk header] marker=5, measurementID=s2, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 1766| [Chunk] of root.sg1.d1.s3, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [chunk header] marker=5, measurementID=s3, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1 ends + 2656| [marker] 2 + 2657| [TimeseriesIndex] of root.sg1.d1.s1, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [ChunkIndex] offset=20 + 2728| [TimeseriesIndex] of root.sg1.d1.s2, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [ChunkIndex] offset=893 + 2799| [TimeseriesIndex] of root.sg1.d1.s3, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [ChunkIndex] offset=1766 + 2870| [IndexOfTimerseriesIndex Node] type=LEAF_MEASUREMENT + | + | +||||||||||||||||||||| [TsFileMetadata] begins + 2891| [IndexOfTimerseriesIndex Node] type=LEAF_DEVICE + | + | + | [meta offset] 2656 + | [bloom filter] bit vector byte array length=31, filterSize=256, hashFunctionSize=5 +||||||||||||||||||||| [TsFileMetadata] ends + 2964| [TsFileMetadataSize] 73 + 2968| [magic tail] TsFile + 2974| END of TsFile +---------------------------- IndexOfTimerseriesIndex Tree ----------------------------- + [MetadataIndex:LEAF_DEVICE] + └──────[root.sg1.d1,2870] + [MetadataIndex:LEAF_MEASUREMENT] + └──────[s1,2657] +---------------------------------- TsFile Sketch End ---------------------------------- +````````````````````````` + +解释： + +- 以"|"为分隔，左边是在TsFile文件中的实际位置，右边是梗概内容。 +- "|||||||||||||||||||||"是为增强可读性而添加的导引信息，不是TsFile中实际存储的数据。 +- 最后打印的"IndexOfTimerseriesIndex Tree"是对TsFile文件末尾的元数据索引树的重新整理打印，便于直观理解，不是TsFile中存储的实际数据。 + +## TsFile Resource概览工具 + +TsFile resource概览工具用于打印出TsFile resource文件的内容，工具位置为 tools/tsfile/print-tsfile-resource-files。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-resource-files.bat +``` + +- Linux or MacOs: + +``` +./print-tsfile-resource-files.sh +``` + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +147 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +230 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +231 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +233 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +237 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file folder D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 finished. +````````````````````````` + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +178 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +186 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +187 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +188 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +192 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource finished. +````````````````````````` diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Maintenance-Tool_timecho.md b/src/zh/UserGuide/latest-Table/Tools-System/Maintenance-Tool_timecho.md new file mode 100644 index 000000000..1c206edc5 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Tools-System/Maintenance-Tool_timecho.md @@ -0,0 +1,1013 @@ + + +# 集群管理工具 + +## 集群管理工具 + +IoTDB 集群管理工具是一款易用的运维工具（企业版工具）。旨在解决 IoTDB 分布式系统多节点的运维难题，主要包括集群部署、集群启停、弹性扩容、配置更新、数据导出等功能，从而实现对复杂数据库集群的一键式指令下发，极大降低管理难度。本文档将说明如何用集群管理工具远程部署、配置、启动和停止 IoTDB 集群实例。 + +### 环境准备 + +本工具为 TimechoDB（基于IoTDB的企业版数据库）配套工具，您可以联系您的销售获取工具下载方式。 + +IoTDB 要部署的机器需要依赖jdk 8及以上版本、lsof、netstat、unzip功能如果没有请自行安装，可以参考文档最后的一节环境所需安装命令。 + +提示:IoTDB集群管理工具需要使用有root权限的账号 + +### 部署方法 + +#### 下载安装 + +本工具为TimechoDB（基于IoTDB的企业版数据库）配套工具，您可以联系您的销售获取工具下载方式。 + +注意：由于二进制包仅支持GLIBC2.17 及以上版本，因此最低适配Centos7版本 + +* 在iotd目录内输入以下指令后： + +```bash +bash install-iotdbctl.sh +``` + +即可在之后的 shell 内激活 iotdbctl 关键词，如检查部署前所需的环境指令如下所示： + +```bash +iotdbctl cluster check example +``` + +* 也可以不激活iotd直接使用 <iotdbctl absolute path>/sbin/iotdbctl 来执行命令，如检查部署前所需的环境： + +```bash +/sbin/iotdbctl cluster check example +``` + +### 系统结构 + +IoTDB集群管理工具主要由config、logs、doc、sbin目录组成。 + +* `config`存放要部署的集群配置文件如果要使用集群部署工具需要修改里面的yaml文件。 +* `logs` 存放部署工具日志，如果想要查看部署工具执行日志请查看`logs/iotd_yyyy_mm_dd.log`。 +* `sbin` 存放集群部署工具所需的二进制包。 +* `doc` 存放用户手册、开发手册和推荐部署手册。 + + +### 集群配置文件介绍 + +* 在`iotdbctl/config` 目录下有集群配置的yaml文件，yaml文件名字就是集群名字yaml 文件可以有多个，为了方便用户配置yaml文件在iotd/config目录下面提供了`default_cluster.yaml`示例。 +* yaml 文件配置由`global`、`confignode_servers`、`datanode_servers`、`grafana_server`、`prometheus_server`四大部分组成 +* global 是通用配置主要配置机器用户名密码、IoTDB本地安装文件、Jdk配置等。在`iotdbctl/config`目录中提供了一个`default_cluster.yaml`样例数据， + 用户可以复制修改成自己集群名字并参考里面的说明进行配置IoTDB集群，在`default_cluster.yaml`样例中没有注释的均为必填项，已经注释的为非必填项。 + +例如要执行`default_cluster.yaml`检查命令则需要执行命令`iotdbctl cluster check default_cluster`即可， +更多详细命令请参考下面命令列表。 + + + +| 参数 | 说明 | 是否必填 | +|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------| +| iotdb_zip_dir | IoTDB 部署分发目录，如果值为空则从`iotdb_download_url`指定地址下载 | 非必填 | +| iotdb_download_url | IoTDB 下载地址，如果`iotdb_zip_dir` 没有值则从指定地址下载 | 非必填 | +| jdk_tar_dir | jdk 本地目录，可使用该 jdk 路径进行上传部署至目标节点。 | 非必填 | +| jdk_deploy_dir | jdk 远程机器部署目录，会将 jdk 部署到该目录下面，与下面的`jdk_dir_name`参数构成完整的jdk部署目录即 `/` | 非必填 | +| jdk_dir_name | jdk 解压后的目录名称默认是jdk_iotdb | 非必填 | +| iotdb_lib_dir | IoTDB lib 目录或者IoTDB 的lib 压缩包仅支持.zip格式 ，仅用于IoTDB升级，默认处于注释状态，如需升级请打开注释修改路径即可。如果使用zip文件请使用zip 命令压缩iotdb/lib目录例如 zip -r lib.zip apache\-iotdb\-1.2.0/lib/* | 非必填 | +| user | ssh登陆部署机器的用户名 | 必填 | +| password | ssh登录的密码, 如果password未指定使用pkey登陆, 请确保已配置节点之间ssh登录免密钥 | 非必填 | +| pkey | 密钥登陆如果password有值优先使用password否则使用pkey登陆 | 非必填 | +| ssh_port | ssh登录端口 | 必填 | +| iotdb_admin_user | iotdb服务用户名默认root | 非必填 | +| iotdb_admin_password | iotdb服务密码默认root | 非必填 | +| deploy_dir | IoTDB 部署目录，会把 IoTDB 部署到该目录下面与下面的`iotdb_dir_name`参数构成完整的IoTDB 部署目录即 `/` | 必填 | +| iotdb_dir_name | IoTDB 解压后的目录名称默认是iotdb | 非必填 | +| datanode-env.sh | 对应`iotdb/config/datanode-env.sh` ,在`global`与`confignode_servers`同时配置值时优先使用`confignode_servers`中的值 | 非必填 | +| confignode-env.sh | 对应`iotdb/config/confignode-env.sh`,在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值 | 非必填 | +| iotdb-common.properties | 对应`iotdb/config/iotdb-common.properties` | 非必填 | +| cn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`confignode_servers`同时配置值时优先使用`confignode_servers`中的值，对应`iotdb/config/iotdb-system.properties`中的`cn_seed_config_node` | 必填 | +| dn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值，对应`iotdb/config/iotdb-system.properties`中的`dn_seed_config_node` | 必填 | + +其中datanode-env.sh 和confignode-env.sh 可以配置额外参数extra_opts，当该参数配置后会在datanode-env.sh 和confignode-env.sh 后面追加对应的值，可参考default_cluster.yaml，配置示例如下: +datanode-env.sh: +extra_opts: | +IOTDB_JMX_OPTS="$IOTDB_JMX_OPTS -XX:+UseG1GC" +IOTDB_JMX_OPTS="$IOTDB_JMX_OPTS -XX:MaxGCPauseMillis=200" + + +* confignode_servers 是部署IoTDB Confignodes配置，里面可以配置多个Confignode + 默认将第一个启动的ConfigNode节点node1当作Seed-ConfigNode + +| 参数 | 说明 | 是否必填 | +|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------| +| name | Confignode 名称 | 必填 | +| deploy_dir | IoTDB config node 部署目录 | 必填｜ | +| cn_internal_address | 对应iotdb/内部通信地址，对应`iotdb/config/iotdb-system.properties`中的`cn_internal_address` | 必填 | +| cn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`confignode_servers`同时配置值时优先使用`confignode_servers`中的值，对应`iotdb/config/iotdb-confignode.properties`中的`cn_seed_config_node` | 必填 | +| cn_internal_port | 内部通信端口，对应`iotdb/config/iotdb-system.properties`中的`cn_internal_port` | 必填 | +| cn_consensus_port | 对应`iotdb/config/iotdb-system.properties`中的`cn_consensus_port` | 非必填 | +| cn_data_dir | 对应`iotdb/config/iotdb-system.properties`中的`cn_data_dir` | 必填 | +| iotdb-system.properties | 对应`iotdb/config/iotdb-system.properties`在`global`与`confignode_servers`同时配置值优先使用confignode_servers中的值 | 非必填 | + +* datanode_servers 是部署IoTDB Datanodes配置，里面可以配置多个Datanode + +| 参数 | 说明 | 是否必填 | +| -------------------------- | ------------------------------------------------------------ | -------- | +| name | Datanode 名称 | 必填 | +| deploy_dir | IoTDB data node 部署目录，注:该目录不能与下面的IoTDB config node部署目录相同 | 必填 | +| dn_rpc_address | datanode rpc 地址对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_address` | 必填 | +| dn_internal_address | 内部通信地址，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_address` | 必填 | +| dn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值，对应`iotdb/config/iotdb-datanode.properties`中的`dn_seed_config_node`，推荐使用 SeedConfigNode | 必填 | +| dn_rpc_port | datanode rpc端口地址，对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_port` | 必填 | +| dn_internal_port | 内部通信端口，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_port` | 必填 | +| iotdb-system.properties | 对应`iotdb/config/iotdb-system.properties`在`global`与`datanode_servers`同时配置值优先使用`datanode_servers`中的值 | 非必填 | + + +| 参数 | 说明 |是否必填| +|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--- | +| name | Datanode 名称 |必填| +| deploy_dir | IoTDB data node 部署目录 |必填| +| dn_rpc_address | datanode rpc 地址对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_address` |必填| +| dn_internal_address | 内部通信地址，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_address` |必填| +| dn_seed_config_node | 集群配置地址指向存活的ConfigNode,默认指向confignode_x，在`global`与`datanode_servers`同时配置值时优先使用`datanode_servers`中的值，对应`iotdb/config/iotdb-system.properties`中的`dn_seed_config_node` |必填| +| dn_rpc_port | datanode rpc端口地址，对应`iotdb/config/iotdb-system.properties`中的`dn_rpc_port` |必填| +| dn_internal_port | 内部通信端口，对应`iotdb/config/iotdb-system.properties`中的`dn_internal_port` |必填| +| iotdb-system.properties | 对应`iotdb/config/iotdb-common.properties`在`global`与`datanode_servers`同时配置值优先使用`datanode_servers`中的值 |非必填| + +* grafana_server 是部署Grafana 相关配置 + +| 参数 | 说明 | 是否必填 | +|--------------------|------------------|-------------------| +| grafana_dir_name | grafana 解压目录名称 | 非必填默认grafana_iotdb | +| host | grafana 部署的服务器ip | 必填 | +| grafana_port | grafana 部署机器的端口 | 非必填，默认3000 | +| deploy_dir | grafana 部署服务器目录 | 必填 | +| grafana_tar_dir | grafana 压缩包位置 | 必填 | +| dashboards | dashboards 所在的位置 | 非必填,多个用逗号隔开 | + +* prometheus_server 是部署Prometheus 相关配置 + +| 参数 | 说明 | 是否必填 | +|--------------------------------|------------------|-----------------------| +| prometheus_dir_name | prometheus 解压目录名称 | 非必填默认prometheus_iotdb | +| host | prometheus 部署的服务器ip | 必填 | +| prometheus_port | prometheus 部署机器的端口 | 非必填，默认9090 | +| deploy_dir | prometheus 部署服务器目录 | 必填 | +| prometheus_tar_dir | prometheus 压缩包位置 | 必填 | +| storage_tsdb_retention_time | 默认保存数据天数 默认15天 | 非必填 | +| storage_tsdb_retention_size | 指定block可以保存的数据大小默认512M ，注意单位KB, MB, GB, TB, PB, EB | 非必填 | + +如果在config/xxx.yaml的`iotdb-system.properties`和`iotdb-system.properties`中配置了metrics,则会自动把配置放入到promethues无需手动修改 + +注意:如何配置yaml key对应的值包含特殊字符如:等建议整个value使用双引号，对应的文件路径中不要使用包含空格的路径，防止出现识别出现异常问题。 + +### 使用场景 + +#### 清理数据场景 + +* 清理集群数据场景会删除IoTDB集群中的data目录以及yaml文件中配置的`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`和`ext`目录。 +* 首先执行停止集群命令、然后在执行集群清理命令。 +```bash +iotdbctl cluster stop default_cluster +iotdbctl cluster clean default_cluster +``` + +#### 集群销毁场景 + +* 集群销毁场景会删除IoTDB集群中的`data`、`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`、`ext`、`IoTDB`部署目录、 + grafana部署目录和prometheus部署目录。 +* 首先执行停止集群命令、然后在执行集群销毁命令。 + + +```bash +iotdbctl cluster stop default_cluster +iotdbctl cluster destroy default_cluster +``` + +#### 集群升级场景 + +* 集群升级首先需要在config/xxx.yaml中配置`iotdb_lib_dir`为要上传到服务器的jar所在目录路径（例如iotdb/lib）。 +* 如果使用zip文件上传请使用zip 命令压缩iotdb/lib目录例如 zip -r lib.zip apache-iotdb-1.2.0/lib/* +* 执行上传命令、然后执行重启IoTDB集群命令即可完成集群升级 + +```bash +iotdbctl cluster dist-lib default_cluster +iotdbctl cluster restart default_cluster +``` + +#### 集群配置文件的热部署场景 + +* 首先修改在config/xxx.yaml中配置。 +* 执行分发命令、然后执行热部署命令即可完成集群配置的热部署 + +```bash +iotdbctl cluster dist-conf default_cluster +iotdbctl cluster reload default_cluster +``` + +#### 集群扩容场景 + +* 首先修改在config/xxx.yaml中添加一个datanode 或者confignode 节点。 +* 执行集群扩容命令 +```bash +iotdbctl cluster scaleout default_cluster +``` + +#### 集群缩容场景 + +* 首先在config/xxx.yaml中找到要缩容的节点名字或者ip+port（其中confignode port 是cn_internal_port、datanode port 是rpc_port） +* 执行集群缩容命令 +```bash +iotdbctl cluster scalein default_cluster +``` + +#### 已有IoTDB集群，使用集群部署工具场景 + +* 配置服务器的`user`、`passwod`或`pkey`、`ssh_port` +* 修改config/xxx.yaml中IoTDB 部署路径，`deploy_dir`（IoTDB 部署目录）、`iotdb_dir_name`(IoTDB解压目录名称,默认是iotdb) + 例如IoTDB 部署完整路径是`/home/data/apache-iotdb-1.1.1`则需要修改yaml文件`deploy_dir:/home/data/`、`iotdb_dir_name:apache-iotdb-1.1.1` +* 如果服务器不是使用的java_home则修改`jdk_deploy_dir`(jdk 部署目录)、`jdk_dir_name`(jdk解压后的目录名称,默认是jdk_iotdb)，如果使用的是java_home 则不需要修改配置 + 例如jdk部署完整路径是`/home/data/jdk_1.8.2`则需要修改yaml文件`jdk_deploy_dir:/home/data/`、`jdk_dir_name:jdk_1.8.2` +* 配置`cn_seed_config_node`、`dn_seed_config_node` +* 配置`confignode_servers`中`iotdb-system.properties`里面的`cn_internal_address`、`cn_internal_port`、`cn_consensus_port`、`cn_system_dir`、 + `cn_consensus_dir`里面的值不是IoTDB默认的则需要配置否则可不必配置 +* 配置`datanode_servers`中`iotdb-system.properties`里面的`dn_rpc_address`、`dn_internal_address`、`dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`等 +* 执行初始化命令 + +```bash +iotdbctl cluster init default_cluster +``` + +#### 一键部署IoTDB、Grafana和Prometheus 场景 + +* 配置`iotdb-system.properties` 打开metrics接口 +* 配置Grafana 配置，如果`dashboards` 有多个就用逗号隔开，名字不能重复否则会被覆盖。 +* 配置Prometheus配置，IoTDB 集群配置了metrics 则无需手动修改Prometheus 配置会根据哪个节点配置了metrics，自动修改Prometheus 配置。 +* 启动集群 + +```bash +iotdbctl cluster start default_cluster +``` + +更加详细参数请参考上方的 集群配置文件介绍 + + +### 命令格式 + +本工具的基本用法为： +```bash +iotdbctl cluster [params (Optional)] +``` +* key 表示了具体的命令。 + +* cluster name 表示集群名称(即`iotdbctl/config` 文件中yaml文件名字)。 + +* params 表示了命令的所需参数(选填)。 + +* 例如部署default_cluster集群的命令格式为： + +```bash +iotdbctl cluster deploy default_cluster +``` + +* 集群的功能及参数列表如下： + +| 命令 | 功能 | 参数 | +|-----------------|-------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| check | 检测集群是否可以部署 | 集群名称列表 | +| clean | 清理集群 | 集群名称 | +| deploy/dist-all | 部署集群 | 集群名称 ,-N,模块名称(iotdb、grafana、prometheus可选),-op force(可选) | +| list | 打印集群及状态列表 | 无 | +| start | 启动集群 | 集群名称,-N,节点名称(nodename、grafana、prometheus可选) | +| stop | 关闭集群 | 集群名称,-N,节点名称(nodename、grafana、prometheus可选) ,-op force(nodename、grafana、prometheus可选) | +| restart | 重启集群 | 集群名称,-N,节点名称(nodename、grafana、prometheus可选),-op force(强制停止)/rolling(滚动重启) | +| show | 查看集群信息，details字段表示展示集群信息细节 | 集群名称, details(可选) | +| destroy | 销毁集群 | 集群名称,-N,模块名称(iotdb、grafana、prometheus可选) | +| scaleout | 集群扩容 | 集群名称 | +| scalein | 集群缩容 | 集群名称，-N，集群节点名字或集群节点ip+port | +| reload | 集群热加载 | 集群名称 | +| dist-conf | 集群配置文件分发 | 集群名称 | +| dumplog | 备份指定集群日志 | 集群名称,-N,集群节点名字 -h 备份至目标机器ip -pw 备份至目标机器密码 -p 备份至目标机器端口 -path 备份的目录 -startdate 起始时间 -enddate 结束时间 -loglevel 日志类型 -l 传输速度 | +| dumpdata | 备份指定集群数据 | 集群名称, -h 备份至目标机器ip -pw 备份至目标机器密码 -p 备份至目标机器端口 -path 备份的目录 -startdate 起始时间 -enddate 结束时间 -l 传输速度 | +| dist-lib | lib 包升级 | 集群名字(升级完后请重启) | +| init | 已有集群使用集群部署工具时，初始化集群配置 | 集群名字，初始化集群配置 | +| status | 查看进程状态 | 集群名字 | +| acitvate | 激活集群 | 集群名字 | +| dist-plugin | 上传plugin(udf,trigger,pipe)到集群 | 集群名字,-type 类型 U(udf)/T(trigger)/P(pipe) -file /xxxx/trigger.jar,上传完成后需手动执行创建udf、pipe、trigger命令 | +| upgrade | 滚动升级 | 集群名字 | +| health_check | 健康检查 | 集群名字,-N,节点名称(可选) | +| backup | 停机备份 | 集群名字,-N,节点名称(可选) | +| importschema | 元数据导入 | 集群名字,-N,节点名称(必填) -param 参数 | +| exportschema | 元数据导出 | 集群名字,-N,节点名称(必填) -param 参数 | + + +### 详细命令执行过程 + +下面的命令都是以default_cluster.yaml 为示例执行的，用户可以修改成自己的集群文件来执行 + +#### 检查集群部署环境命令 + +```bash +iotdbctl cluster check default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 验证目标节点是否能够通过 SSH 登录 + +* 验证对应节点上的 JDK 版本是否满足IoTDB jdk1.8及以上版本、服务器是否按照unzip、是否安装lsof 或者netstat + +* 如果看到下面提示`Info:example check successfully!` 证明服务器已经具备安装的要求， + 如果输出`Error:example check fail!` 证明有部分条件没有满足需求可以查看上面的输出的Error日志(例如:`Error:Server (ip:172.20.31.76) iotdb port(10713) is listening`)进行修复， + 如果检查jdk没有满足要求，我们可以自己在yaml 文件中配置一个jdk1.8 及以上版本的进行部署不影响后面使用， + 如果检查lsof、netstat或者unzip 不满足要求需要在服务器上自行安装。 + +#### 部署集群命令 + +```bash +iotdbctl cluster deploy default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 根据`confignode_servers` 和`datanode_servers`中的节点信息上传IoTDB压缩包和jdk压缩包(如果yaml中配置`jdk_tar_dir`和`jdk_deploy_dir`值) + +* 根据yaml文件节点配置信息生成并上传`iotdb-system.properties` + +```bash +iotdbctl cluster deploy default_cluster -op force +``` +注意：该命令会强制执行部署，具体过程会删除已存在的部署目录重新部署 + +*部署单个模块* +```bash +# 部署grafana模块 +iotdbctl cluster deploy default_cluster -N grafana +# 部署prometheus模块 +iotdbctl cluster deploy default_cluster -N prometheus +# 部署iotdb模块 +iotdbctl cluster deploy default_cluster -N iotdb +``` + +#### 启动集群命令 + +```bash +iotdbctl cluster start default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 启动confignode，根据yaml配置文件中`confignode_servers`中的顺序依次启动同时根据进程id检查confignode是否正常，第一个confignode 为seek config + +* 启动datanode，根据yaml配置文件中`datanode_servers`中的顺序依次启动同时根据进程id检查datanode是否正常 + +* 如果根据进程id检查进程存在后，通过cli依次检查集群列表中每个服务是否正常，如果cli链接失败则每隔10s重试一次直到成功最多重试5次 + + +*启动单个节点命令* +```bash +#按照IoTDB 节点名称启动 +iotdbctl cluster start default_cluster -N datanode_1 +#按照IoTDB 集群ip+port启动，其中port对应confignode的cn_internal_port、datanode的rpc_port +iotdbctl cluster start default_cluster -N 192.168.1.5:6667 +#启动grafana +iotdbctl cluster start default_cluster -N grafana +#启动prometheus +iotdbctl cluster start default_cluster -N prometheus +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件 + +* 根据提供的节点名称或者ip:port找到对于节点位置信息,如果启动的节点是`data_node`则ip使用yaml 文件中的`dn_rpc_address`、port 使用的是yaml文件中datanode_servers 中的`dn_rpc_port`。 + 如果启动的节点是`config_node`则ip使用的是yaml文件中confignode_servers 中的`cn_internal_address` 、port 使用的是`cn_internal_port` + +* 启动该节点 + +说明：由于集群部署工具仅是调用了IoTDB集群中的start-confignode.sh和start-datanode.sh 脚本， +在实际输出结果失败时有可能是集群还未正常启动，建议使用status命令进行查看当前集群状态(iotdbctl cluster status xxx) + + +#### 查看IoTDB集群状态命令 + +```bash +iotdbctl cluster show default_cluster +#查看IoTDB集群详细信息 +iotdbctl cluster show default_cluster details +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 依次在datanode通过cli执行`show cluster details` 如果有一个节点执行成功则不会在后续节点继续执行cli直接返回结果 + + +#### 停止集群命令 + + +```bash +iotdbctl cluster stop default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 根据`datanode_servers`中datanode节点信息，按照配置先后顺序依次停止datanode节点 + +* 根据`confignode_servers`中confignode节点信息，按照配置依次停止confignode节点 + +*强制停止集群命令* + +```bash +iotdbctl cluster stop default_cluster -op force +``` +会直接执行kill -9 pid 命令强制停止集群 + +*停止单个节点命令* + +```bash +#按照IoTDB 节点名称停止 +iotdbctl cluster stop default_cluster -N datanode_1 +#按照IoTDB 集群ip+port停止(ip+port是按照datanode中的ip+dn_rpc_port获取唯一节点或confignode中的ip+cn_internal_port获取唯一节点) +iotdbctl cluster stop default_cluster -N 192.168.1.5:6667 +#停止grafana +iotdbctl cluster stop default_cluster -N grafana +#停止prometheus +iotdbctl cluster stop default_cluster -N prometheus +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件 + +* 根据提供的节点名称或者ip:port找到对应节点位置信息，如果停止的节点是`data_node`则ip使用yaml 文件中的`dn_rpc_address`、port 使用的是yaml文件中datanode_servers 中的`dn_rpc_port`。 + 如果停止的节点是`config_node`则ip使用的是yaml文件中confignode_servers 中的`cn_internal_address` 、port 使用的是`cn_internal_port` + +* 停止该节点 + +说明：由于集群部署工具仅是调用了IoTDB集群中的stop-confignode.sh和stop-datanode.sh 脚本，在某些情况下有可能iotdb集群并未停止。 + + +#### 清理集群数据命令 + +```bash +iotdbctl cluster clean default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`配置信息 + +* 根据`confignode_servers`、`datanode_servers`中的信息，检查是否还有服务正在运行， + 如果有任何一个服务正在运行则不会执行清理命令 + +* 删除IoTDB集群中的data目录以及yaml文件中配置的`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`和`ext`目录。 + + + +#### 重启集群命令 + +```bash +iotdbctl cluster restart default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 + +* 执行上述的停止集群命令(stop),然后执行启动集群命令(start) 具体参考上面的start 和stop 命令 + +*强制重启集群命令* + +```bash +iotdbctl cluster restart default_cluster -op force +``` +会直接执行kill -9 pid 命令强制停止集群，然后启动集群 + +*重启单个节点命令* + +```bash +#按照IoTDB 节点名称重启datanode_1 +iotdbctl cluster restart default_cluster -N datanode_1 +#按照IoTDB 节点名称重启confignode_1 +iotdbctl cluster restart default_cluster -N confignode_1 +#重启grafana +iotdbctl cluster restart default_cluster -N grafana +#重启prometheus +iotdbctl cluster restart default_cluster -N prometheus +``` + +#### 集群缩容命令 + +```bash +#按照节点名称缩容 +iotdbctl cluster scalein default_cluster -N nodename +#按照ip+port缩容(ip+port按照datanode中的ip+dn_rpc_port获取唯一节点，confignode中的ip+cn_internal_port获取唯一节点) +iotdbctl cluster scalein default_cluster -N ip:port +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 判断要缩容的confignode节点和datanode是否只剩一个，如果只剩一个则不能执行缩容 + +* 然后根据ip:port或者nodename 获取要缩容的节点信息，执行缩容命令，然后销毁该节点目录，如果缩容的节点是`data_node`则ip使用yaml 文件中的`dn_rpc_address`、port 使用的是yaml文件中datanode_servers 中的`dn_rpc_port`。 + 如果缩容的节点是`config_node`则ip使用的是yaml文件中confignode_servers 中的`cn_internal_address` 、port 使用的是`cn_internal_port` + + +提示：目前一次仅支持一个节点缩容 + +#### 集群扩容命令 + +```bash +iotdbctl cluster scaleout default_cluster +``` +* 修改config/xxx.yaml 文件添加一个datanode 节点或者confignode节点 + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 找到要扩容的节点，执行上传IoTDB压缩包和jdb包(如果yaml中配置`jdk_tar_dir`和`jdk_deploy_dir`值)并解压 + +* 根据yaml文件节点配置信息生成并上传`iotdb-system.properties` + +* 执行启动该节点命令并校验节点是否启动成功 + +提示：目前一次仅支持一个节点扩容 + +#### 销毁集群命令 +```bash +iotdbctl cluster destroy default_cluster +``` + +* cluster-name 找到默认位置的 yaml 文件 + +* 根据`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`中node节点信息，检查是否节点还在运行， + 如果有任何一个节点正在运行则停止销毁命令 + +* 删除IoTDB集群中的`data`以及yaml文件配置的`cn_system_dir`、`cn_consensus_dir`、 + `dn_data_dirs`、`dn_consensus_dir`、`dn_system_dir`、`logs`、`ext`、`IoTDB`部署目录、 + grafana部署目录和prometheus部署目录 + +*销毁单个模块* +```bash +# 销毁grafana模块 +iotdbctl cluster destroy default_cluster -N grafana +# 销毁prometheus模块 +iotdbctl cluster destroy default_cluster -N prometheus +# 销毁iotdb模块 +iotdbctl cluster destroy default_cluster -N iotdb +``` + +#### 分发集群配置命令 +```bash +iotdbctl cluster dist-conf default_cluster +``` + +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 + +* 根据yaml文件节点配置信息生成并依次上传`iotdb-system.properties`到指定节点 + +#### 热加载集群配置命令 +```bash +iotdbctl cluster reload default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 根据yaml文件节点配置信息依次在cli中执行`load configuration` + +#### 集群节点日志备份 +```bash +iotdbctl cluster dumplog default_cluster -N datanode_1,confignode_1 -startdate '2023-04-11' -enddate '2023-04-26' -h 192.168.9.48 -p 36000 -u root -pw root -path '/iotdb/logs' -logs '/root/data/db/iotdb/logs' +``` +* 根据 cluster-name 找到默认位置的 yaml 文件 + +* 该命令会根据yaml文件校验datanode_1,confignode_1 是否存在，然后根据配置的起止日期(startdate<=logtime<=enddate)备份指定节点datanode_1,confignode_1 的日志数据到指定服务`192.168.9.48` 端口`36000` 数据备份路径是 `/iotdb/logs` ，IoTDB日志存储路径在`/root/data/db/iotdb/logs`(非必填，如果不填写-logs xxx 默认从IoTDB安装路径/logs下面备份日志) + +| 命令 | 功能 | 是否必填 | +|------------|------------------------------------| ---| +| -h | 存放备份数据机器ip |否| +| -u | 存放备份数据机器用户名 |否| +| -pw | 存放备份数据机器密码 |否| +| -p | 存放备份数据机器端口(默认22) |否| +| -path | 存放备份数据的路径(默认当前路径) |否| +| -loglevel | 日志基本有all、info、error、warn(默认是全部) |否| +| -l | 限速(默认不限速范围0到104857601 单位Kbit/s) |否| +| -N | 配置文件集群名称多个用逗号隔开 |是| +| -startdate | 起始时间(包含默认1970-01-01) |否| +| -enddate | 截止时间(包含) |否| +| -logs | IoTDB 日志存放路径，默认是（{iotdb}/logs） |否| + +#### 集群节点数据备份 +```bash +iotdbctl cluster dumpdata default_cluster -granularity partition -startdate '2023-04-11' -enddate '2023-04-26' -h 192.168.9.48 -p 36000 -u root -pw root -path '/iotdb/datas' +``` +* 该命令会根据yaml文件获取leader 节点，然后根据起止日期(startdate<=logtime<=enddate)备份数据到192.168.9.48 服务上的/iotdb/datas 目录下 + +| 命令 | 功能 | 是否必填 | +| ---|---------------------------------| ---| +|-h| 存放备份数据机器ip |否| +|-u| 存放备份数据机器用户名 |否| +|-pw| 存放备份数据机器密码 |否| +|-p| 存放备份数据机器端口(默认22) |否| +|-path| 存放备份数据的路径(默认当前路径) |否| +|-granularity| 类型partition |是| +|-l| 限速(默认不限速范围0到104857601 单位Kbit/s) |否| +|-startdate| 起始时间(包含) |是| +|-enddate| 截止时间(包含) |是| + +#### 集群lib包上传(升级) +```bash +iotdbctl cluster dist-lib default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 上传lib包 + +注意执行完升级后请重启IoTDB 才能生效 + +#### 集群初始化 +```bash +iotdbctl cluster init default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 +* 初始化集群配置 + +#### 查看集群进程状态 +```bash +iotdbctl cluster status default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`、`datanode_servers`、`grafana`、`prometheus`配置信息 +* 展示集群的存活状态 + +#### 集群授权激活 + +集群激活默认是通过输入激活码激活，也可以通过-op license_path 通过license路径激活 + +* 默认激活方式 +```bash +iotdbctl cluster activate default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`配置信息 +* 读取里面的机器码 +* 等待输入激活码 + +```bash +Machine code: +Kt8NfGP73FbM8g4Vty+V9qU5lgLvwqHEF3KbLN/SGWYCJ61eFRKtqy7RS/jw03lHXt4MwdidrZJ== +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKgGXEGzMms25+u== +Please enter the activation code: +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKg=，lTF1Dur1AElXIi/5jPV9h0XCm8ziPd9/R+tMYLsze1oAPxE87+Nwws= +Activation successful +``` +* 激活单个节点 + +```bash +iotdbctl cluster activate default_cluster -N confignode1 +``` + +* 通过license路径方式激活 + +```bash +iotdbctl cluster activate default_cluster -op license_path +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`配置信息 +* 读取里面的机器码 +* 等待输入激活码 + +```bash +Machine code: +Kt8NfGP73FbM8g4Vty+V9qU5lgLvwqHEF3KbLN/SGWYCJ61eFRKtqy7RS/jw03lHXt4MwdidrZJ== +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKgGXEGzMms25+u== +Please enter the activation code: +JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKg=，lTF1Dur1AElXIi/5jPV9h0XCm8ziPd9/R+tMYLsze1oAPxE87+Nwws= +Activation successful +``` +* 激活单个节点 + +```bash +iotdbctl cluster activate default_cluster -N confignode1 -op license_path +``` + +* 通过license路径方式激活 + +```bash +iotdbctl cluster activate default_cluster -op license_path +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`配置信息 +* 读取里面的机器码 +* 等待输入激活码 + +### 集群plugin分发 +```bash +#分发udf +iotdbctl cluster dist-plugin default_cluster -type U -file /xxxx/udf.jar +#分发trigger +iotdbctl cluster dist-plugin default_cluster -type T -file /xxxx/trigger.jar +#分发pipe +iotdbctl cluster dist-plugin default_cluster -type P -file /xxxx/pipe.jar +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取 `datanode_servers`配置信息 + +* 上传udf/trigger/pipe jar包 + +上传完成后需要手动执行创建udf/trigger/pipe命令 + +### 集群滚动升级 +```bash +iotdbctl cluster upgrade default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 + +* 上传lib包 +* confignode 执行停止、替换lib包、启动，然后datanode执行停止、替换lib包、启动 + + + +### 集群健康检查 +```bash +iotdbctl cluster health_check default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 +* 每个节点执行health_check.sh + +* 单个节点健康检查 +```bash +iotdbctl cluster health_check default_cluster -N datanode_1 +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行health_check.sh + + +### 集群停机备份 +```bash +iotdbctl cluster backup default_cluster +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`confignode_servers`和`datanode_servers`配置信息 +* 每个节点执行backup.sh + +* 单个节点健康检查 +```bash +iotdbctl cluster backup default_cluster -N datanode_1 +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行backup.sh + +说明：多个节点部署到单台机器，只支持 quick 模式 + +### 集群元数据导入 + +```bash +iotdbctl cluster importschema default_cluster -N datanode1 -param "-s ./dump0.csv -fd ./failed/ -lpf 10000" +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行元数据导入import-schema.sh + +其中 -param的参数如下: + +| 命令 | 功能 | 是否必填 | +|-----|---------------------------------|------| +| -s |指定想要导入的数据文件，这里可以指定文件或者文件夹。如果指定的是文件夹，将会把文件夹中所有的后缀为csv的文件进行批量导入。 | 是 | +| -fd |指定一个目录来存放导入失败的文件，如果没有指定这个参数，失败的文件将会被保存到源数据的目录中，文件名为是源文件名加上.failed的后缀。 | 否 | +| -lpf |用于指定每个导入失败文件写入数据的行数，默认值为10000 | 否 | + + + +### 集群元数据导出 + +```bash +iotdbctl cluster exportschema default_cluster -N datanode1 -param "-t ./ -pf ./pattern.txt -lpf 10 -t 10000" +``` +* 根据 cluster-name 找到默认位置的 yaml 文件，获取`datanode_servers`配置信息 +* datanode1 执行元数据导入export-schema.sh + +其中 -param的参数如下: + +| 命令 | 功能 | 是否必填 | +|-----|------------------------------------------------------------|------| +| -t | 为导出的CSV文件指定输出路径 | 是 | +| -path |指定导出元数据的path pattern,指定该参数后会忽略-s参数例如：root.stock.** | 否 | +| -pf |如果未指定-path，则需指定该参数，指定查询元数据路径所在文件路径，支持 txt 文件格式，每个待导出的路径为一行。 | 否 | +| -lpf |指定导出的dump文件最大行数，默认值为10000。 | 否 | +| -timeout |指定session查询时的超时时间，单位为ms | 否 | + + + +### 集群部署工具样例介绍 +在集群部署工具安装目录中config/example 下面有3个yaml样例，如果需要可以复制到config 中进行修改即可 + +| 名称 | 说明 | +|-----------------------------|------------------------------------------------| +| default_1c1d.yaml | 1个confignode和1个datanode 配置样例 | +| default_3c3d.yaml | 3个confignode和3个datanode 配置样例 | +| default_3c3d_grafa_prome | 3个confignode和3个datanode、Grafana、Prometheus配置样例 | + +## 数据文件夹概览工具 + +IoTDB数据文件夹概览工具用于打印出数据文件夹的结构概览信息，工具位置为 tools/tsfile/print-iotdb-data-dir。 + +### 用法 + +- Windows: + +```bash +.\print-iotdb-data-dir.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-iotdb-data-dir.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"IoTDB_data_dir_overview.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-iotdb-data-dir.bat D:\github\master\iotdb\data\datanode\data +```````````````````````` +Starting Printing the IoTDB Data Directory Overview +```````````````````````` +output save path:IoTDB_data_dir_overview.txt +data dir num:1 +143 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +|============================================================== +|D:\github\master\iotdb\data\datanode\data +|--sequence +| |--root.redirect0 +| | |--1 +| | | |--0 +| |--root.redirect1 +| | |--2 +| | | |--0 +| |--root.redirect2 +| | |--3 +| | | |--0 +| |--root.redirect3 +| | |--4 +| | | |--0 +| |--root.redirect4 +| | |--5 +| | | |--0 +| |--root.redirect5 +| | |--6 +| | | |--0 +| |--root.sg1 +| | |--0 +| | | |--0 +| | | |--2760 +|--unsequence +|============================================================== +````````````````````````` + +## TsFile概览工具 + +TsFile概览工具用于以概要模式打印出一个TsFile的内容，工具位置为 tools/tsfile/print-tsfile。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-sketch.bat (<输出结果的存储路径>) +``` + +- Linux or MacOs: + +```shell +./print-tsfile-sketch.sh (<输出结果的存储路径>) +``` + +注意：如果没有设置输出结果的存储路径, 将使用相对路径"TsFile_sketch_view.txt"作为默认值。 + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile.bat D:\github\master\1669359533965-1-0-0.tsfile D:\github\master\sketch.txt +```````````````````````` +Starting Printing the TsFile Sketch +```````````````````````` +TsFile path:D:\github\master\1669359533965-1-0-0.tsfile +Sketch save path:D:\github\master\sketch.txt +148 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +-------------------------------- TsFile Sketch -------------------------------- +file path: D:\github\master\1669359533965-1-0-0.tsfile +file length: 2974 + + POSITION| CONTENT + -------- ------- + 0| [magic head] TsFile + 6| [version number] 3 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1, num of Chunks:3 + 7| [Chunk Group Header] + | [marker] 0 + | [deviceID] root.sg1.d1 + 20| [Chunk] of root.sg1.d1.s1, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [chunk header] marker=5, measurementID=s1, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 893| [Chunk] of root.sg1.d1.s2, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [chunk header] marker=5, measurementID=s2, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 + 1766| [Chunk] of root.sg1.d1.s3, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [chunk header] marker=5, measurementID=s3, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE + | [page] UncompressedSize:862, CompressedSize:860 +||||||||||||||||||||| [Chunk Group] of root.sg1.d1 ends + 2656| [marker] 2 + 2657| [TimeseriesIndex] of root.sg1.d1.s1, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19] + | [ChunkIndex] offset=20 + 2728| [TimeseriesIndex] of root.sg1.d1.s2, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18] + | [ChunkIndex] offset=893 + 2799| [TimeseriesIndex] of root.sg1.d1.s3, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19] + | [ChunkIndex] offset=1766 + 2870| [IndexOfTimerseriesIndex Node] type=LEAF_MEASUREMENT + | + | +||||||||||||||||||||| [TsFileMetadata] begins + 2891| [IndexOfTimerseriesIndex Node] type=LEAF_DEVICE + | + | + | [meta offset] 2656 + | [bloom filter] bit vector byte array length=31, filterSize=256, hashFunctionSize=5 +||||||||||||||||||||| [TsFileMetadata] ends + 2964| [TsFileMetadataSize] 73 + 2968| [magic tail] TsFile + 2974| END of TsFile +---------------------------- IndexOfTimerseriesIndex Tree ----------------------------- + [MetadataIndex:LEAF_DEVICE] + └──────[root.sg1.d1,2870] + [MetadataIndex:LEAF_MEASUREMENT] + └──────[s1,2657] +---------------------------------- TsFile Sketch End ---------------------------------- +````````````````````````` + +解释： + +- 以"|"为分隔，左边是在TsFile文件中的实际位置，右边是梗概内容。 +- "|||||||||||||||||||||"是为增强可读性而添加的导引信息，不是TsFile中实际存储的数据。 +- 最后打印的"IndexOfTimerseriesIndex Tree"是对TsFile文件末尾的元数据索引树的重新整理打印，便于直观理解，不是TsFile中存储的实际数据。 + +## TsFile Resource概览工具 + +TsFile resource概览工具用于打印出TsFile resource文件的内容，工具位置为 tools/tsfile/print-tsfile-resource-files。 + +### 用法 + +- Windows: + +```bash +.\print-tsfile-resource-files.bat +``` + +- Linux or MacOs: + +``` +./print-tsfile-resource-files.sh +``` + +### 示例 + +以Windows系统为例： + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +147 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +230 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +231 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +233 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +237 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file folder D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 finished. +````````````````````````` + +`````````````````````````bash +.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource +```````````````````````` +Starting Printing the TsFileResources +```````````````````````` +178 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +186 [main] WARN o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs. +187 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +188 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration +192 [main] WARN o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources. +Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ... + +Resource plan index range [9223372036854775807, -9223372036854775808] +device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00]) + +Analyzing the resource file D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource finished. +````````````````````````` diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool.md b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool.md new file mode 100644 index 000000000..1a2986f69 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool.md @@ -0,0 +1,23 @@ +--- +redirectTo: Monitor-Tool_apache.html +--- + diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md new file mode 100644 index 000000000..c2cdc0510 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md @@ -0,0 +1,170 @@ + + + +# Prometheus + +监控工具的部署可参考文档 [监控面板部署](../Deployment-and-Maintenance/Monitoring-panel-deployment.md) 章节。 + +## 监控指标的 Prometheus 映射关系 + +> 对于 Metric Name 为 name, Tags 为 K1=V1, ..., Kn=Vn 的监控指标有如下映射，其中 value 为具体值 + +| 监控指标类型 | 映射关系 | +| ---------------- |--------------------------------| +| Counter | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| AutoGauge、Gauge | name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| Histogram | name_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | +| Rate | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m1"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m5"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m15"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="mean"} value | +| Timer | name_seconds_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | + +## 修改配置文件 + +1) 以 DataNode 为例，修改 iotdb-system.properties 配置文件如下： + +```properties +dn_metric_reporter_list=PROMETHEUS +dn_metric_level=CORE +dn_metric_prometheus_reporter_port=9091 +``` + +2) 启动 IoTDB DataNode + +3) 打开浏览器或者用```curl``` 访问 ```http://servier_ip:9091/metrics```, 就能得到如下 metric 数据： + +``` +... +# HELP file_count +# TYPE file_count gauge +file_count{name="wal",} 0.0 +file_count{name="unseq",} 0.0 +file_count{name="seq",} 2.0 +... +``` + +## Prometheus + Grafana + +如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana +可视化监控指标。 + +IoTDB、Prometheus、Grafana三者的关系如下图所示: + +![iotdb_prometheus_grafana](/img/UserGuide/System-Tools/Metrics/iotdb_prometheus_grafana.png) + +1. IoTDB在运行过程中持续收集监控指标数据。 +2. Prometheus以固定的间隔（可配置）从IoTDB的HTTP接口拉取监控指标数据。 +3. Prometheus将拉取到的监控指标数据存储到自己的TSDB中。 +4. Grafana以固定的间隔（可配置）从Prometheus查询监控指标数据并绘图展示。 + +从交互流程可以看出，我们需要做一些额外的工作来部署和配置Prometheus和Grafana。 + +比如，你可以对Prometheus进行如下的配置（部分参数可以自行调整）来从IoTDB获取监控数据 + +```yaml +job_name: pull-metrics +honor_labels: true +honor_timestamps: true +scrape_interval: 15s +scrape_timeout: 10s +metrics_path: /metrics +scheme: http +follow_redirects: true +static_configs: + - targets: + - localhost:9091 +``` + +更多细节可以参考下面的文档： + +[Prometheus安装使用文档](https://prometheus.io/docs/prometheus/latest/getting_started/) + +[Prometheus从HTTP接口拉取metrics数据的配置说明](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) + +[Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) + +[Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) + +## Apache IoTDB Dashboard + +`Apache IoTDB Dashboard`是 IoTDB 企业版的配套产品，支持统一集中式运维管理，可通过一个监控面板监控多个集群。你可以联系商务获取到 Dashboard 的 Json文件。 + + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20default%20cluster.png) + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20cluster2.png) + + +### 集群概览 + +可以监控包括但不限于： +- 集群总CPU核数、总内存空间、总硬盘空间 +- 集群包含多少个ConfigNode与DataNode +- 集群启动时长 +- 集群写入速度 +- 集群各节点当前CPU、内存、磁盘使用率 +- 分节点的信息 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%A6%82%E8%A7%88.png) + +### 数据写入 + +可以监控包括但不限于： +- 写入平均耗时、耗时中位数、99%分位耗时 +- WAL文件数量与尺寸 +- 节点 WAL flush SyncBuffer 耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%86%99%E5%85%A5.png) + +### 数据查询 + +可以监控包括但不限于： +- 节点查询加载时间序列元数据耗时 +- 节点查询读取时间序列耗时 +- 节点查询修改时间序列元数据耗时 +- 节点查询加载Chunk元数据列表耗时 +- 节点查询修改Chunk元数据耗时 +- 节点查询按照Chunk元数据过滤耗时 +- 节点查询构造Chunk Reader耗时的平均值 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%9F%A5%E8%AF%A2.png) + +### 存储引擎 + +可以监控包括但不限于： +- 分类型的文件数量、大小 +- 处于各阶段的TsFile数量、大小 +- 各类任务的数量与耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%AD%98%E5%82%A8%E5%BC%95%E6%93%8E.png) + +### 系统监控 + +可以监控包括但不限于： +- 系统内存、交换内存、进程内存 +- 磁盘空间、文件数、文件尺寸 +- JVM GC时间占比、分类型的GC次数、GC数据量、各年代的堆内存占用 +- 网络传输速率、包发送速率 + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E5%86%85%E5%AD%98%E4%B8%8E%E7%A1%AC%E7%9B%98.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9Fjvm.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E7%BD%91%E7%BB%9C.png) diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_timecho.md b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_timecho.md new file mode 100644 index 000000000..9ee1b5d4b --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_timecho.md @@ -0,0 +1,170 @@ + + + +# 监控工具 + +监控工具的部署可参考文档 [监控面板部署](../Deployment-and-Maintenance/Monitoring-panel-deployment.md) 章节。 + +## 监控指标的 Prometheus 映射关系 + +> 对于 Metric Name 为 name, Tags 为 K1=V1, ..., Kn=Vn 的监控指标有如下映射，其中 value 为具体值 + +| 监控指标类型 | 映射关系 | +| ---------------- | ------------------------------------------------------------ | +| Counter | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| AutoGauge、Gauge | name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value | +| Histogram | name_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value
name{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | +| Rate | name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m1"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m5"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="m15"} value
name_total{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", rate="mean"} value | +| Timer | name_seconds_max{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_sum{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds_count{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn"} value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.5"} value value
name_seconds{cluster="clusterName", nodeType="nodeType", nodeId="nodeId",k1="V1" , ..., Kn="Vn", quantile="0.99"} value | + +## 修改配置文件 + +1) 以 DataNode 为例，修改 iotdb-system.properties 配置文件如下： + +```properties +dn_metric_reporter_list=PROMETHEUS +dn_metric_level=CORE +dn_metric_prometheus_reporter_port=9091 +``` + +2) 启动 IoTDB DataNode + +3) 打开浏览器或者用```curl``` 访问 ```http://servier_ip:9091/metrics```, 就能得到如下 metric 数据： + +``` +... +# HELP file_count +# TYPE file_count gauge +file_count{name="wal",} 0.0 +file_count{name="unseq",} 0.0 +file_count{name="seq",} 2.0 +... +``` + +## Prometheus + Grafana + +如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana +可视化监控指标。 + +IoTDB、Prometheus、Grafana三者的关系如下图所示: + +![iotdb_prometheus_grafana](/img/UserGuide/System-Tools/Metrics/iotdb_prometheus_grafana.png) + +1. IoTDB在运行过程中持续收集监控指标数据。 +2. Prometheus以固定的间隔（可配置）从IoTDB的HTTP接口拉取监控指标数据。 +3. Prometheus将拉取到的监控指标数据存储到自己的TSDB中。 +4. Grafana以固定的间隔（可配置）从Prometheus查询监控指标数据并绘图展示。 + +从交互流程可以看出，我们需要做一些额外的工作来部署和配置Prometheus和Grafana。 + +比如，你可以对Prometheus进行如下的配置（部分参数可以自行调整）来从IoTDB获取监控数据 + +```yaml +job_name: pull-metrics +honor_labels: true +honor_timestamps: true +scrape_interval: 15s +scrape_timeout: 10s +metrics_path: /metrics +scheme: http +follow_redirects: true +static_configs: + - targets: + - localhost:9091 +``` + +更多细节可以参考下面的文档： + +[Prometheus安装使用文档](https://prometheus.io/docs/prometheus/latest/getting_started/) + +[Prometheus从HTTP接口拉取metrics数据的配置说明](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) + +[Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) + +[Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) + +## Apache IoTDB Dashboard + +我们提供了Apache IoTDB Dashboard，支持统一集中式运维管理，可通过一个监控面板监控多个集群。 + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20default%20cluster.png) + +![Apache IoTDB Dashboard](/img/%E7%9B%91%E6%8E%A7%20cluster2.png) + +你可以在企业版中获取到 Dashboard 的 Json文件。 + +### 集群概览 + +可以监控包括但不限于： +- 集群总CPU核数、总内存空间、总硬盘空间 +- 集群包含多少个ConfigNode与DataNode +- 集群启动时长 +- 集群写入速度 +- 集群各节点当前CPU、内存、磁盘使用率 +- 分节点的信息 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%A6%82%E8%A7%88.png) + +### 数据写入 + +可以监控包括但不限于： +- 写入平均耗时、耗时中位数、99%分位耗时 +- WAL文件数量与尺寸 +- 节点 WAL flush SyncBuffer 耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%86%99%E5%85%A5.png) + +### 数据查询 + +可以监控包括但不限于： +- 节点查询加载时间序列元数据耗时 +- 节点查询读取时间序列耗时 +- 节点查询修改时间序列元数据耗时 +- 节点查询加载Chunk元数据列表耗时 +- 节点查询修改Chunk元数据耗时 +- 节点查询按照Chunk元数据过滤耗时 +- 节点查询构造Chunk Reader耗时的平均值 + +![](/img/%E7%9B%91%E6%8E%A7%20%E6%9F%A5%E8%AF%A2.png) + +### 存储引擎 + +可以监控包括但不限于： +- 分类型的文件数量、大小 +- 处于各阶段的TsFile数量、大小 +- 各类任务的数量与耗时 + +![](/img/%E7%9B%91%E6%8E%A7%20%E5%AD%98%E5%82%A8%E5%BC%95%E6%93%8E.png) + +### 系统监控 + +可以监控包括但不限于： +- 系统内存、交换内存、进程内存 +- 磁盘空间、文件数、文件尺寸 +- JVM GC时间占比、分类型的GC次数、GC数据量、各年代的堆内存占用 +- 网络传输速率、包发送速率 + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E5%86%85%E5%AD%98%E4%B8%8E%E7%A1%AC%E7%9B%98.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9Fjvm.png) + +![](/img/%E7%9B%91%E6%8E%A7%20%E7%B3%BB%E7%BB%9F%20%E7%BD%91%E7%BB%9C.png)