doc/rados/bluestore: Documentation for Interpreting spillover cleaner stats

Signed-off-by: Jaya Prakash <jayaprakash@ibm.com>

diff --git a/doc/rados/bluestore/bluefs-spillover-cleaner.rst b/doc/rados/bluestore/bluefs-spillover-cleaner.rst
index 7d25dbf6de38901bf948c8493330c5803d0fc095..023cccabaf6f634714c6448948a31ea02f95e384 100644 (file)
--- a/doc/rados/bluestore/bluefs-spillover-cleaner.rst
+++ b/doc/rados/bluestore/bluefs-spillover-cleaner.rst
@@ -80,21 +80,66 @@ Example output:
    {
     "Files Migrated": [
         ...
-        "db.wal/000052.log size=0x24cd21 migrated=0x1200000 from dev=2->1 ts=2026-06-02T12:44:25.488250+0000",
-        "db.wal/000053.log size=0x3696ad migrated=0x1200000 from dev=2->1 ts=2026-06-02T12:44:25.833014+0000",
-        "db.wal/000054.log size=0x1571f61 migrated=0x2400000 from dev=2->1 ts=2026-06-02T12:44:26.134245+0000",
-        "db.wal/000055.log size=0x1b2b508 migrated=0x2400000 from dev=2->1 ts=2026-06-02T12:44:26.550633+0000"
+        "db/000084.sst size=0xf8cd6 migrated=0x100000 from dev=2->1 ts=2026-07-22T18:49:42.555723+0000",
+        "db/000086.sst size=0xfdd34 migrated=0x100000 from dev=2->1 ts=2026-07-22T18:49:42.595349+0000",
+        "db.wal/000078.log size=0x19de2e2 migrated=0x2400000 from dev=2->1 ts=2026-07-22T18:49:42.694700+0000",
+        "db.wal/000079.log size=0x19d32f7 migrated=0x2400000 from dev=2->1 ts=2026-07-22T18:49:43.424059+0000",
+        "db.wal/000080.log size=0xd1a637 migrated=0x1200000 from dev=2->1 ts=2026-07-22T18:49:44.204353+0000",
+        "db.wal/000081.log size=0xcbeaf5 migrated=0x1200000 from dev=2->1 ts=2026-07-22T18:49:44.618457+0000",
+        "db.wal/000082.log size=0xd6737 migrated=0x1200000 from dev=2->1 ts=2026-07-22T18:49:44.892949+0000",
+        "db.wal/000083.log size=0x696fe8 migrated=0x1200000 from dev=2->1 ts=2026-07-22T18:49:45.279432+0000"
     ],
     "pending_files": [
-        "db.wal/000056.log",
-        "db.wal/000057.log",
-        "db.wal/000058.log",
-        "db.wal/000059.log",
-        "db.wal/000060.log",
+        "db.wal/000091.log",
+        "db.wal/000092.log",
+        "db.wal/000093.log",
+        "db.wal/000094.log",
+        "db.wal/000095.log",
         ...
-    ]
+    ],
+    "active_files": [
+        "db.wal/000085.log num_writers=1",
+        "db.wal/000087.log num_writers=1",
+        "db.wal/000088.log num_writers=1",
+        "db.wal/000089.log num_writers=1",
+        "db.wal/000090.log num_writers=1"
+    ],
+    "last_scan_time": "2026-07-22T18:51:15.895644+0000"
    }
 
+Interpreting Cleaner Stats
+==========================
+
+The spillover cleaner operates in repeated scan cycles of alternating Active and Idle phases.
+The output of ``ceph tell osd.N bluefs spillover cleaner stats`` shows the
+current cycle state and migration history of spillover cleaner.
+
+``Files Migrated``
+  Contains a list of entries for files that have been recently migrated from the slow device
+  to the DB device.
+
+  Example entry::
+
+     db/000084.sst size=0xf8cd6 migrated=0x100000 from dev=2->1 ts=2026-07-22T18:49:42.555723+0000
+
+``pending_files``
+  At the beginning of each cycle, the spillover cleaner scans for files on the slow device and adds them to ``pending_files``.
+  These files are later processed one by one.
+
+  - Successfully migrated files are removed from ``pending_files`` and added
+    to ``Files Migrated``.
+  - Files open for write are removed from ``pending_files`` and reported
+    in ``active_files`` for that cycle.
+
+  A new scan is performed at the beginning of the next cycle.
+
+``active_files``
+  Contains files that have active writers when the cleaner attempted to
+  migrate them. Migration of these files are skipped during the current cycle.
+
+``last_scan_time``
+  Shows the time of the most recent cleaner scan.
+
 Testing
 =======