doc: document `cephfs-top` utility

Signed-off-by: Venky Shankar <vshankar@redhat.com>

diff --git a/doc/cephfs/cephfs-top.png b/doc/cephfs/cephfs-top.png
new file mode 100644 (file)
index 0000000..f65aea1
Binary files /dev/null and b/doc/cephfs/cephfs-top.png differ

diff --git a/doc/cephfs/cephfs-top.rst b/doc/cephfs/cephfs-top.rst
new file mode 100644 (file)
index 0000000..200ca15
--- /dev/null
+++ b/doc/cephfs/cephfs-top.rst
@@ -0,0 +1,77 @@
+==================
+CephFS Top Utility
+==================
+
+CephFS provides `top(1)` like utility to display various Ceph Filesystem metrics
+in realtime. `cephfs-top` is a curses based python script which makes use of `stats`
+plugin in Ceph Manager to fetch (and display) metrics.
+
+Manager Plugin
+--------------
+
+Ceph Filesystem clients periodically forward various metrics to Ceph Metadata Servers (MDS)
+which in turn get forwarded to Ceph Manager by MDS rank zero. Each active MDS forward its
+respective set of metrics to MDS rank zero. Metrics are aggergated and forwarded to Ceph
+Manager.
+
+Metrics are divided into two categories - global and per-mds. Global metrics represent
+set of metrics for the filesystem as a whole (e.g., client read latency) whereas per-mds
+metrics are for a particular MDS rank (e.g., number of subtrees handled by an MDS).
+
+.. note:: Currently, only global metrics are tracked.
+
+`stats` plugin is disabled by default and should be enabled via::
+
+  $ ceph mgr module enable stats
+
+Once enabled, Ceph Filesystem metrics can be fetched via::
+
+  $ ceph fs perf stats
+  {"version": 1, "global_counters": ["cap_hit", "read_latency", "write_latency", "metadata_latency", "dentry_lease"], "counters": [], "client_metadata": {"client.614146": {"IP": "10.1.1.100", "hostname"  : "ceph-host1", "root": "/", "mount_point": "/mnt/cephfs", "valid_metrics": ["cap_hit", "read_latency", "write_latency", "metadata_latency", "dentry_lease"]}}, "global_metrics": {"client.614146": [[0,  0], [0, 0], [0, 0], [0, 0], [0, 0]]}, "metrics": {"delayed_ranks": [], "mds.0": {"client.614146": []}}}
+
+Details of the JSON command output are as follows:
+
+- `version`: Version of stats output
+- `global_counters`: List of global performance metrics
+- `counters`: List of per-mds performance metrics
+- `client_metadata`: Ceph Filesystem client metadata
+- `global_metrics`: Global performance counters
+- `metrics`: Per-MDS performance counters (currently, empty) and delayed ranks
+
+.. note:: `delayed_ranks` is the set of active MDS ranks that are reporting stale metrics.
+          This can happen in cases such as (temporary) network issue between MDS rank zero
+          and other active MDSs.
+
+Metrics can be fetched for a partcilar client and/or for a set of active MDSs. To fetch metrics
+for a particular client (e.g., for client-id: 1234)::
+
+  $ ceph fs perf stats --client_id=1234
+
+To fetch metrics only for a subset of active MDSs (e.g., MDS rank 1 and 2)::
+
+  $ ceph fs perf stats --mds_rank=1,2
+
+`cephfs-top`
+------------
+
+`cephfs-top` utility relies on `stats` plugin to fetch performance metrics and display in
+`top(1)` like format. `cephfs-top` is available as part of `cephfs-top` package.
+
+By default, `cephfs-top` uses `client.fstop` user to connect to a Ceph cluster::
+
+  $ ceph auth get-or-create client.fstop mon 'allow r' mds 'allow r' osd 'allow r' mgr 'allow r'
+  $ cephfs-top
+
+To use a non-default user (other than `client.fstop`) use::
+
+  $ cephfs-top --id <name>
+
+By default, `cephfs-top` connects to cluster name `ceph`. To use a non-default cluster name::
+
+  $ cephfs-top --cluster <cluster>
+
+Sample screenshot running `cephfs-top` with 2 clients:
+
+.. image:: cephfs-top.png
+
+.. note:: As of now, `cephfs-top` does not reliably work with multiple Ceph Filesystems.

diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst
index 6064321b7ce158440898b11494888704a1de9153..479cdfc40cea1f8b1096c4480011dd09b57a1cae 100644 (file)
--- a/doc/cephfs/index.rst
+++ b/doc/cephfs/index.rst
@@ -90,6 +90,7 @@ Administration
     CephFS Quotas <quota>
     Health messages <health-messages>
     Upgrading old file systems <upgrading>
+    CephFS Top Utility <cephfs-top>
 
 
 .. raw:: html