bcc-biolatency(8)

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

NAME

6       biolatency - Summarize block device I/O latency as a histogram.
7

SYNOPSIS

9       biolatency [-h] [-F] [-T] [-Q] [-m] [-D] [interval [count]]
10

DESCRIPTION

12       biolatency  traces block device I/O (disk I/O), and records the distri‐
13       bution of I/O latency (time). This is printed as a histogram either  on
14       Ctrl-C, or after a given interval in seconds.
15
16       The  latency  of disk I/O operations is measured from when requests are
17       issued to the device up to completion. A  -Q  option  can  be  used  to
18       include time queued in the kernel.
19
20       This  tool uses in-kernel eBPF maps for storing timestamps and the his‐
21       togram, for efficiency.
22
23       This works by tracing various kernel blk_*()  functions  using  dynamic
24       tracing,  and  will  need  updating to match any changes to these func‐
25       tions.
26
27       Since this uses BPF, only the root user can use this tool.
28

REQUIREMENTS

30       CONFIG_BPF and bcc.
31

OPTIONS

33       -h Print usage message.
34
35       -T     Include timestamps on output.
36
37       -m     Output histogram in milliseconds.
38
39       -D     Print a histogram per disk device.
40
41       -F     Print a histogram per set of I/O flags.
42
43       -j     Print a histogram dictionary
44
45       interval
46              Output interval, in seconds.
47
48       count  Number of outputs.
49

EXAMPLES

51       Summarize block device I/O latency as a histogram:
52              # biolatency
53
54       Print 1 second summaries, 10 times:
55              # biolatency 1 10
56
57       Print 1 second summaries, using milliseconds  as  units  for  the  his‐
58       togram, and
59              include timestamps on output: # biolatency -mT 1
60
61       Include OS queued time in I/O time:
62              # biolatency -Q
63
64       Show a latency histogram for each disk device separately:
65              # biolatency -D
66
67       Show a latency histogram in a dictionary format:
68              # biolatency -j
69

FIELDS

71       usecs  Microsecond range
72
73       msecs  Millisecond range
74
75       count  How many I/O fell into this range
76
77       distribution
78              An ASCII bar chart to visualize the distribution (count column)
79

OVERHEAD

81       This  traces  kernel functions and maintains in-kernel timestamps and a
82       histogram, which are asynchronously copied to user-space.  This  method
83       is  very  efficient, and the overhead for most storage I/O rates (< 10k
84       IOPS) should be negligible.  If you have a higher IOPS storage environ‐
85       ment, test and quantify the overhead before use.
86

SOURCE

88       This is from bcc.
89
90              https://github.com/iovisor/bcc
91
92       Also  look  in  the bcc distribution for a companion _examples.txt file
93       containing example usage, output, and commentary for this tool.
94

OS

96       Linux
97

STABILITY

99       Unstable - in development.
100

AUTHOR

102       Brendan Gregg
103