上一篇我们聊了一下通用 TSBS 工具《聊一聊TSBS：时序数据库跑分，为啥大家都用它？》
今天想就一家国内厂商开源的TSBS工具展开讲讲。怎么看这件事儿，怎么用，以及好不好用。

最近一直在玩时序数据库，做性能对比的时候离不开压测工具。今天给大家分享一下kwdb-tsbs，这是适配 KaiwuDB 的 TSBS 基准测试工具，我用下来感觉很顺手，整理了一份完整使用笔记，方便大家快速上手。参考 KaiwuDB 开源仓库：https://gitee.com/kwdb/kwdb-tsbs，所有内容都是我自己整理的实操笔记，方便大家直接照着跑。

一、kwdb-tsbs 是什么？

简单说，基于开源 TSBS（Time Series Benchmark Suite）改造、专为 KWDB 优化的时序数据库性能基准测试工具，已在 Gitee/GitHub 开源（MIT协议）。支持生成数据、批量写入、跑查询、自动出报告，一套流程全搞定。总结有如下功能特性：

• 数据生成：支持自定义设备数量、数据采样时间范围和数据采样间隔。
• 数据导入：提供针对 KWDB 优化的批量写入工具。
• 查询场景：提供标准的时序查询模板。
• 自动化测试：一键执行完整的 KWDB 性能基准测试流程。

二、怎么看这件事儿？

数据库厂商把自家专用的性能测试工具开源出来，是一件很敢、也很聪明的做法。
搁以前，厂商自己写脚本、自己跑、自己出TPS/吞吐，用户端很难复现，经常被质疑美化数据。开源性能测试工具（比如kwdb-tsbs），相当于把标尺公开，让社区、用户、第三方都能用同一把尺子来测你的产品。
从用户角度来讲，有工具可以大大降低POC成本、缩短选型周期，避免“你测我不信、我测你不认” 的来回扯皮。
从行业角度来讲，时序数据场景数据量巨大、写入吞吐高、查询模式相对固定，非常依赖标准压测来证明产品能力。原生TSBS工具对具体产品的适配不足，可能并不能完整体现某一款特定产品的真实水平，自己做一套深度优化、贴合分布式时序引擎的TSBS分支，再开源，至少我觉得 KaiwuDB 是动过脑子的。
从厂商角度来讲，KaiwuDB 能开源自己的性能测试工具，无疑是对自身性能的自信+技术倒逼，不怕被用来和InfluxDB、TimescaleDB 等在同一框架下对比，还能根据社区反馈优化测试模型，不断提升行业信任。
更客观地说，毕竟是 KaiwuDB 主导开发，默认参数、写入路径、查询模板会更适配 KWDB，用来对比其他数据库时需注意公平性（比如参数对齐、版本一致之类）。如果各家厂商都愿意做这个事情，无疑会推动行业从“黑盒宣传”走上透明可信的路。

三、kwdb-tsbs 支持哪些测试场景？

主要分两大场景，包括平时最常见的监控和物联网数据：

1. DevOps cpu-only

测试场景关注 CPU 指标，模拟服务器 CPU 监控数据，支持各种聚合、分组、最大值、最新点查询，基本是时序库常用的查询类型。该测试场景模拟对服务器 CPU 监控生成的时序数据，针对每台设备（CPU）记录其 10 个 CPU 指标。下表是该场景中支持的查询类型：

查询类型	描述
single-groupby-1-1-1	对单台主机的单个指标进行简单汇总（MAX）。每 5 分钟汇总一次，持续 1 小时。
single-groupby-1-1-12	对单台主机的单个指标进行简单汇总（MAX）。每 5 分钟汇总一次，持续 12 小时。
single-groupby-1-8-1	对八台主机的单个指标进行简单汇总（MAX）。每 5 分钟汇总一次，持续 1 小时。
single-groupby-5-1-1	对单台主机的五个指标进行简单汇总（MAX）。每 5 分钟汇总一次，持续 1 小时。
single-groupby-5-1-12	对单台主机的五个指标进行简单汇总（MAX）。每 5 分钟汇总一次，持续 12 小时。
single-groupby-5-8-1	对八台主机的五个指标进行简单汇总（MAX）。每 5 分钟汇总一次，持续 1 小时。
cpu-max-all-1	汇总 1 小时内单台主机每小时的所有 CPU 指标。
cpu-max-all-8	汇总 1 小时内八台主机每小时的所有 CPU 指标。
double-groupby-1	对时间和主机进行汇总，得出 24 小时内每台主机每小时单个 CPU 指标的平均值。
double-groupby-5	对时间和主机进行汇总，得出 24 小时内每台主机每小时 5 个 CPU 指标的平均值。
double-groupby-all	对时间和主机进行汇总，得出 24 小时内每台主机每小时所有 CPU 指标（10 个）的平均值。
high-cpu-all	所有主机的某个指标超过阈值的所有读数。
high-cpu-1	特定主机的某个指标超过阈值的所有读数。
lastpoint	每台主机的最后读数。
groupby-orderby-limit	在随机选定的时间终点前，按时间维度汇总的最后 5 个读数。

