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 the disk I/O is measured from the issue to the device to
17       its completion. A -Q option can be used to include time queued  in  the
18       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       interval
44              Output interval, in seconds.
45
46       count  Number of outputs.
47

EXAMPLES

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

FIELDS

66       usecs  Microsecond range
67
68       msecs  Millisecond range
69
70       count  How many I/O fell into this range
71
72       distribution
73              An ASCII bar chart to visualize the distribution (count column)
74

OVERHEAD

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

SOURCE

83       This is from bcc.
84
85              https://github.com/iovisor/bcc
86
87       Also  look  in  the bcc distribution for a companion _examples.txt file
88       containing example usage, output, and commentary for this tool.
89

OS

91       Linux
92

STABILITY

94       Unstable - in development.
95

AUTHOR

97       Brendan Gregg
98