biolatency(8) System Manager's Manual biolatency(8)

# [NAME](#NAME)

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

# [SYNOPSIS](#SYNOPSIS)

**biolatency \[-h] \[-F] \[-T] \[-Q] \[-m] \[-D] \[-F] \[-e] \[-j] \[-d DISK] \[interval \[count]]**

# [DESCRIPTION](#DESCRIPTION)

biolatency traces block device I/O (disk I/O), and records the distribution of I/O latency (time). This is printed as a histogram either on Ctrl-C, or after a given interval in seconds.

The latency of disk I/O operations is measured from when requests are issued to the device up to completion. A -Q option can be used to include time queued in the kernel.

This tool uses in-kernel eBPF maps for storing timestamps and the histogram, for efficiency.

This works by tracing various kernel blk\_\*() functions using dynamic tracing, and will need updating to match any changes to these functions.

Since this uses BPF, only the root user can use this tool.

# [REQUIREMENTS](#REQUIREMENTS)

CONFIG\_BPF and bcc.

# [OPTIONS](#OPTIONS)

-h Print usage message.

[-T](#T)

Include timestamps on output.

[-m](#m)

Output histogram in milliseconds.

[-D](#D)

Print a histogram per disk device.

[-F](#F)

Print a histogram per set of I/O flags.

[-j](#j)

Print a histogram dictionary

[-e](#e)

Show extension summary(total, average)

[-d DISK](#d)

Trace this disk only

[interval](#interval)

Output interval, in seconds.

[count](#count)

Number of outputs.

# [EXAMPLES](#EXAMPLES)

[Summarize block device I/O latency as a histogram:](#Summarize)

\# **biolatency**

[Print 1 second summaries, 10 times:](#Print)

\# **biolatency 1 10**

[Print 1 second summaries, using milliseconds as units for the histogram, and](#Print~2)

include timestamps on output: # **biolatency -mT 1**

[Include OS queued time in I/O time:](#Include)

\# **biolatency -Q**

[Show a latency histogram for each disk device separately:](#Show)

\# **biolatency -D**

[Show a latency histogram in a dictionary format:](#Show~2)

\# **biolatency -j**

[Also show extension summary(total, average):](#Also)

\# **biolatency -e**

# [FIELDS](#FIELDS)

[usecs](#usecs)

Microsecond range

[msecs](#msecs)

Millisecond range

[count](#count~2)

How many I/O fell into this range

[distribution](#distribution)

An ASCII bar chart to visualize the distribution (count column)

# [OVERHEAD](#OVERHEAD)

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

# [SOURCE](#SOURCE)

This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion \_examples.txt file containing example usage, output, and commentary for this tool.

# [OS](#OS)

Linux

# [STABILITY](#STABILITY)

Unstable - in development.

# [AUTHOR](#AUTHOR)

Brendan Gregg, Rocky Xing

# [SEE ALSO](#SEE_ALSO)

[biosnoop(8)](/man/enterprise-packages/bcc/biosnoop.8)

2020-12-30 USER COMMANDS

---

Document: biolatency(8) from bcc 0.37.0-r2 (Chainguard OS)
Source: https://github.com/iovisor/bcc