biostacks.bt(8)

📦 version 0.17.0, in debian bookworm

💅 biostacks.bt — bestie edition 💅

okay so this is biostacks.bt, and it lives in section 8 of the System Manager's Manual (you know, the whole System Manager's Manual vibe). sit down, grab a lil snack, we're doing eBPF 🧚

✨ NAME ✨

biostacks — show disk I/O latency with initialization stacks. it uses bpftrace/eBPF. no cap 💖

🎀 SYNOPSIS 🎀

biostacks

that's it. that's the whole thing. iconic.

🦋 DESCRIPTION 🦋

okay so what this tool DOES is it shows you disk I/O latency histograms, one for each block I/O initialization path. why do we care?? because it can reveal the reason for different latencies — like some of them are caused by log flushing, others by application reads, etc. so you're not just staring at a number like "hm latency" you're like "oh THAT'S who did this" 😭

the way it works: it traces the blk_account_io_start() function, plus blk_start_request() or blk_mq_start_request(), using dynamic instrumentation. slay.

⚠️ okay important lore: Linux 5.0 removed the classic I/O scheduler, so the blk_start_request() probe can be removed from the tool (literally just delete it). also this tool may need other maintenance to keep working if these functions change in later kernels. so like… it's a bit of a high-maintenance queen, but we love her 💅

and because it uses BPF, only the root user can use this tool. sorry bestie, root only, no exceptions, that's just the rules 🫶

💖 REQUIREMENTS 💖

  • CONFIG_BPF
  • bpftrace

those two. that's the list. short and sweet, we love a low-effort prerequisite 🎀

🌸 EXAMPLES 🌸

trace disk I/O latency with initialization stacks:

# biostacks.bt

go off 👑

🌈 FIELDS 🌈

here's the vibe check on each column you're gonna see:

  • 0th — an initialization kernel stack trace (shown in "@[...]") gets printed before each I/O histogram. so every histogram comes with a lil backstory bestie 💅
  • 1st, 2nd — this is a range of I/O latency, in microseconds (shown in "[...)" set notation). two columns, one range, they're a package deal 🫶
  • 3rd — a column showing the count of I/O in this range. the receipts ✨
  • 4th — an ASCII histogram representing the count column. the lil bars. the aesthetic. obsessed 😭

🍓 OVERHEAD 🍓

ngl the rate of biostacks should be low (bounded by device IOPS), so the overhead of this tool is expected to be negligible. it's giving "barely there, doesn't text back, but in a good way" 💜

👑 SOURCE 👑

this tool originated from the book "BPF Performance Tools", published by Addison Wesley (2019):

http://www.brendangregg.com/bpf-performance-tools-book.html

see the book for more documentation on this tool 📖

this version is in the bpftrace repository:

https://github.com/iovisor/bpftrace

also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool. it's basically the director's commentary track, iykyk 🎬

⭐ OS ⭐

Linux 🐧

💀 STABILITY 💀

Unstable — in development. she's still growing, be patient with her 🙈

🫶 AUTHOR 🫶

Brendan Gregg — the main character, fr fr 👑

🔥 SEE ALSO 🔥

this whole page is part of the USER COMMANDS manual set, dated 2019-07-12, and it's the biostacks.bt(8) page, bestie. go trace some I/O, you absolute icon 💖✨🎀🦋🌸💅

📦 where this page comes from