2. IoT

IoT 测试场景主要是模拟物联网环境中的数据负载。该测试场景模拟来自一家虚构卡车公司的一组卡车的数据流。它模拟每辆卡车的诊断数据和指标，并引入环境因素，如乱序数据和批量摄取（对于一段时间离线的卡车）。它还跟踪卡车元数据，并将其用于将指标和诊断作为查询集的一部分联系起来。在该测试场景中，一部分生成的查询将涵盖实时卡车状态和分析，这些分析将查看时序数据，以更好地预测卡车行为。该测试场景的规模因素将基于跟踪的卡车数量。下表为该测试场景中支持的查询类型：

查询类型	描述
last-loc	获取每辆卡车的实时（最新）位置。
low-fuel	获取所有燃料不足（低于 10%）的卡车。
high-load	获取当前负载高（超过 90% 负载容量）的卡车。
stationary-trucks	获取所有静止不动的卡车（最近 10 分钟内平均最低速度）。
long-driving-sessions	获取在过去 4 小时内未休息至少 20 分钟的卡车。
long-daily-sessions	获取在过去 24 小时内驾驶超过 10 小时的卡车。
avg-vs-projected-fuel-consumption	计算每个车队的平均燃料消耗量和预计燃料消耗量。
avg-daily-driving-duration	计算每位司机每天的平均驾驶时长。
avg-daily-driving-session	计算每位司机每天的平均驾驶次数。
avg-load	计算每个车队每种卡车型号的平均负载。
daily-activity	获取每个车队每天卡车处于活跃状态（相对于停运状态）的小时数。
breakdown-frequency	按卡车型号计算故障频率。

四、环境准备和编译

环境要求

只要装了 Go 1.23 及以上就行。

编译步骤

1. 克隆仓库

git clone https://gitee.com/kwdb/kwdb-tsbs.git
cd kwdb-tsbs

2. 构建应用

make

编译和安装成功后的文件清单如下：

kwdb-tsbs/
└── bin/
    ├── tsbs_generate_data      # 数据生成工具
    ├── tsbs_load_kwdb          # 数据导入工具
    ├── tsbs_generate_queries   # 查询生成工具
    └── tsbs_run_queries_kwdb   # 查询执行工具

五、完整使用流程（照着就能跑）

整个压测就四步：造数据→写数据→造查询→跑查询。

1. 生成数据

kwdb-tsbs 提供数据生成工具（tsbs_generate_data），为 KWDB 数据库生成一个伪 CSV 文件。其中，每行表示一条记录，首项为操作类型（1 或 3）。

• 1：表示插入数据（包括数据值和标签值），格式为 1,ptag名,字段数量,插入的数据。
• 3：表示写入标签值，格式为 3,表名,ptag名,标签值。
  示例：

1,host_0,11,(1451606400000,58,2,24,61,22,63,6,44,80,38,'host_0')3,cpu,host_0,('host_0','eu-central-1','eu-central-1a','6','Ubuntu15.10','x86','SF','19','1','test')

以下示例生成一个数据文件，可用于将数据批量加载到 KWDB 数据库中。

./tsbs_generate_data \--format="kwdb" \
  --use-case="cpu-only" \--seed=123 \--scale=100 \
  --timestamp-start="2016-01-01T00:00:00Z" \
  --timestamp-end="2016-01-02T00:00:00Z" \
  --log-interval="10s" \--orderquantity=12 \--orderquantity=12 \--outoforder="0.0" \--outoforderwindow="0" > data.dat 

参数说明：

