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] [-e] [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  in‐
18       clude 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       -e     Show extension summary(total, average)
46
47       interval
48              Output interval, in seconds.
49
50       count  Number of outputs.
51

EXAMPLES

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

FIELDS

76       usecs  Microsecond range
77
78       msecs  Millisecond range
79
80       count  How many I/O fell into this range
81
82       distribution
83              An ASCII bar chart to visualize the distribution (count column)
84

OVERHEAD

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

SOURCE

93       This is from bcc.
94
95              https://github.com/iovisor/bcc
96
97       Also  look  in  the bcc distribution for a companion _examples.txt file
98       containing example usage, output, and commentary for this tool.
99

OS

101       Linux
102

STABILITY

104       Unstable - in development.
105

AUTHOR

107       Brendan Gregg
108