biolatency(8)

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

biolatency is the manual page for biolatency, which summarizes block device I/O latency as a histogram 📊

💖 NAME 💖

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

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

okay so biolatency traces block device I/O (aka disk I/O) and records how the latency (time) is spread out across all those operations 🔍 The result gets printed as a histogram either when you hit Ctrl-C or after every interval you set, in seconds ⏱️

The latency of disk I/O is measured from the moment requests get issued to the device, all the way up to completion. If you want the time spent queued in the kernel counted too, that's what the -Q option is for 🫶

This tool keeps its timestamps and histogram in in-kernel eBPF maps, which is why it's so efficient 🧚

It works by tracing a bunch of kernel blk_*() functions using dynamic tracing. Heads up, though: if those functions ever change, the tool will need updating to match 🙈

Since this uses BPF, only the root user can use this tool. No exceptions, bestie 👑

🌸 REQUIREMENTS 🌸

CONFIG_BPF and bcc are needed 💜

✨ OPTIONS ✨

• -h — Pulls up the usage message 📖
• -T — Adds timestamps to the output ⏰
• -m — Shows the histogram in milliseconds instead 🍓
• -D — Prints a separate histogram for each disk device 💅
• -F — Prints a separate histogram for each set of I/O flags 🏳️‍🌈
• -j — Prints the histogram as a dictionary 🧚
• -e — Shows an extension summary with the total and the average 🔥
• -d DISK — Only traces this one disk 🎯
• interval — How often to output, in seconds ⏱️
• count — How many outputs you want 🔢

🌈 EXAMPLES 🌈

Summarize block device I/O latency as a histogram:

# biolatency

Print 1 second summaries, 10 times:

# biolatency 1 10

Print 1 second summaries, using milliseconds as units for the histogram, and include timestamps on output:

# biolatency -mT 1

Include OS queued time in I/O time:

# biolatency -Q

Show a latency histogram for each disk device separately:

# biolatency -D

Show a latency histogram in a dictionary format:

# biolatency -j

Also show extension summary (total, average):

# biolatency -e

📊 FIELDS 📊

• usecs — The microsecond range 🕐
• msecs — The millisecond range 🕑
• count — How many I/O fell into this range 🔢
• distribution — An ASCII bar chart that visualizes the distribution, based on the count column 📈

🧁 OVERHEAD 🧁

This tool traces kernel functions and keeps in-kernel timestamps and a histogram. Those get asynchronously copied over to user-space. It's super efficient, and for most storage I/O rates (under 10k IOPS) the overhead should be negligible 🌷 If you're in a higher IOPS storage environment, test and quantify the overhead before you use it, ngl 🙈

💫 SOURCE 💫

This is from bcc 🫧

https://github.com/iovisor/bcc

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

🖥️ OS 🖥️

Linux 🐧

🚧 STABILITY 🚧

Unstable - in development. Still cooking 🍳

👑 AUTHOR 👑

Brendan Gregg, Rocky Xing 🫶

🦋 SEE ALSO 🦋

biosnoop(8) 💜

---

Bestie, that's the whole page 💖 It's the USER COMMANDS manual, dated 2020-12-30, and it's biolatency(8) forever ✨🫶💅