biolatpcts(8)

✨ NAME ✨

biolatpcts 💖 is the tool that monitors the IO latency distribution of a block device. It's the biolatpcts(8) manual page, so you know it's serious 💅

---

🎀 SYNOPSIS 🎀

biolatpcts [-h] [-i INTERVAL] [-w which] [-p PCT,...] [-j] [-v] DEV

---

🦋 DESCRIPTION 🦋

okay so bestie, biolatpcts watches block device I/O (aka disk I/O) on the device you point it at 👀 and then works out the completion latency percentiles for each IO type, over and over, while you watch. it's giving data scientist, ngl 🧚

here's what it looks like in action:

# biolatpcts /dev/nvme0n1
nvme0n1    p1    p5   p10   p16   p25   p50   p75   p84   p90   p95
p99  p100
 read     95us 175us 305us 515us 895us 985us 995us 1.5ms 2.5ms 3.5ms
4.5ms  10ms
 write     5us   5us   5us  15us  25us 135us 765us 855us 885us 895us
965us 1.5ms
 discard   5us   5us   5us   5us 135us 145us 165us 205us 385us 875us
1.5ms 2.5ms
 flush     5us   5us   5us   5us   5us   5us   5us   5us   5us 1.5ms
4.5ms 5.5ms
 [...]

by default it prints a set of pre-set latency percentiles in a neat table every three seconds 🌸 you can change how often with the -i option.

the latency is measured from issue to the device until completion 🫶 if you want to start the clock somewhere else, use the -w option.

you can ask for any number of percentiles with the -p option ✨ whatever string you type is used exactly as typed in the output, so machines can parse it without any drama.

the -j option turns on json output, and each interval gets printed on a single line 💜

quick tea: this tool works by tracing blk_account_io_done() with kprobe and dropping the completion latencies into percpu arrays 🔥 it might need updating if that function changes, so keep that in mind, bestie.

⚠️ Since this uses BPF, only the root user can use this tool. no sneaking in as a normal user 🙈

---

🌈 REQUIREMENTS 🌈

You'll need CONFIG_BPF, CONFIG_KPROBES and bcc. no cap, these are non-negotiable 💀

---

👑 OPTIONS 👑

• -h — prints the usage message 📝
• -i INTERVAL, --interval INTERVAL — how often the report shows up ⏰ (default: 3)
• -w {from-rq-alloc,after-rq-alloc,on-device}, --which {from-rq-alloc,after-rq-alloc,on-device} — picks which latency gets measured 🎯 (default: on-device)
• -p PCT,..., --pcts PCT,... — the percentiles you want calculated 💅 (default: 1,5,10,16,25,50,75,84,90,95,99,100)
• -j, --json — outputs in json 🧾
• -v, --verbose — turns on debug output 🐛
• DEV — the target block device 💜 it can be /dev/DEVNAME, DEVNAME or MAJ:MIN

---

🍓 EXAMPLES 🍓

Print sda's I/O latency percentiles every second 🫧

# biolatpcts -i 1 sda

Print nvme0n1's all-9 I/O latency percentiles in json every second. the "all-9" squad is ✨ iconic ✨

# biolatpcts -p 99,99.9,99.99,99.999 -j -i 1 /dev/nvme0n1

---

🧚 OVERHEAD 🧚

not gonna lie, this one is actually chill 🫶 it traces kernel functions and keeps per-cpu latency buckets in the kernel, which then get copied to user-space asynchronously. this method is very efficient, and for most storage I/O rates the overhead should be negligible. but if you have an extremely high IOPS storage device, test and quantify the overhead before you use it 🙈

---

🔗 SOURCE 🔗

this is from bcc 💖

https://github.com/iovisor/bcc

also check the bcc distribution for a companion _examples.txt file with example usage, output, and commentary for this tool 📚

---

🌸 OS 🌸

Linux 🐧

---

🧪 STABILITY 🧪

Unstable, it's still in development 🚧

---

💜 AUTHOR 💜

Tejun Heo ✨

---

🦋 SEE ALSO 🦋

biolatency(8), biosnoop(8) 👀

---

Bestie, that's the whole page 🎀 biolatpcts(8) from the USER COMMANDS section, dated 2020-04-17, with the bcc source vibes 💅 Stay curious and keep your percentiles spicy 🌈💖