From: Edwin Rodriguez <edwin.rodriguez1@ibm.com>
Date: Mon, 22 Jun 2026 14:15:20 +0000 (-0400)
Subject: doc/cephfs: document new benchmark options and features
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=9c0f43e7da9f5f76ae31f08a8455331ed40b5bcf;p=ceph.git

doc/cephfs: document new benchmark options and features

Fixes: https://tracker.ceph.com/issues/76183
Signed-off-by: Edwin Rodriguez <edwin.rodriguez1@ibm.com>
---

diff --git a/doc/cephfs/cephfs-tool.rst b/doc/cephfs/cephfs-tool.rst
index 8bdbe6c98988..334ba5786ae9 100644
--- a/doc/cephfs/cephfs-tool.rst
+++ b/doc/cephfs/cephfs-tool.rst
@@ -15,6 +15,10 @@ Key features include:
 * Configurable block sizes, file counts, and fsync intervals.
 * Detailed statistical reporting (Mean, Std Dev, Min/Max) for throughput and IOPS.
 * Support for specific CephFS user/group impersonation (UID/GID) via ``ceph_mount_perms_set``.
+* Optional JSON output and libcephfs perf counter dumps.
+* Optional progress reporting during benchmark phases.
+* Optional asynchronous I/O benchmarking with configurable queue depth.
+* Optional overrides for selected client configuration settings such as object cache and messenger worker threads.
 
 Building
 ========
@@ -60,7 +64,7 @@ General Options
 
    Path to keyring file
 
-.. option:: --filesystem <name>
+.. option:: --filesystem, --fs <name>
 
    CephFS filesystem name to mount
 
@@ -72,6 +76,19 @@ General Options
 
    Group ID to mount as (default: ``-1``)
 
+.. option:: --client-oc <0|1>
+
+   Override the ``client_oc`` setting for the benchmark mount
+
+.. option:: --client-oc-size <value>
+
+   Override the ``client_oc_size`` setting for the benchmark mount
+
+.. option:: --msgr-workers <n>
+
+   Override ``ms_async_op_threads`` for the benchmark mount. Valid values are
+   ``1`` to ``24``; ``0`` keeps the configured default.
+
 Benchmark Options
 -----------------
 
@@ -121,6 +138,40 @@ These options are used with the ``bench`` command.
 
    Disable cleanup of files
 
+.. option:: --json <path>
+
+   Write structured benchmark results to a JSON file
+
+.. option:: --duration <seconds>
+
+   Limit each write and read phase to ``N`` seconds. A value of ``0`` means the
+   benchmark processes all files.
+
+.. option:: --perf-dump <path>
+
+   Dump libcephfs performance counters to the specified file after the benchmark
+
+.. option:: --progress
+
+   Show live progress, bandwidth, file rate, and ETA during benchmark phases
+
+.. option:: --progress-interval <percent>
+
+   Minimum percentage increment between progress updates (default: ``10``;
+   valid range: ``1`` to ``100``)
+
+.. option:: --async-io
+
+   Use asynchronous I/O via ``ceph_ll_nonblocking_readv_writev`` for read and
+   write phases
+
+.. option:: --queue-depth <n>
+
+   Maximum number of outstanding async I/Os per worker thread (default:
+   ``16``; valid range: ``1`` to ``1024``). This option is only meaningful with
+   ``--async-io`` and ``--async-io`` cannot be combined with
+   ``--per-thread-mount``.
+
 Examples
 ========