CephFS 用户态性能基准工具 cephfs-tool 完全指南:构建、配置与源码级原理
CephFS 用户态性能基准工具 cephfs-tool 完全指南:构建、配置与源码级原理
cephfs-tool 是 Ceph 仓库中一个独立的 C++ 工具,用于直接通过 libcephfs 库访问 CephFS 并执行多线程读写基准测试(bench 命令)。与 FUSE 或内核客户端不同,它完全运行在用户态,因此能隔离并测量 libcephfs 库本身的性能特征。本文将基于 doc/cephfs/cephfs-tool.rst 官方文档,结合 src/tools/cephfs/cephfs-tool.cc 的完整实现,讲解该工具的构建方法、全部命令行选项、典型使用场景,并深入到源码层面揭示其基准测试流程、异步 I/O 模型与配置覆盖机制的工作原理。读完本文,你将能够独立编译、配置并运行 cephfs-tool,解读其统计输出,并根据实际场景调优参数。
工具概述:为什么需要用户态基准测试
CephFS 提供多种访问路径:内核客户端、FUSE 挂载以及直接调用 libcephfs 库。传统的 dd 或 fio 基准测试往往经过 VFS、FUSE 或内核驱动等中间层,无法精确反映 CephFS 客户端库本身的吞吐能力。
cephfs-tool 的设计目标正是填补这一空白:它直接以 libcephfs 为 I/O 后端,避免了 FUSE 与内核客户端的开销,从而让开发者和管理员能够:
- 测量多线程读写吞吐量与 IOPS(每秒文件操作数);
- 验证对象缓存(ObjectCacher)、消息层线程数等客户端配置对性能的影响;
- 在引入 FUSE 或内核客户端之前,先对
libcephfs层做性能验收。
其核心特性在文档与源码中均有明确体现(src/tools/cephfs/cephfs-tool.cc):
- 多线程读写吞吐基准测试;
- 可配置的块大小(block size)、文件数量与 fsync 间隔;
- 详细的统计报告:均值(Mean)、标准差(Std Dev)、最小值/最大值(Min/Max),覆盖吞吐量与文件操作速率;
- 通过
ceph_mount_perms_set支持以指定 UID/GID 挂载(用户/组模拟); - 可选的 JSON 结果输出与 libcephfs 性能计数器(perf counter)导出;
- 可选的进度实时报告(带宽、文件速率、ETA);
- 可选的异步 I/O 基准测试,支持可配置队列深度(queue depth);
- 可选的客户端配置覆盖,如对象缓存(
client_oc/client_oc_size)与消息层工作线程数(ms_async_op_threads)。
构建 cephfs-tool
独立构建(不依赖 Ceph 源码树)
官方文档给出的构建命令非常轻量,只需要 C++20 编译器、libcephfs 开发库与 Boost.ProgramOptions:
g++ --std=c++20 -D_FILE_OFFSET_BITS=64 -O3 -o cephfs-tool cephfs-tool.cc -lcephfs -lpthread -lboost_program_options
要点说明:
-D_FILE_OFFSET_BITS=64:启用 64 位文件偏移,保证大文件基准(如文档示例中的 128 MiB 文件)能够正确寻址;-lcephfs:链接 libcephfs 用户态库;-lboost_program_options:命令行解析依赖 Boost.ProgramOptions(见 src/tools/cephfs/cephfs-tool.cc 中大量po::options_description的使用);--std=c++20:源码使用 C++20 特性,包括std::span、std::counting_semaphore等(见 src/tools/cephfs/cephfs-tool.cc)。
随 Ceph 源码树构建
cephfs-tool 也集成在 Ceph 的 CMake 构建体系中。在 src/tools/cephfs/CMakeLists.txt 中可以看到:
set(cephfs_tool_srcs
cephfs-tool.cc)
add_executable(cephfs-tool ${cephfs_tool_srcs})
target_include_directories(cephfs-tool PRIVATE ${PROJECT_SOURCE_DIR}/src/include)
target_link_libraries(cephfs-tool ceph-common librados cephfs osdc global uring::uring
${BLKID_LIBRARIES} ${CMAKE_DL_LIBS} Boost::filesystem)
该目标会安装到 bin 目录。注意:完整构建链接的库(ceph-common、librados、cephfs、osdc、global 等)比独立构建更多,这是因为树内构建可以复用 Ceph 内部组件(例如 common/JSONFormatter.h、perf counters 收集等)。
命令行结构与完整选项表
cephfs-tool 的命令行格式为:
cephfs-tool [general-options] <command> [command-options]
当前唯一的子命令是 bench(运行 I/O 基准测试)。从 src/tools/cephfs/cephfs-tool.cc 的实现可以看到,若未指定子命令或传入未知子命令,工具会报错退出;--help 会打印完整选项说明。
通用选项(General Options)
以下选项作用于挂载与客户端配置,在 bench 命令前后均可使用:
| 选项 | 说明 | 默认值 |
|---|---|---|
-h, --help |
打印帮助信息 | — |
-c, --conf <path> |
Ceph 配置文件路径;未指定时按默认路径搜索 | — |
-i, --id <id> |
客户端 ID(Ceph auth 身份) | admin |
-k, --keyring <path> |
keyring 文件路径 | — |
--filesystem, --fs <name> |
要挂载的 CephFS 文件系统名称 | 默认文件系统 |
--uid <uid> |
挂载时模拟的用户 ID | -1(不模拟) |
--gid <gid> |
挂载时模拟的组 ID | -1(不模拟) |
--client-oc <0|1> |
覆盖基准挂载的 client_oc(对象缓存开关)设置 |
不覆盖 |
--client-oc-size <value> |
覆盖 client_oc_size(对象缓存大小上限)设置,支持 K/M/G/T 后缀 |
不覆盖 |
--msgr-workers <n> |
覆盖 ms_async_op_threads(异步消息线程数)。合法值 1~24,0 表示沿用配置默认 |
0 |
基准选项(Benchmark Options)
这些选项仅与 bench 命令配合使用:
| 选项 | 说明 | 默认值 |
|---|---|---|
--threads <n> |
线程数 | 1 |
--iterations <n> |
迭代次数(每次迭代都包含完整的写/读阶段) | 1 |
--files <n> |
文件总数(均分到各线程) | 100 |
--size <size> |
文件大小(如 4MB;0 表示仅测创建) |
4MB |
--block-size <size> |
单次 I/O 块大小(如 1MB) |
4MB |
--fsync-every <size> |
每写入 N 字节调用一次 fsync | 0(不调用) |
--prefix <str> |
文件名前缀 | benchmark_ |
--dir-prefix <str> |
基准目录前缀(实际目录名会追加随机十六进制后缀) | bench_run_ |
--root-path <path> |
CephFS 内的根路径(挂载点) | / |
--per-thread-mount |
每个线程使用独立的挂载(ceph_mount_info) |
关闭 |
--no-cleanup |
禁用基准结束后的文件清理 | 关闭(默认清理) |
--json <path> |
将结构化结果写入 JSON 文件;- 表示输出到 stdout |
关闭 |
--duration <seconds> |
将每个写/读阶段限制为 N 秒;0 表示处理全部文件 |
0 |
--perf-dump <path> |
基准结束后将 libcephfs 性能计数器导出到指定文件 | 关闭 |
--progress |
基准阶段显示实时进度、带宽、文件速率与 ETA | 关闭 |
--progress-interval <percent> |
进度更新的最小百分比增量(1~100) |
10 |
--async-io |
通过 ceph_ll_nonblocking_readv_writev 使用异步 I/O 执行读写阶段 |
关闭 |
--queue-depth <n> |
每个工作线程的最大在途异步 I/O 数(1~1024) |
16 |
源码中额外存在的选项
从 src/tools/cephfs/cephfs-tool.cc 可以看到,除文档列出的选项外,源码还支持两个高级选项:
--async-write-fsync:在--async-io模式下,每次异步写都携带 fsync(通过ceph_ll_io_info.fsync标志实现,模拟 NFS-Ganesha 风格写入)。该选项要求--async-io;--shared-file:在--async-io模式下,所有线程写入同一个共享文件(用于压力测试 cap flush 等待路径)。该选项要求--async-io,且指定后会强制--files 1。
此外,若以 CEPH_LOCKSTAT 宏编译,还会出现 --lockstat-dump 与 --lockstat-threshold 两个锁竞争分析选项。
选项校验规则(源码级)
主函数在进入基准前会做一系列合法性校验(src/tools/cephfs/cephfs-tool.cc):
--progress-interval必须在1~100之间;--msgr-workers非 0 时必须在1~24之间;--queue-depth必须在1~1024之间;--async-io与--per-thread-mount互斥(异步路径使用共享挂载 + 每线程 I/O 队列);--async-write-fsync、--shared-file都依赖--async-io;--block-size不能超过 2 GiB(受 libcephfs API 限制,见 src/tools/cephfs/cephfs-tool.cc)。
挂载与客户端配置覆盖的内部机制
setup_mount() 函数(src/tools/cephfs/cephfs-tool.cc)封装了完整的挂载流程,理解它有助于解释各选项的真实作用:
- 创建实例:调用
ceph_create()创建ceph_mount_info句柄,使用--id指定的客户端 ID; - 读取配置文件:优先读取
--conf指定路径;未指定则调用ceph_conf_read_file(cmount, NULL)搜索默认位置(如/etc/ceph/ceph.conf); - 应用覆盖项(必须在
ceph_init()之前,否则无法生效):--client-oc→ceph_conf_set(cmount, "client_oc", ...),用于在创建 ObjectCacher 前打开/关闭对象缓存;--msgr-workers→ceph_conf_set(cmount, "ms_async_op_threads", ...),调整消息层异步操作线程数(注意这是 messenger 的 I/O 线程,并非基准工作线程);--client-oc-size→ 先将人类可读大小(如1GB)经parse_size()换算为字节,再写入client_oc_size;--keyring→ 写入keyring配置项;--filesystem→ 写入client_mds_namespace配置项,即多文件系统(multifilesystem)场景下的命名空间选择;
- 初始化客户端:调用
ceph_init(); - 应用 UID/GID 模拟:若指定了
--uid或--gid,则调用ceph_userperm_new(uid, gid, 0, NULL)构造UserPerm,随后通过ceph_mount_perms_set()应用到挂载句柄(对应文档中提到的用户/组模拟能力,API 声明见 src/include/cephfs/libcephfs.h)。设置完成后立即ceph_userperm_destroy()释放权限对象; - 挂载:
ceph_mount(cmount, mount_root),挂载到--root-path指定的目录。
值得注意的细节:--per-thread-mount 模式下,每个工作线程会独立执行一次完整的 setup_mount(),而共享模式下所有线程复用主挂载句柄。
大小解析规则
parse_size()(src/tools/cephfs/cephfs-tool.cc)同时支持 SI(1000 进制)与二进制(1024 进制)后缀:
- SI 后缀:
KB、MB、GB、TB(分别乘以 1000、10⁶、10⁹、10¹²); - 二进制后缀:
KiB、MiB、GiB、TiB(分别乘以 1024、2²⁰、2³⁰、2⁴⁰); - 单字母后缀(如
4M)按二进制解释。
文档示例中的 $(( 128 * 2 ** 20 ))(=134217728 字节)正是 128 MiB 的精确二进制写法。
基准测试工作流程
do_bench()(src/tools/cephfs/cephfs-tool.cc)实现了完整的基准流程,每次迭代遵循固定顺序:
- 创建主挂载并打印基准配置(线程数、文件数、文件系统、根路径、生成的随机子目录等);
- 创建基准目录:目录名为
dir_prefix + 随机十六进制后缀(如bench_run_d942),权限 0755; - 统计基准前文件系统状态(
statvfs:总块数、空闲块数、文件数); - 写阶段(Write Phase):
- 文件按线程均分(余数分配给前几个线程);
- 每个工作线程以
ceph_open(..., O_CREAT|O_WRONLY|O_TRUNC, 0644)创建文件(O_CREAT确保创建开销也被计入测量),再以ceph_write循环写入,块大小由--block-size决定; - 若设置了
--fsync-every,则写入量达到间隔时调用ceph_fsync; - 写满后
ceph_close关闭文件; - 阶段结束后调用
ceph_sync_fs确保缓冲数据落盘到 MDS;
- 缓存清除(Re-mount):非
--per-thread-mount模式下,会先卸载并关闭挂载,再重新挂载,从而丢弃客户端页缓存,保证读阶段测量的是来自 OSD 的"冷读"性能(见 src/tools/cephfs/cephfs-tool.cc)。--per-thread-mount模式下各线程独立挂载则天然没有共享缓存问题; - 读阶段(Read Phase):以
O_RDONLY打开同一批文件,用ceph_read顺序读取,读到 EOF(返回 0)结束; - 多迭代清理:若还有后续迭代,先并发 unlink 文件并清理目录,再进入下一轮;若为最后一轮,则在汇总报告后执行最终清理(除非
--no-cleanup); - 收尾:可选导出 perf 计数器(
--perf-dump)、写出 JSON(--json)、卸载并关闭。
错误处理方面,任意线程遇到致命错误都会置位 stop_signal 原子标志,其余线程据此提前退出,主线程通过 check_and_report_errors() 汇总各线程的 stringstream 日志并返回失败码。
线程与统计模型
每个线程维护一组原子计数器(src/tools/cephfs/cephfs-tool.cc):
bytes_transferred:传输字节数;ops:读写调用次数(用于 IOPS 统计);files:成功打开/关闭的文件数;errors:错误计数。
工作线程通过 ceph_pthread_setname() 命名为 wr-worker-N / rd-worker-N,便于在 top、perf 等工具中归因。阶段结束后,主线程聚合各线程统计值计算吞吐量(MiB/s)与文件速率(files/s),并记录到跨迭代的向量中,最终由 print_statistics()(src/tools/cephfs/cephfs-tool.cc)输出均值、标准差、最小/最大值。
--duration 模式的行为差异
当 --duration N 大于 0 时,每个写/读阶段最多持续 N 秒,线程会在到达时间上限时停止,并且文件名按 i % files 循环复用(同一轮迭代内同一文件可能被多次覆盖写入),此时 --files 决定的是每线程的文件集大小而非严格总数。当 --duration 为 0(默认)时,必须写完全部文件,否则视为失败退出。
异步 I/O 基准(--async-io)原理
异步模式是 cephfs-tool 的一个高级特性,它绕过传统同步 ceph_write/ceph_read,改用 libcephfs 的底层非阻塞接口 ceph_ll_nonblocking_readv_writev(声明见 src/include/cephfs/libcephfs.h)。
I/O 提交模型
每个工作线程预分配 queue_depth 个 AsyncIOContext 槽位(src/tools/cephfs/cephfs-tool.cc),每个槽位持有:
- 独立的
ceph_ll_io_info结构(包含回调函数指针、私有数据、文件句柄、iovec 与偏移量,结构定义见 src/include/cephfs/libcephfs.h); - 持久化的 I/O 缓冲区与
struct iovec(异步操作生命周期内必须保持有效); - 完成标志、信号量指针等同步原语。
提交流程为:
- 线程通过
std::counting_semaphore控制队列深度,每次提交前acquire()等待空槽; - 找到空闲
AsyncIOContext,填充ceph_ll_io_info(文件句柄、iovec、偏移量、读写方向),置completed=false后调用ceph_ll_nonblocking_readv_writev()提交; - 提交成功后立即继续填充下一个块,无需等待完成——这正是异步模型吞吐的关键;
- 回调
async_io_callback()(src/tools/cephfs/cephfs-tool.cc)在 I/O 完成时被触发:累加bytes_transferred/ops,置completed=true并释放信号量;错误时置位stop_signal并累计错误; - 关闭文件前,线程会等待该文件所有在途 I/O 完成并执行
ceph_ll_fsync(除非使用--async-write-fsync让每次写都携带 fsync),避免数据停留在缓冲中; - 线程退出前再次等待所有在途 I/O 完成(
completed可能先于 finisher 回调置位,因此还要等待active_callbacks归零)。
读路径还做了专门处理:inode 引用延迟到线程末尾统一释放,确保 readahead 等异步操作不会访问已释放的 inode(src/tools/cephfs/cephfs-tool.cc)。此外异步模式使用低层 ceph_ll_walk/ceph_ll_create/ceph_ll_open 接口(文件路径解析与同步 ceph_open 保持一致的模型),并借助 UserPerm 传递 UID/GID。
队列深度的影响
--queue-depth 决定每个线程同时在途的异步 I/O 数量,默认 16,合法范围 1~1024。更大的队列深度允许更多请求在消息层与 OSD 之间流水线化,通常能提升吞吐,但也会增加内存占用(每个槽位持有一个 block-size 大小的缓冲区)与客户端侧并发压力。该选项仅在 --async-io 下有意义,且异步模式与 --per-thread-mount 不兼容。
典型使用场景与示例
场景一:多线程读写吞吐基准
文档给出了一个 8 线程、256 个文件、每个文件 128 MiB、3 次迭代的完整示例:
env CEPH_ARGS="--log-to-stderr=false --log-to-file=false --log-file=/tmp/bench.log" \
./cephfs-tool -c ~/ceph.conf -k ~/keyring -i scratch --filesystem scratch \
bench --root-path=/pdonnell --files 256 --size=$(( 128 * 2 ** 20 )) \
--threads=8 --iterations 3
解释:
CEPH_ARGS环境变量把客户端日志重定向到/tmp/bench.log,避免日志干扰终端输出(日志不写 stderr、不写文件,而是写入指定日志文件);-c ~/ceph.conf -k ~/keyring -i scratch指定配置文件、keyring 与客户端 ID;--filesystem scratch挂载名为scratch的 CephFS 文件系统;--root-path=/pdonnell在/pdonnell下创建基准目录;--size=$(( 128 * 2 ** 20 ))即 128 MiB 文件;--threads=8 --iterations 3:8 线程并发、重复 3 轮取统计。
工具启动后会打印配置摘要与每轮进度,最终输出形如:
Benchmark Configuration:
Threads: 8 | Iterations: 3
Files: 256 | Size: 134217728
Filesystem: scratch
Root: /pdonnell
Subdirectory: bench_run_d942
UID: -1
GID: -1
--- Iteration 1 of 3 ---
Starting Write Phase...
Write: 2761.97 MB/s, 21.5779 files/s (11.864s)
Starting Read Phase...
Read: 2684.36 MB/s, 20.9716 files/s (12.207s)
...
*** Final Report ***
Write Throughput Statistics (3 runs):
Mean: 2727.06 MB/s
Std Dev: 26.2954 MB/s
Min: 2698.51 MB/s
Max: 2761.97 MB/s
Read Throughput Statistics (3 runs):
Mean: 2687.24 MB/s
Std Dev: 5.68904 MB/s
Min: 2682.16 MB/s
Max: 2695.18 MB/s
File Creates Statistics (3 runs):
Mean: 21.3051 files/s
Std Dev: 0.205433 files/s
Min: 21.0821 files/s
Max: 21.5779 files/s
File Reads (Opens) Statistics (3 runs):
Mean: 20.994 files/s
Std Dev: 0.0444456 files/s
Min: 20.9544 files/s
Max: 21.0561 files/s
Cleaning up...
阅读要点:写吞吐统计来自各轮写阶段的 MiB/s 均值;文件创建速率(files/s)来自写阶段完成的文件数除以耗时;文件打开速率来自读阶段。方差(Std Dev)可用于评估多次运行的稳定性,若差异过大通常提示集群存在干扰因素。
场景二:纯文件创建/打开性能(metadata 基准)
将 --size=0 可跳过数据写入,专注于测量元数据路径(文件创建与打开)的性能:
env CEPH_ARGS="--log-to-stderr=false --log-to-file=false --log-file=/tmp/bench.log" \
./cephfs-tool -c ~/ceph.conf -k ~/keyring -i scratch --filesystem scratch \
bench --root-path=/pdonnell --files=$(( 2 ** 16 )) --size=0 \
--threads=8 --iterations 3
示例输出:
Benchmark Configuration:
Threads: 8 | Iterations: 3
Files: 65536 | Size: 0
...
*** Final Report ***
File Creates Statistics (3 runs):
Mean: 4001.86 files/s
Std Dev: 125.337 files/s
Min: 3863.7 files/s
Max: 4167.1 files/s
File Reads (Opens) Statistics (3 runs):
Mean: 14382.3 files/s
Std Dev: 556.594 files/s
Min: 13636.3 files/s
Max: 14972.8 files/s
Cleaning up...
从源码看,--size=0 时写阶段只执行 ceph_open(O_CREAT...) + ceph_close,不进入写循环;读阶段仅打开并关闭文件。此时吞吐统计(Write/Read Throughput)会被跳过,只报告文件创建与打开速率——这组指标直接反映了 MDS 的元数据处理能力。
场景三:结合配置覆盖调优客户端
使用 --client-oc、--client-oc-size、--msgr-workers 可以快速比较不同客户端配置下的性能,无需修改 ceph.conf。例如:
./cephfs-tool -c ~/ceph.conf -i admin bench \
--root-path=/bench --files 100 --size=64MB --threads=4 \
--client-oc 1 --client-oc-size 512MB --msgr-workers 8
从 src/tools/cephfs/cephfs-tool.cc 的实现可知,这些覆盖通过 ceph_conf_set() 在 ceph_init() 之前写入配置子系统,因此对本次基准挂载完全生效;配置摘要中会回读并打印实际生效值(client_oc、client_oc_size、ms_async_op_threads),便于确认覆盖成功。
场景四:异步 I/O 与 JSON 输出
./cephfs-tool -c ~/ceph.conf -i admin bench \
--root-path=/bench --files 64 --size=128MB --threads=4 \
--async-io --queue-depth 32 --json results.json --progress
--async-io --queue-depth 32启用异步 I/O,每线程最多 32 个在途请求;--json results.json将配置、每轮读写指标、统计摘要与文件系统前后状态(block_size、total_blocks、free_blocks、files)写入结构化 JSON;--json -则直接输出到 stdout,便于管道处理;--progress会打印实时进度行,格式为[百分比%][w=带宽MiB/s][w=IOPS][eta 分:秒],进度按--progress-interval指定的最小百分比增量刷新(默认 10%)。
结果解读与统计指标说明
print_statistics() 使用标准的均值/标准差公式:均值 = 总和/次数,标准差 = sqrt(平方和/次数 − 均值²),并同时输出最小值与最大值。--json 模式下这些指标会镜像到 JSON 的 summary 节(含 runs、mean、stddev、min、max、unit 字段)。
以下指标对应关系有助于解读报告:
- Write/Read Throughput(MiB/s):数据平面吞吐,反映 OSD 数据路径与客户端缓冲层的整体性能;
- File Creates(files/s):写阶段文件创建速率,反映 MDS 元数据创建能力;
- File Reads (Opens)(files/s):读阶段文件打开速率,反映 MDS 的 lookup/open 能力。
注意文档示例输出的单位显示为 "MB/s",而源码计算使用 1024*1024 进制(MiB/s),两者数值含义相同,均为二进制兆字节每秒。
注意事项与限制
- 异步模式的限制:
--async-io不能与--per-thread-mount组合使用;--async-write-fsync与--shared-file均依赖--async-io; - 块大小上限:
--block-size受 libcephfs API 限制不得超过 2 GiB; - 缓存影响:默认流程在写阶段后通过卸载重挂载清除客户端页缓存,确保读阶段为冷读;若使用
--per-thread-mount,各线程独立挂载天然避免了共享缓存,但也意味着每个线程有独立的客户端实例,更适合模拟多客户端场景; - 日志干扰:建议像文档示例那样用
CEPH_ARGS将日志导向文件,否则客户端日志可能与基准输出混杂; - 清理行为:默认在结束后并发 unlink 基准文件并
rmdir目录;需要保留数据用于后续分析时使用--no-cleanup; - 权限模拟:
--uid/--gid通过ceph_mount_perms_set在挂载上应用,可用来测试不同身份的权限路径,但需要确认所用 keyring 具备相应授权。
总结
cephfs-tool 通过直接绑定 libcephfs,为 CephFS 用户态客户端提供了精确、可控且可编程的基准测量手段。它既能以简单的同步多线程模式快速评估吞吐与元数据性能,也能通过异步 I/O、队列深度、配置覆盖等高级特性深入剖析客户端库的行为。结合本文所述的源码实现细节(挂载配置覆盖顺序、缓存清除重挂载、异步信号量模型、统计计算方式),你可以更准确地设计测试方案、解释数据并定位性能瓶颈。相关源码与文档位置:官方文档、工具实现、构建集成、libcephfs API 头文件。