.TH biolatency.bt 8  "2018-09-13" "USER COMMANDS"
.SH NAME
biolatency.bt \- Block I/O latency as a histogram. Uses bpftrace/eBPF.
.SH SYNOPSIS
.B biolatency.bt
.SH DESCRIPTION
This tool summarizes time (latency) spent in block device I/O (disk I/O)
as a power-of-2 histogram. This allows the distribution to be studied,
including modes and outliers. There are often two modes, one for device cache
hits and one for cache misses, which can be shown by this tool. Latency
outliers will also be shown.

The original tool, which is retained as "biolatency-kp.bt", currently
works by dynamic tracing of the blk_account*() kernel functions, which
will need updating to match any changes to these functions in future
kernels versions.

The updated version of the tool utilizes tracepoints instead of
kprobes so that it can be compatible with a wide range of kernel
versions.

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF and bpftrace.
.SH EXAMPLES
.TP
Trace block device I/O (disk I/O), and print a latency histogram on Ctrl-C:
#
.B biolatency.bt
.SH FIELDS
.TP
1st, 2nd
This is a range of latency, in microseconds (shown in "[...)" set notation).
.TP
3rd
A column showing the count of operations in this range.
.TP
4th
This is an ASCII histogram representing the count column.
.SH OVERHEAD
Since block device I/O usually has a relatively low frequency (< 10,000/s),
the overhead for this tool is expected to be negligible. For high IOPS storage
systems, test and quantify before use.
.SH SOURCE
This is from bpftrace.
.IP
https://github.com/iovisor/bpftrace
.PP
Also look in the bpftrace distribution for a companion _examples.txt file containing
example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool
may provide more options and customizations.
.IP
https://github.com/iovisor/bcc
.SH OS
Linux
.SH STABILITY
Unstable - in development.
.SH AUTHOR
Brendan Gregg
.SH SEE ALSO
biosnoop.bt(8)