参数	描述	类型	可选值	默认值
format	目标数据库的格式。	STRING	kwdb	N/A
use-case	测试场景类型。	STRING	cpu-only、iot	cpu-only
seed	伪随机数生成器 PRNG 种子。	INT	正整数	0，表示使用当前时间戳。
scale	生成数据的设备数量。	INT	正整数	1
timestamp-start	数据生成的起始时间。遵循 RFC 3339 标准。	STRING	N/A	2016-01-01T00:00:00Z
timestamp-end	数据生成的结束时间。遵循 RFC 3339 标准。	STRING	N/A	2016-03-02T00:00:00Z
log-interval	数据生成的间隔时间。	STRING	如 “10s”、“1m”	10s
orderquantity	初始生成设备数量。例如，对于 100 台 设备，首先生成从 host_0 到 host_11 的数据，然后生成从 host_12 到 host_23 的数据，依此类推。	INT	正整数	建议与导入数据时使用的 worker 参数的取值保持一致。
outoforder	设置乱序数据的比例，取值范围是 0.0 - 1.0。例如，0.0 表示完全按顺序生成数据。0.1 表示乱序生成 10% 的数据。1.0 表示完全随机乱序生成数据。说明:该参数只适用于 DevOps cpu-only 测试场景。	FLOAT	N/A	0.0
outoforderwindow	设置乱序数据的时间窗口范围，支持多种时间单位，例如，0s、1m、1h。其中，0 表示按时间顺序生成数据。60s 表示允许在 60s 时间范围内乱序生成数据。实际数据乱序程度还受 outoforder 参数的影响。说明:该参数只适用于 DevOps cpu-only 测试场景。	DURATION	N/A	0

2. 入数据

kwdb-tsbs 提供数据导入工具（tsbs_load_data），将由 tsbs_generate_data 工具生成的数据文件导入到目标数据库。tsbs_load_data 工具支持 INSERT 模式和 PREPARE 模式。两种数据导入模式的参数基本相同。

• INSERT 模式

./tsbs_load_kwdb \--file=data.dat \--user=root \--pass=1234 \--host=127.0.0.1 \--port=26257 \
  --insert-type=insert \
  --batch-size=1000 \
  --db-name=benchmark \--case=cpu-only \--workers=12 \--partition=false

• PREPARE 模式

./tsbs_load_kwdb \--file=data.dat \--user=root \--pass=1234 \--host=127.0.0.1 \--port=26257 \
  --insert-type=prepare \--preparesize=1000 \
  --db-name=benchmark \--case=cpu-only \--workers=12 \--partition=false

参数说明：

参数	描述	类型	可选值	默认值
file	数据生成文件的路径。	STRING	N/A	N/A
user	连接 KWDB 数据库的用户名。	STRING	N/A	root
pass	身份验证时使用的密码。	STRING	N/A	默认为空。
host	KWDB 数据库的 IP 地址。	STRING	N/A	N/A
port	WDB 数据库的连接端口。	INT	N/A	26257
insert-type	数据写入模式。insert：直接插入数据，适用于 DevOps cpu-only 和 IoT 测试场景。prepare：预编译数据，适用于 DevOps cpu-only 测试场景。prepareiot：预编译数据，适用于 IoT 测试场景。	STRING	insert、prepare 或 prepareiot	insert
batch-size 或 preparesize	每批次写入的数据量。说明：batch-size 参数只适用于 INSERT 模式。preparesize 参数只适用于 PREPARE 模式。	INT	正整数	1000
db-name	需要访问的 KWDB 数据库名称。	STRING	N/A	benchmark
case	测试场景类型。	STRING	cpu-only、iot	cpu-only
workers	并发写入线程数。	INT	正整数	建议与生成数据时使用的 orderquantity 参数的取值保持一致。
partition	设置是否分区。单节点：false。集群：true	BOOL	true 或 false	false

3. 生成查询

kwdb-tsbs 提供查询生成工具（tsbs_generate_queries），用以生成指定查询类型的查询脚本。

./tsbs_generate_queries \--format=kwdb \
    --use-case="cpu-only" \--seed=123 \--scale=100 \
    --query-type=${QUERY_TYPE} \--prepare=false \--queries=100 \
    --timestamp-start="2016-01-01T08:00:00Z" \
    --timestamp-end="2016-01-05T00:00:01Z" \
    --db-name=benchmark > query.dat

参数说明：

