bcc-btrfsslower(8)

1btrfsslower(8)              System Manager's Manual             btrfsslower(8)
2
3
4

NAME

6       btrfsslower - Trace slow btrfs file operations, with per-event details.
7

SYNOPSIS

9       btrfsslower [-h] [-j] [-p PID] [min_ms]
10

DESCRIPTION

12       This  tool  traces  common btrfs file operations: reads, writes, opens,
13       and syncs. It measures the time spent in these operations,  and  prints
14       details for each that exceeded a threshold.
15
16       WARNING: See the OVERHEAD section.
17
18       By default, a minimum millisecond threshold of 10 is used. If a thresh‐
19       old of 0 is used, all events are printed (warning: verbose).
20
21       Since this works by tracing the btrfs_file_operations  interface  func‐
22       tions, it will need updating to match any changes to these functions.
23
24       Since this uses BPF, only the root user can use this tool.
25

REQUIREMENTS

27       CONFIG_BPF and bcc.
28

OPTIONS

30       -p PID Trace this PID only.
31
32       min_ms Minimum  I/O  latency  (duration)  to  trace,  in  milliseconds.
33              Default is 10 ms.
34

EXAMPLES

36       Trace synchronous file reads and writes slower than 10 ms:
37              # btrfsslower
38
39       Trace slower than 1 ms:
40              # btrfsslower 1
41
42       Trace slower than 1 ms, and output just the fields in  parsable  format
43       (csv):
44              # btrfsslower -j 1
45
46       Trace all file reads and writes (warning: the output will be verbose):
47              # btrfsslower 0
48
49       Trace slower than 1 ms, for PID 181 only:
50              # btrfsslower -p 181 1
51

FIELDS

53       TIME(s)
54              Time of I/O completion since the first I/O seen, in seconds.
55
56       COMM   Process name.
57
58       PID    Process ID.
59
60       T      Type of operation. R == read, W == write, O == open, S == fsync.
61
62       OFF_KB File offset for the I/O, in Kbytes.
63
64       BYTES  Size of I/O, in bytes.
65
66       LAT(ms)
67              Latency  (duration)  of I/O, measured from when it was issued by
68              VFS to the filesystem, to when it completed. This time is inclu‐
69              sive  of  block  device I/O, file system CPU cycles, file system
70              locks, run queue latency, etc. It's a more accurate  measure  of
71              the latency suffered by applications performing file system I/O,
72              than to measure this down at the block device interface.
73
74       FILENAME
75              A cached kernel file name (comes from dentry->d_iname).
76
77       ENDTIME_us
78              Completion timestamp, microseconds (-j only).
79
80       OFFSET_b
81              File offset, bytes (-j only).
82
83       LATENCY_us
84              Latency (duration) of the I/O, in microseconds (-j only).
85

OVERHEAD

87       This adds low-overhead instrumentation to btrfs writes and  fsyncs,  as
88       well  as  all system reads and opens (due to the current implementation
89       of the btrfs_file_operations interface). Particularly,  all  reads  and
90       writes from the file system cache will incur extra overhead while trac‐
91       ing. Such reads and writes can be very frequent (depending on the work‐
92       load;  eg, 1M/sec), at which point the overhead of this tool may become
93       noticeable.  Measure and quantify before use. If this continues to be a
94       problem,  consider  switching to a tool that prints in-kernel summaries
95       only, such as btrfsdist(8).
96
97       Note that the overhead of this tool should be less than  fileslower(8),
98       as  this tool targets btrfs functions only, and not all file read/write
99       paths (which can include socket I/O).
100

SOURCE

102       This is from bcc.
103
104              https://github.com/iovisor/bcc
105
106       Also look in the bcc distribution for a  companion  _examples.txt  file
107       containing example usage, output, and commentary for this tool.
108

OS

110       Linux
111

STABILITY

113       Unstable - in development.
114

AUTHOR

116       Brendan Gregg
117