ceph/doc/cephfs/cephfs-top.rst

   1 .. _cephfs-top:
   2
   3 ==================
   4 CephFS Top Utility
   5 ==================
   6
   7 CephFS provides `top(1)` like utility to display various Ceph Filesystem metrics
   8 in realtime. `cephfs-top` is a curses based python script which makes use of `stats`
   9 plugin in Ceph Manager to fetch (and display) metrics.
  10
  11 Manager Plugin
  12 --------------
  13
  14 Ceph Filesystem clients periodically forward various metrics to Ceph Metadata Servers (MDS)
  15 which in turn get forwarded to Ceph Manager by MDS rank zero. Each active MDS forward its
  16 respective set of metrics to MDS rank zero. Metrics are aggregated and forwarded to Ceph
  17 Manager.
  18
  19 Metrics are divided into two categories - global and per-mds. Global metrics represent
  20 set of metrics for the filesystem as a whole (e.g., client read latency) whereas per-mds
  21 metrics are for a particular MDS rank (e.g., number of subtrees handled by an MDS).
  22
  23 .. note:: Currently, only global metrics are tracked.
  24
  25 `stats` plugin is disabled by default and should be enabled via::
  26
  27   $ ceph mgr module enable stats
  28
  29 Once enabled, Ceph Filesystem metrics can be fetched via::
  30
  31   $ ceph fs perf stats
  32   {"version": 1, "global_counters": ["cap_hit", "read_latency", "write_latency", "metadata_latency", "dentry_lease", "opened_files", "pinned_icaps", "opened_inodes", "avg_read_latency", "stdev_read_latency", "avg_write_latency", "stdev_write_latency", "avg_metadata_latency", "stdev_metadata_latency"], "counters": [], "client_metadata": {"client.324130": {"IP": "192.168.1.100", "hostname": "ceph-host1", "root": "/", "mount_point": "/mnt/cephfs", "valid_metrics": ["cap_hit", "read_latency", "write_latency", "metadata_latency", "dentry_lease, "opened_files", "pinned_icaps", "opened_inodes", "avg_read_latency", "stdev_read_latency", "avg_write_latency", "stdev_write_latency", "avg_metadata_latency", "stdev_metadata_latency"]}}, "global_metrics": {"client.324130": [[309785, 1280], [0, 0], [197, 519015022], [88, 279074768], [12, 70147], [0, 3], [3, 3], [0, 3], [0, 0], [0, 0], [0, 11699223], [0, 88245], [0, 6596951], [0, 9539]]}, "metrics": {"delayed_ranks": [], "mds.0": {"client.324130": []}}}
  33
  34 Details of the JSON command output are as follows:
  35
  36 - `version`: Version of stats output
  37 - `global_counters`: List of global performance metrics
  38 - `counters`: List of per-mds performance metrics
  39 - `client_metadata`: Ceph Filesystem client metadata
  40 - `global_metrics`: Global performance counters
  41 - `metrics`: Per-MDS performance counters (currently, empty) and delayed ranks
  42
  43 .. note:: `delayed_ranks` is the set of active MDS ranks that are reporting stale metrics.
  44           This can happen in cases such as (temporary) network issue between MDS rank zero
  45           and other active MDSs.
  46
  47 Metrics can be fetched for a partcilar client and/or for a set of active MDSs. To fetch metrics
  48 for a particular client (e.g., for client-id: 1234)::
  49
  50   $ ceph fs perf stats --client_id=1234
  51
  52 To fetch metrics only for a subset of active MDSs (e.g., MDS rank 1 and 2)::
  53
  54   $ ceph fs perf stats --mds_rank=1,2
  55
  56 `cephfs-top`
  57 ------------
  58
  59 `cephfs-top` utility relies on `stats` plugin to fetch performance metrics and display in
  60 `top(1)` like format. `cephfs-top` is available as part of `cephfs-top` package.
  61
  62 By default, `cephfs-top` uses `client.fstop` user to connect to a Ceph cluster::
  63
  64   $ ceph auth get-or-create client.fstop mon 'allow r' mds 'allow r' osd 'allow r' mgr 'allow r'
  65   $ cephfs-top
  66
  67 To use a non-default user (other than `client.fstop`) use::
  68
  69   $ cephfs-top --id <name>
  70
  71 By default, `cephfs-top` connects to cluster name `ceph`. To use a non-default cluster name::
  72
  73   $ cephfs-top --cluster <cluster>
  74
  75 `cephfs-top` refreshes stats every second by default. To choose a different refresh interval use::
  76
  77   $ cephfs-top -d <seconds>
  78
  79 Interval should be greater than or equal to 0.5 seconds. Fractional seconds are honoured.
  80
  81 Sample screenshot running `cephfs-top` with 2 clients:
  82
  83 .. image:: cephfs-top.png
  84
  85 .. note:: As of now, `cephfs-top` does not reliably work with multiple Ceph Filesystems.