参数	描述	类型	可选值	默认值
format	目标数据库的格式。	STRING	kwdb	N/A
use-case	测试场景类	STRING	cpu-only、iot	cpu-only
seed	伪随机数生成器 PRNG 种子。	INT	正整数	0，表示使用当前时间戳。
scale	生成查询的设备数量。	INT	正整数	1
query-type	查询类型。	STRING	有关 kwdb-tsbs 支持的查询类型，参见测试场景。	N/A
prepare	设置是否使用查询模板。	BOOL	true 或 false	false
queries	产生的查询语句数量。	INT	正整数	N/A
timestamp-start	查询生成的起始时间。遵循 RFC 3339 标准。	STRING	N/A	2016-01-01T08:00:00Z
timestamp-end	查询生成的结束时间。遵循 RFC 3339 标准。	STRING	N/A	2016-01-05T00:00:01Z
db-name	需要访问的 KWDB 数据库名称。	STRING	N/A	benchmark

4. 执行查询

在完成数据生成、数据导入、查询生成后，用户可以使用 tsbs_run_queries_kwdb 工具测试 KWDB 数据库的查询执行性能。

./tsbs_run_queries_kwdb \--file=query.dat \--user=root \--pass=1234 \--host=127.0.0.1 \--port=26257 \
    --query-type=${QUERY_TYPE} \--prepare=false \--workers=1 > query.log

参数说明：

参数	描述	类型	可选值	默认值
file	数据生成文件的路径。	STRING	N/A	N/A
user	连接 KWDB 数据库的用户名。	STRING	N/A	root
pass	身份验证时使用的密码。	STRING	N/A	默认为空。
host	KWDB 数据库的 IP 地址。	STRING	N/A	N/A
port	KWDB 数据库的连接端口。	INT	N/A	26257
query-type	查询类型。该参数取值必须与查询生成工具设置的参数取值保持一致。	STRING	有关 kwdb-tsbs 支持的查询类型，参见测试场景。	N/A
prepare	设置是否使用查询模板。该参数取值必须与查询生成工具设置的参数取值保持一致。	BOOL	true 或 false	false
workers	并发查询线程数。	INT	正整数	N/A

六、自动化测试

kwdb-tsbs 还在 kwdb-tsbs/scripts 目录下提供了自动化脚本（tsbs_kwdb.sh），用户可以一键执行完整的 KWDB 性能基准测试流程。一键就能执行完整的压测流程，适合批量测试或重复测试。

1. 前提条件

• 已安装 kwdb-tsbs 以及 Go 1.23 或更高版本。
• 具有执行自动化测试脚本的权限。

2. 推荐配置

• 硬件配置
  下表列出执行自动化测试推荐的硬件规格。用户可以根据实际的业务规模和性能要求规划硬件资源。

组件	规格
CPU	16 核
内存	32 GB
磁盘	SSD

• 操作系统
  下表列出执行自动化测试推荐的操作系统。未提及的操作系统版本也许可以运行自动化测试脚本，但尚未得到 KWDB 官方支持。

操作系统	版本	架构
Ubuntu	V20.04	x86_64

3. 执行自动化脚本

• 配置自动化脚本参数。

workspace="$GOPATH/src/gitee.com/kwdb"

参数说明：
workspace：KWDB 工作目录的路径。有关更多自动化测试脚本的参数配置，参见脚本文件中的详细注释说明。

• 执行自动化脚本。

cd kwdb-tsbs/scripts
./tsbs_kwdb.sh

运行完成后，生成以下相关文件：

kwdb-tsbs/
├── load_data/          # 生成的导入数据
├── query_data/         # 生成的查询数据
└── reports/            # 生成的测试结果
└── YMD_HMS_scale[scaleNum]_cluster[clusterNum]_insert[insertType]_wal[walSetting]_replica[replicaNum]_dop[degreeOfParallelism]/
├── load_data/  # 导入测试的结果
└── query_data/ # 查询测试的结果

综上，kwdb-tsbs 作为适配 KWDB 时序数据库的专属压测工具，实操门槛低、功能覆盖还是比较全面的，可以高效完成数据生成、导入、查询及自动化压测全流程。如果大家在使用过程中遇到问题，欢迎在评论区留言，我也推荐去官方仓库（https://gitee.com/kwdb/kwdb-tsbs）查看详细文档，能获取更全面的配置说明和问题解决方案。希望这份实操笔记能帮大家少踩坑，快速上手kwdb-tsbs！