基准测试最令人遗憾的结果不是吞吐量低而是几天后再看那张截图已经说不清它来自哪个版本、哪份配置和哪台机器。性能结果天然依赖上下文。同样的吞吐量可能来自不同设备数、批大小、接口、数据库参数和硬件状态同一个 P99 峰值也可能对应客户端 GC、网络抖动、服务端合并或磁盘写满。没有原始证据复盘只能变成猜测。这一篇讨论怎样把一次 IoT Benchmark 运行保存为“可追溯实验包”让结果不仅能看还能复现、解释和审计。1. 为什么只保存截图远远不够截图通常只能保留某一刻的结果矩阵却会丢失决定结果含义的条件。只留下的内容后来无法回答的问题一张吞吐量截图使用了哪个数据库版本和写入接口一份config.properties服务端配置、硬件和网络环境是否相同一个最终 CSV测试中途是否出现超时、重试或错误日志一组监控曲线曲线的时间窗口对应哪一轮 Benchmark一句“测试通过”正确性验证检查了数量、时间戳还是具体值真正可复盘的结果必须能够重新建立“这一轮究竟发生了什么”的时间线。测试问题运行编号配置与版本原始日志与结果资源与正确性证据异常时间线带边界的结论2. 先给每轮测试一个唯一编号不要使用“最终版”“再跑一次”或“test2”作为运行名称。一个实用的运行编号至少应包含日期、对象、负载和轮次例如20260718-iotdb200-session-write-r03它可以映射为字段示例作用日期20260718便于按时间定位环境变化。被测对象iotdb200-session标明版本族或接口。负载write区分纯写、混合、乱序等场景。轮次r03保留同一配置下的重复运行。如果是多实例集群测试还应为每个客户端增加实例后缀如client-0、client-1并由一个总运行编号把它们关联起来。3. 建立一份可追溯实验包下面是一种建议目录。它不是 IoT Benchmark 自动生成的固定格式而是测试者在工具输出之外建立的归档约定。runs/20260718-iotdb200-session-write-r03/ ├── README.md # 测试问题、结论与异常摘要 ├── manifest.yaml # 运行编号、时间、机器和版本 ├── config/ │ ├── benchmark.properties # 本轮实际使用的完整配置 │ └── database.conf # 与结论相关的服务端配置 ├── output/ │ ├── benchmark.log # 完整客户端日志 │ └── test-result.csv # 最终结果与配置快照 ├── monitor/ │ ├── client/ # 压测机 CPU、网络、GC 等 │ └── server/ # 每个数据库节点的资源记录 ├── correctness/ │ ├── verification.log # 验证日志 │ └── checks.md # 预期量、实际量与抽样结果 └── checksums.txt # 关键数据集和文件校验值这个目录最重要的原则是原始证据与人工结论分开保存。日志和 CSV 不应被手工“修漂亮”异常解释放进README.md必要的清洗或汇总则另存新文件并说明生成方法。4. IoT Benchmark 提供了哪些结果出口在当前配置中至少要区分两类 CSV 能力。4.1CSV_OUTPUT保存最终结果和配置CSV_OUTPUTtrue当前代码会把配置、结果指标和延迟统计写入data/csvOutput/下的测试结果文件。它适合保存一轮结束时的最终汇总也是最轻量的归档方式。4.2TEST_DATA_PERSISTENCE持久化测量结果TEST_DATA_PERSISTENCECSV RECORD_SPLITtrue RECORD_SPLIT_MAX_LINE10000000 REMARKwrite_baseline_r03TEST_DATA_PERSISTENCE支持None、IoTDB、MySQL和CSV。选择 CSV 时工具会通过CSVRecorder保存测量记录选择数据库时则需要配置对应的结果库地址、端口、库名、账号和连接参数。二者不要混为一谈CSV_OUTPUTtrue负责输出最终测试结果 CSVTEST_DATA_PERSISTENCECSV走的是测量结果持久化路径。是否两者都开启取决于你需要“最终摘要”还是“更细的过程记录”。需求建议配置说明只保留最终结果与配置CSV_OUTPUTtrue简单适合小规模手工测试。保存更细的测量记录TEST_DATA_PERSISTENCECSV便于分析不同操作和时间段。多轮集中查询结果TEST_DATA_PERSISTENCEIoTDB或MySQL需要单独维护结果库和标识。只看终端或日志TEST_DATA_PERSISTENCENone仍建议额外归档完整日志和配置。配置中的账号和密码不应原样进入公开实验包。可以保存一份脱敏副本同时在受控位置保留实际运行配置。5. 用REMARK和打印间隔增强可追踪性REMARK会参与结果标识或表名构造适合放入简短、无特殊字符的运行标签REMARKiotdb200_session_write_r03 # 保留必要的进度和中间结果 IS_QUIET_MODEfalse LOG_PRINT_INTERVAL5 RESULT_PRINT_INTERVAL60中间结果不是最终结论但它能帮助建立时间线。例如第 180 秒开始 P99 上升而同一时刻某个节点磁盘写入等待升高就比“整轮平均值变差”更容易定位问题。设置打印间隔时也要控制日志量。过密的日志可能产生额外开销过疏则可能错过短时异常。最稳妥的做法是在正式对比前固定间隔并让所有候选对象使用相同配置。6. 配置、版本和环境要保存到什么粒度仅保存 Benchmark 配置还不够。一轮测试至少应记录下面这些信息类别必须记录推荐补充BenchmarkGit 提交或发布版本、DB_SWITCH、完整配置Java 版本、启动方式、客户端日志级别。数据库产品版本、提交或镜像摘要、关键服务端配置驱动版本、插件版本、后台任务状态。数据数据来源、设备数、测点数、类型、时间范围输入文件校验值、乱序比例与随机种子。硬件CPU、内存、磁盘类型与容量、机器数量NUMA、文件系统、挂载参数。部署单机或集群、节点角色、副本和分片设置容器限制、网络拓扑、访问入口。时间开始与结束时间、时区、预热与正式阶段各机器时钟同步状态。版本最好记录为不可变标识例如 Git commit、容器镜像 digest 或完整构建号而不是只写“最新版”。数据库配置也应保存本轮实际生效值不能只链接一份后来可能被修改的公共配置。7. 资源监控必须与运行时间对齐资源曲线只有和 Benchmark 时间线对齐后才有解释力。多机测试尤其要确认时区和系统时钟一致并保存以下关键时间点数据库启动或重启完成时间预热开始与结束时间正式运行开始与结束时间异常、超时或人工操作时间正确性验证开始与结束时间。监控系统数据库压测客户端监控系统数据库压测客户端开始采集预热负载正式运行开始响应、超时或错误记录中间结果正式运行结束正确性验证结束采集并归档时间窗口如果测试期间发生了清库、重启、扩容或参数修改必须记入时间线。这类操作不能只写在聊天记录里否则之后无法判断曲线变化来自系统还是人工干预。8. 怎样复盘一轮测试复盘不应从“吞吐量是多少”开始而应按证据门禁逐层推进。第一步确认实验身份检查运行编号、候选对象、配置摘要、开始结束时间和结果文件是否互相对应防止拿错轮次。第二步检查完整性与正确性确认进程是否正常结束成功与失败点数是否符合预期验证日志是否存在值或行数差异。正确性未通过时性能结果应标记为无效。第三步观察稳定阶段把预热、正式运行和收尾阶段分开。平均吞吐量不能掩盖正式阶段内部的持续下降、周期抖动或长尾恶化。第四步关联资源和事件将 P99、失败数与客户端 CPU、服务端 CPU、磁盘、网络、GC 和后台任务放在同一时间轴上。相关性可以帮助定位但仍不能直接当作因果结论。第五步与同配置多轮结果比较确认当前结果是否落在稳定范围。若只在某一轮异常应先解释环境和状态差异若多轮都出现相同变化才更接近可重复现象。9. 一份复盘摘要应该怎样写一个合格的README.md不需要很长但应包含以下内容# 运行摘要 - 运行编号待填 - 测试问题待填 - 被测对象与版本待填 - 唯一变量待填 - 正式运行窗口待填 - 正确性门禁通过 / 未通过 / 未执行 ## 主要结果 - 各操作成功点数、失败点数待填 - 吞吐量与 P99 的多轮范围待填 - 客户端与服务端资源峰值待填 ## 异常时间线 - 时间点—现象—相关日志—相关资源待填 ## 结论与边界 - 当前证据支持的结论待填 - 尚不能覆盖的场景待填 - 下一步复测条件待填“未执行”比空白更好因为它明确告诉读者哪一类证据缺失。若某项数据来自人工计算或二次汇总也应注明来源文件和计算口径。10. 四个常见误区第一只保存最好的一轮。异常轮次同样重要它能揭示稳定性和环境敏感性。第二测试结束后再凭记忆补配置。运行前就应复制实际配置并生成运行编号。第三把监控截图当原始数据。截图适合展示原始时间序列才适合复盘和重新计算。第四修改原始日志后不留痕迹。任何过滤、聚合和清洗都应生成新文件保留原始证据。系列文章第一篇数据库基准测试工具是什么第二篇从一次时序数据库写入测试开始第三篇如何模拟线上写入负载第四篇如何读懂测试结果波动第五篇什么是读写混合负载第六篇如何模拟线上读写混合负载第七篇怎样做一场公平的性能对比第八篇怎样找到并发与批大小的合理区间第九篇如何模拟乱序写入第十篇不同写入接口该怎样比较第十一篇性能测试与正确性验证有什么区别第十二篇单机测试与集群测试有什么不同第十三篇怎样保存和复盘一轮测试第十四篇一份可复用的基准测试方案模板