This document is for a development version of Ceph.

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).


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": "", "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


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 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>

cephfs-top refreshes stats every second by default. To chose a different refresh interval use:

$ cephfs-top -d <seconds>

Interval should be greater or equal to 0.5 second. Fractional seconds are honoured.

Sample screenshot running cephfs-top with 2 clients:



As of now, cephfs-top does not reliably work with multiple Ceph Filesystems.