基准测试工具之你不知道的两三事 | 从一次时序数据库写入测试开始
在上一篇文章中，我们了解了数据库基准测试工具是什么，以及它为什么会出现在数据库选型和性能优化的过程中。
但知道“要测”只是第一步。真正打开工具时，很多人马上会遇到新的问题：测试程序该怎样启动？配置文件里那么多参数先看哪个？终端最后打印出一大张表，到底应该关注什么？
这一篇就以 IoT Benchmark 为例，完成一次最小可运行的时序数据库写入测试。这里使用 IoTDB 2.0.10 作为被测系统，通过一个具体场景把基准测试从“概念”落到“操作”。
1. 先跑通，再谈比较
第一次接触基准测试时，很容易把目标定成“测出谁更快”。其实更合理的顺序恰好相反：先稳定地跑出一轮自己能解释、别人能复现的测试，再考虑比较不同配置、不同版本，或不同数据库。
一次可信的测试结果至少由三部分组成：被测环境、工作负载和输出结果。只保留最后一个吞吐量数字，往往没有多少意义。换一台机器、换一块磁盘、改一个并发数，结果都可能不同。
因此，本文的目标很简单：先完成这个闭环。跑通之后，你得到的不是某个“标准答案”，而是一份可以继续调整、重复执行和说明来路的测试基线。
2. 准备工作
根据项目当前说明，运行 IoT Benchmark 需要准备以下环境：
- Java 17。
- Maven。
- IoTDB 2.0.10
本文以 IoTDB 2.0.10 为例。完成编译后，需要先在本机6667端口启动对应的 IoTDB 服务。当前 IoT Benchmark 2.0 的默认配置启用了 IoTDB RPC 压缩，因此目标 IoTDB 建议使用2.0.6或更高版本；若测试更早的 IoTDB 2.0 版本，则需要在配置中关闭该选项：
ENABLE_IOTDB_RPC_COMPRESSION=false这里还有一个小提醒：基准测试会写入数据，也会消耗 CPU、内存和磁盘空间。第一次运行时，建议先在测试环境或本地开发环境进行，不要直接对生产实例执行默认负载。
3. 运行第一次写入测试
环境准备完成后，可以按下面的顺序获取和构建工具：
gitclone https://github.com/thulab/iot-benchmark.gitcdiot-benchmark mvn clean package-Dmaven.test.skip=true构建完成后，进入 IoTDB 2.0 对应的产物目录并启动：
cdiotdb-2.0/target/iot-benchmark-iotdb-2.0/iot-benchmark-iotdb-2.0 ./benchmark.sh默认配置会启动一次写入测试。运行过程中，终端会持续输出各个客户端的完成进度；当看到All dataClients finished一类信息时，说明所有数据客户端已经完成。
这一步看似只是运行了一条命令，但它已经帮我们完成了三件事：根据配置生成周期性时序数据、把数据写入目标数据库、汇总本轮测试的配置和统计结果。后面无论要增加读操作、测试乱序写入，还是比较两套配置，都是在这个最小闭环上继续调整。
4. 配置文件里，先看这三个地方
测试产物目录下的conf文件夹保存配置文件。参数很多，但第一次不需要逐项研究。先看下面三个位置，就能回答“测谁、测多大、测什么”这三个基本问题。
| 要回答的问题 | 重点参数 | 它决定什么 |
|---|---|---|
| 测谁 | DB_SWITCH | 被测数据库及所使用的连接实现，必须与实际启动的数据库版本匹配。 |
| 测多大 | DEVICE_NUMBER、SENSOR_NUMBER、DATA_CLIENT_NUMBER、BATCH_SIZE_PER_WRITE、LOOP | 设备与测点规模、客户端并发、单批写入量，以及总操作量。 |
| 测什么 | BENCHMARK_WORK_MODE、OPERATION_PROPORTION | 运行模式，以及写入和各类查询操作在工作负载中的比例。 |
其中，DB_SWITCH是最先要确认的参数。以 IoTDB 2.0.10 为例，项目 README 列出了 JDBC、REST、Session 等不同连接实现。配置写成了一个数据库不支持的取值，后续再怎么调并发也没有意义。
DATA_CLIENT_NUMBER表示负责读写数据的客户端数量，BATCH_SIZE_PER_WRITE则控制每次写入批次的行数。提高它们可能提升吞吐，也可能让客户端、网络或服务端先达到瓶颈。因此，改动时不要同时把多个参数拉高，最好一次只改一个变量。
最后是工作负载。常规模式使用：
BENCHMARK_WORK_MODE=testWithDefaultPath默认的OPERATION_PROPORTION为写入比例为 1、其他操作比例为 0，也就是一轮纯写入测试。IoT Benchmark 还支持把数据生成到磁盘的generateDataMode，以及基于数据集做正确性写入和正确性查询的verificationWriteMode、verificationQueryMode。这些模式适合后续做数据复用或正确性验证；第一次上手先保持默认模式即可。
5. 测试结束后，应该看什么
测试结束时，终端会输出主配置、总耗时、结果矩阵和延迟矩阵。真正有价值的，不是盯着一个最大的数字，而是把它们放在一起看。
先看主配置。它相当于这份结果的“实验条件”：目标数据库、设备数、测点数、客户端数、批大小、写入或查询比例都在其中。离开这些条件，结果不能被正确解释。
然后看结果矩阵中的几个字段：
| 字段 | 含义 | 第一次测试时怎样看 |
|---|---|---|
okOperation | 成功执行的请求或 SQL 数量 | 确认负载是否按预期完成。 |
okPoint | 成功写入的数据点数，或查询成功返回的数据点数 | 与配置一起检查实际处理的数据规模。 |
failOperation | 执行失败的请求或 SQL 数量 | 不应只看吞吐量而忽略失败。 |
failPoint | 写入失败的数据点数 | 写入测试中应重点关注。 |
throughput | okPoint / Test elapsed time | 用于比较相同环境、相同负载下的处理速率。 |
延迟矩阵则用于观察每次操作花了多长时间。平均值能给出整体印象，但它会掩盖少量慢请求。P99更值得额外关注：它表示 99% 的已记录操作延迟不超过该值，剩下约 1% 的操作更慢。若平均延迟不高、P99 却很高，通常说明尾部请求存在明显抖动，继续调优前应先结合日志检查原因。
请特别注意，项目文档里的示例输出来自特定硬件、磁盘和参数设置；它展示的是报告的格式，不是你的机器应该达到的性能目标。对你而言，最重要的是让每一轮结果都能对应到一份明确的配置和环境记录。
6. 三个容易忽略的测试习惯
第一，固定环境再比较。数据库版本、CPU、内存、磁盘、网络、部署方式不同，都会影响结果。要比较两个数据库或两个版本时，应尽量让这些条件保持一致。
第二，一次只改一个变量。例如先固定数据规模，只调整DATA_CLIENT_NUMBER；或先固定并发，只调整批大小。这样才能知道结果变化到底由什么造成。一次改五个参数，最后通常只能得到一张很热闹、却难以解释的表。
第三，不要只保存截图。IoT Benchmark 会把运行信息记录到运行设备的logs文件夹。除了日志，还应记录服务端版本、硬件与存储情况、完整配置文件和重复运行的结果。它们才是以后复查、复现和讨论差异时真正需要的材料。
7. 小结
现在，我们已经完成了一次最小的 IoT Benchmark 测试流程：准备环境，启动对应版本的 IoTDB，构建并运行工具，确认关键配置，再从吞吐、失败数和尾部延迟三个角度阅读结果。
在开始下一轮测试前，可以用下面这份清单做一次确认：
- 被测数据库版本和
DB_SWITCH是否匹配？ - 本轮的设备数、测点数、客户端数和批大小是否已记录？
- 写入与查询的比例是否符合本轮想回答的问题？
- 是否检查了失败操作和 P99，而不只看吞吐量？
- 是否保留了配置文件、环境信息和
logs中的完整结果？
当这些问题都有答案时，基准测试才真正从“跑了一条命令”变成了可以支撑判断的材料。下一篇文章可以继续讨论更关键的一步：怎样根据自己的业务场景，设计一份更贴近真实负载的测试方案。
系列文章
- 第一篇：数据库基准测试工具是什么