biolatency.bt(8)

📦
version 0.27.0 · 3 versions
  • 0.27.0 · alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 0.14.0 · ubuntu jammy
  • 0.20.2 · ubuntu noble
, in alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ biolatency.bt(8) — NAME ✨

okay so biolatency.bt 🎀 is the manual page for the tool that measures block I/O latency as a histogram 📊, and it runs on bpftrace/eBPF 🐝 🔥. literally the vibe is "how long do my disk reads and writes take" and it's giving main character energy 💅

🦋 SYNOPSIS 🦋

biolatency.bt

just type that and go bestie 🫶

💖 DESCRIPTION 💖

okay so this tool summarizes the time (latency) spent in block device I/O (aka disk I/O) 💾 and shows it as a power-of-2 histogram 📊. ngl this is so useful because you get to study the whole distribution, including the modes and the outliers 👀. there are often two modes, one for device cache hits and one for cache misses, and this tool can show both 🙈 latency outliers get shown too, no cap ✨

the original tool, which is still kept around as "biolatency-kp.bt" 🌸, works by dynamic tracing of the blk_account*() kernel functions. the catch is it'll need updating to match any changes to those functions in future kernel versions 😭

the updated version uses tracepoints instead of kprobes 💜 so it's compatible with a wide range of kernel versions. that's the one you want, periodt 💅

since this uses BPF, only the root user can use this tool 👑 sorry bestie, no exceptions 🥺

🧚 REQUIREMENTS 🧚

you need CONFIG_BPF and bpftrace ✨

🍓 EXAMPLES 🍓

trace block device I/O (disk I/O) and print a latency histogram when you hit Ctrl-C 🎀:

# biolatency.bt

🌈 FIELDS 🌈

  • 1st, 2nd — this is a range of latency, in microseconds (shown in "[...)" set notation) 📏
  • 3rd — a column showing the count of operations in that range 🔢
  • 4th — an ASCII histogram representing the count column 🎨

🫧 OVERHEAD 🫧

block device I/O usually has a pretty low frequency (< 10,000/s), so the overhead for this tool is expected to be negligible 🥰 but for high IOPS storage systems, test and quantify before you use it 🧐

🦋 SOURCE 🦋

this is from bpftrace 💜

https://github.com/bpftrace/bpftrace

also look in the bpftrace distribution for a companion _examples.txt file 📖 with example usage, output, and commentary for this tool ✨

this is a bpftrace version of the bcc tool of the same name, and the bcc tool may provide more options and customizations 💅

https://github.com/iovisor/bcc

💻 OS 💻

Linux 🐧

🚧 STABILITY 🚧

Unstable — still in development 🛠️ so expect things to shift

🌸 AUTHOR 🌸

Brendan Gregg 👑

🔗 SEE ALSO 🔗

ok bestie that's the whole tea 🫶 biolatency.bt(8) from bpftrace, source & version 2018-09-13 under USER COMMANDS, the whole thing is giving iconic ✨💖

📦 where this page comes from