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] [-d DURATION]
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
35       -d DURATION
36              Total duration of trace in seconds.
37

EXAMPLES

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

FIELDS

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

OVERHEAD

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

SOURCE

108       This is from bcc.
109
110              https://github.com/iovisor/bcc
111
112       Also look in the bcc distribution for a  companion  _examples.txt  file
113       containing example usage, output, and commentary for this tool.
114

OS

116       Linux
117

STABILITY

119       Unstable - in development.
120

AUTHOR

122       Brendan Gregg
123