biolatency.bt(8)

📦 version 0.17.0, in debian bookworm

💅 biolatency.bt — bestie's guide to block I/O latency (manual page 8) 💅

okay so listen. this is the manual for biolatency.bt, and it's living in the System Manager's Manual, section 8 (that's the admin/commands girlies). come sit with me, we're gonna read this together and you're gonna get it. 🫶

✨ NAME ✨

biolatency.bt — block I/O latency as a histogram. and it uses bpftrace/eBPF, obviously. 💖

🌸 SYNOPSIS 🌸

biolatency.bt

that's it. no args. no flags. she simply is. minimal queen behavior. 👑

💫 DESCRIPTION 💫

so what this cutie does: she summarizes the time (latency) spent in block device I/O (that's disk I/O, bestie) and she hands it back to you as a power-of-2 histogram. why does that matter? because it lets you actually study the distribution — the modes, the outliers, all of it. the whole vibe check. 🔥

here's the tea tho: there are often two modes. one for device cache hits and one for cache misses. and this tool will show you both, which is lowkey iconic. latency outliers show up too, so nothing is hiding from you. 😭

quick honest moment: this tool currently works by dynamic tracing of the blk_account*() kernel functions. that means if future kernel versions change those functions, this needs updating to match. so it's giving "in a relationship with kernel internals" energy. 🙈

and the big one — since this uses BPF, only the root user can use this tool. no exceptions, no cap. 💀

🎀 REQUIREMENTS 🎀

  • CONFIG_BPF
  • bpftrace

both. you need both. periodt.

🦋 EXAMPLES 🦋

want to trace block device I/O (disk I/O, same thing bestie) and print a latency histogram on Ctrl-C? say less:

# biolatency.bt

that's the whole thing. hit it, let it vibe, then Ctrl-C and read your histogram. ✨

🌈 FIELDS 🌈

here's how to read the output columns, so you don't just stare at numbers like 👁️👄👁️

  • 1st, 2nd — this is a range of latency, in microseconds, shown in "[...)" set notation.
  • 3rd — a column showing the count of operations in this range.
  • 4th — this is an ASCII histogram representing the count column. (the little bars. the aesthetic. we love her.)

⭐ OVERHEAD ⭐

good news: block device I/O usually has a relatively low frequency (that's < 10,000/s), so the overhead for this tool is expected to be negligible. slay. 🫶

but for high IOPS storage systems? bestie, test and quantify before use. don't just rawdog it in prod. 🙈

💜 SOURCE 💜

this is from bpftrace.

https://github.com/iovisor/bpftrace

also — look in the bpftrace distribution for a companion _examples.txt file. it's got example usage, output, and commentary for this tool. like bonus content. director's cut. 🎬

oh and! this is a bpftrace version of the bcc tool of the same name. the bcc tool may provide more options and customizations, so if you want the deluxe edition:

https://github.com/iovisor/bcc

🧚 OS 🧚

Linux. that's the one. that's the girl. 🐧

🍓 STABILITY 🍓

Unstable - in development.

so like, she's growing. she's evolving. be nice to her and don't build your whole production empire on her without knowing that. 💅

👑 AUTHOR 👑

Brendan Gregg

(the blueprint. the original. we stan.) 💖

🌸 SEE ALSO 🌸

and that's the whole page, bestie!! you ate this. now go trace something. 🦋

this lil manual was brought to you by the USER COMMANDS section, dated 2018-09-13, and she lives at biolatency.bt(8). mwah. 💋

📦 where this page comes from