123 lines
3.4 KiB
Groff
123 lines
3.4 KiB
Groff
.TH btrfsslower 8 "2016-02-15" "USER COMMANDS"
|
|
.SH NAME
|
|
btrfsslower \- Trace slow btrfs file operations, with per-event details.
|
|
.SH SYNOPSIS
|
|
.B btrfsslower [\-h] [\-j] [\-p PID] [min_ms] [\-d DURATION]
|
|
.SH DESCRIPTION
|
|
This tool traces common btrfs file operations: reads, writes, opens, and
|
|
syncs. It measures the time spent in these operations, and prints details
|
|
for each that exceeded a threshold.
|
|
|
|
WARNING: See the OVERHEAD section.
|
|
|
|
By default, a minimum millisecond threshold of 10 is used. If a threshold of 0
|
|
is used, all events are printed (warning: verbose).
|
|
|
|
Since this works by tracing the btrfs_file_operations interface functions, it
|
|
will need updating to match any changes to these functions.
|
|
|
|
Since this uses BPF, only the root user can use this tool.
|
|
.SH REQUIREMENTS
|
|
CONFIG_BPF and bcc.
|
|
.SH OPTIONS
|
|
\-p PID
|
|
Trace this PID only.
|
|
.TP
|
|
min_ms
|
|
Minimum I/O latency (duration) to trace, in milliseconds. Default is 10 ms.
|
|
.TP
|
|
\-d DURATION
|
|
Total duration of trace in seconds.
|
|
.SH EXAMPLES
|
|
.TP
|
|
Trace synchronous file reads and writes slower than 10 ms:
|
|
#
|
|
.B btrfsslower
|
|
.TP
|
|
Trace slower than 1 ms:
|
|
#
|
|
.B btrfsslower 1
|
|
.TP
|
|
Trace slower than 1 ms, and output just the fields in parsable format (csv):
|
|
#
|
|
.B btrfsslower \-j 1
|
|
.TP
|
|
Trace all file reads and writes (warning: the output will be verbose):
|
|
#
|
|
.B btrfsslower 0
|
|
.TP
|
|
Trace slower than 1 ms, for PID 181 only:
|
|
#
|
|
.B btrfsslower \-p 181 1
|
|
.TP
|
|
Trace for 10 seconds only:
|
|
#
|
|
.B btrfsslower \-d 10
|
|
.SH FIELDS
|
|
.TP
|
|
TIME(s)
|
|
Time of I/O completion since the first I/O seen, in seconds.
|
|
.TP
|
|
COMM
|
|
Process name.
|
|
.TP
|
|
PID
|
|
Process ID.
|
|
.TP
|
|
T
|
|
Type of operation. R == read, W == write, O == open, S == fsync.
|
|
.TP
|
|
OFF_KB
|
|
File offset for the I/O, in Kbytes.
|
|
.TP
|
|
BYTES
|
|
Size of I/O, in bytes.
|
|
.TP
|
|
LAT(ms)
|
|
Latency (duration) of I/O, measured from when it was issued by VFS to the
|
|
filesystem, to when it completed. This time is inclusive of block device I/O,
|
|
file system CPU cycles, file system locks, run queue latency, etc. It's a more
|
|
accurate measure of the latency suffered by applications performing file
|
|
system I/O, than to measure this down at the block device interface.
|
|
.TP
|
|
FILENAME
|
|
A cached kernel file name (comes from dentry->d_name.name).
|
|
.TP
|
|
ENDTIME_us
|
|
Completion timestamp, microseconds (\-j only).
|
|
.TP
|
|
OFFSET_b
|
|
File offset, bytes (\-j only).
|
|
.TP
|
|
LATENCY_us
|
|
Latency (duration) of the I/O, in microseconds (\-j only).
|
|
.SH OVERHEAD
|
|
This adds low-overhead instrumentation to btrfs writes and fsyncs, as well
|
|
as all system reads and opens (due to the current implementation of the
|
|
btrfs_file_operations interface). Particularly, all reads and writes from
|
|
the file system cache will incur extra overhead while tracing. Such reads and
|
|
writes can be very frequent (depending on the workload; eg, 1M/sec), at which
|
|
point the overhead of this tool may become noticeable.
|
|
Measure and quantify before use. If this
|
|
continues to be a problem, consider switching to a tool that prints in-kernel
|
|
summaries only, such as btrfsdist(8).
|
|
.PP
|
|
Note that the overhead of this tool should be less than fileslower(8), as
|
|
this tool targets btrfs functions only, and not all file read/write paths
|
|
(which can include socket I/O).
|
|
.SH SOURCE
|
|
This is from bcc.
|
|
.IP
|
|
https://github.com/iovisor/bcc
|
|
.PP
|
|
Also look in the bcc distribution for a companion _examples.txt file containing
|
|
example usage, output, and commentary for this tool.
|
|
.SH OS
|
|
Linux
|
|
.SH STABILITY
|
|
Unstable - in development.
|
|
.SH AUTHOR
|
|
Brendan Gregg
|
|
.SH SEE ALSO
|
|
btrfsdist(8), biosnoop(8), funccount(8), fileslower(8)
|