# 从源码到报告：IoT-Benchmark 时序数据库压测全流程拆解
**选时序数据库像买车：看参数没用，得上路跑一圈。**
这是某工业互联网团队在选型 TDengine 与 IoTDB 时，用了三周时间得出的结论。他们用的“试车场”不是自研脚本，而是 IoT-Benchmark——**清华大学软件学院开源的时序数据库基准测试工具，目前支持 8 款主流时序引擎、4 种接入协议、20 余项可调参数**。
本文从**部署、配置、执行、结果分析**四个阶段，完整走一遍 IoT-Benchmark 压测流程。所有操作均基于 `iotdb-2.0` 测试分支复现。
## 一、部署：两条路，选源码编译还是二进制包
IoT-Benchmark 的获取方式分两种，对应不同诉求。
**路径 A（推荐）：直接下载二进制包**
访问 GitHub Releases 页，下载 `iot-benchmark-xxx.tar.gz`，解压即用。**无需 Maven、无需编译**，适合只想跑测试的用户。
**路径 B（定制化）：源码编译**
需测试 IoTDB 2.0 特定分支时走此路。
```bash
# 1. 编译 IoTDB Session 包（若需）
git clone https://github.com/apache/iotdb/tree/rc/2.0.5
cd iotdb && mvn clean package install -pl session -am -DskipTests
# 2. 编译 IoT-Benchmark 2.0 测试包
git clone https://github.com/thulab/iot-benchmark
cd iot-benchmark && mvn clean package install -pl iotdb-2.0 -am -DskipTests
```
编译产物位于 `./iotdb-2.0/target/iotdb-2.0-0.0.1/`。**目录结构是固定的**：`conf/` 存配置，`benchmark.sh` 是启动入口，`lib/` 装依赖。
## 二、配置：改三个地方，压测就成型
**核心配置文件是 `conf/config.properties`**。以下三项必须按目标场景修改。
**1. 指定被测数据库**
```properties
DB_SWITCH=IoTDB-200-SESSION_BY_TABLET
HOST=127.0.0.1
PORT=6667
USERNAME=root
PASSWORD=root
```
`DB_SWITCH` 支持 `IoTDB-xxx`、`InfluxDB`、`TimescaleDB`、`TDengine` 等 8 种引擎，连接方式可选 Session、JDBC、HTTP。
**2. 定义写入负载模型**
```properties
CLIENT_NUMBER=10 # 并发客户端数
DEVICE_NUMBER=1000 # 设备总数（关键：基数）
SENSOR_NUMBER=50 # 每设备测点数
BATCH_SIZE_PER_WRITE=100 # 单次写入行数
POINT_STEP=1000 # 时间间隔（毫秒）
```
**设备数与测点数乘积 = 总时间序列数**。测试高基数场景时，需调大 `DEVICE_NUMBER` 并观察内存变化。
**3. 选择工作模式**
```properties
BENCHMARK_WORK_MODE=testWithDefaultPath
OPERATION_PROPORTION=1:0:0:0:0:0:0:0:0:0:0 # 纯写入
```
比例串共 11 项，依次为：**写 : Q1 : Q2 : ... : Q10**。`1:0` 即纯写；`1:1` 为读写混合。
## 三、执行：三条命令，看吞吐与延迟
启动被测数据库后，执行：
```bash
# Linux / macOS
./benchmark.sh
<"j8.p5k3.org.cn">
<"n0.p5k3.org.cn">
<"w4.p5k3.org.cn">
# Windows
benchmark.bat
```
测试过程中终端实时输出：
```
> ----------------------------------------------------------------------------------------------------------------------
> [TEST STATUS] main-thread started. Loops: 86400; Time remaining 169s
> 10 clients, 30000 series, 100 batch size, sequential write
> [avg] Write latency: 23.17 ms, 99%: 45.21 ms, 99.9%: 67.83 ms
> Throughput: 432,109 points/s, 4,321 ops/s
> ----------------------------------------------------------------------------------------------------------------------
```
**关键观察点**：
- **吞吐量（points/s）**：纯写入场景的核心指标。TDengine 在 TSBS 测试中可达 InfluxDB 的 16 倍。
- **延迟分布（P99/P99.9）**：反映稳定性。Kudu 在超负荷下仍能保持低 P99 延迟。
## 四、结果分析：两个文件，定结论
测试结束后，所有数据写入 `data/csvOutput/` 目录，生成带时间戳的 CSV 文件。
**结果表示例**：
| Operation | OkOperation | OkPoint | FailOperation | FailPoint | AVG(ms) | MIN(ms) | P25 | P50 | P75 | P90 | P95 | P99 |
|-----------|------------|---------|---------------|-----------|---------|---------|-----|-----|-----|-----|-----|-----|
| WRITE | 86400 | 8.64e8 | 0 | 0 | 23.17 | 5.21 | 18.2| 21.5| 27.4| 35.1| 40.2| 45.2|
**四步读表法**：
1. **看成功率**：`FailOperation` 为 0 是底线。
2. **看吞吐量**：`OkPoint` / 总时长 ≈ 每秒写入点数。
3. **看平均延迟**：`AVG` 是否在业务容忍范围内。
4. **看长尾**：`P99` 与 `AVG` 差距过大说明存在抖动。
**logs/ 目录** 存全量日志，用于排查失败请求的具体原因。
## 五、两个实战案例：不同数据库，不同结论
**案例 A：某工厂 10 万设备写入测试**
用 IoT-Benchmark 对比 IoTDB 与 InfluxDB。配置：`DEVICE_NUMBER=100000`, `SENSOR_NUMBER=10`, `CLIENT_NUMBER=50`。
结果：IoTDB 吞吐量 220 万点/秒，InfluxDB 78 万点/秒。**结论：高基数场景选 IoTDB**。
**案例 B：时序基准套件（TSBS）跨库比较**
TSBS 是另一套更通用的时序压测框架，TDengine 官方报告显示：**在复杂查询场景，TDengine 响应速度是 TimescaleDB 平均 5.1 倍、InfluxDB 平均 21.2 倍**。
## 六、避坑：三个参数调不对，结果全白费
**坑 1：`LOOP` 与 `BATCH_SIZE_PER_WRITE` 关系**
`LOOP` 是**操作次数**，不是点数。若 `BATCH_SIZE_PER_WRITE=100`，`LOOP=86400` 则总写入行数为 86400×100。**别把行数当点数算**。
**坑 2：`DEVICE_NUMBER` 与 `GROUP_NUMBER`（IoTDB 专用）**
IoTDB 中设备隶属于存储组。若 `GROUP_NUMBER=10`, `DEVICE_NUMBER=1000`，则每组均分设备。**组数过少会导致写入热点**。
**坑 3：`IS_OUT_OF_ORDER` 乱序写入**
默认关闭。若测试乱序场景（如网络抖动），需设为 `true` 并配置 `OUT_OF_ORDER_RATIO`。**乱序比越高，写入吞吐通常越低**。
**IoT-Benchmark 的价值，不是给你一个“冠 军分数”，而是让你在同等负载、同等硬件下，看见不同数据库的真实反应**。吞吐量、延迟、长尾、资源占用——这些数字不会说谎，它们只是等你用正确的工具把它们放出来。