zfsdist(8)

🦋 zfsdist(8) 🦋

System Manager's Manual 💜

✨ NAME ✨

zfsdist — summarize ZFS operation latency 💖 It uses Linux eBPF/bcc, so it's a Linux thing 🐧

🎀 SYNOPSIS 🎀

zfsdist [-h] [-T] [-m] [-p PID] [interval] [count]

💅 DESCRIPTION 💅

okay so zfsdist is literally the tool that tells you how long your ZFS file ops take 😭 It tracks the time (latency) spent in the common ones: reads, writes, opens, and syncs. Then it shows you the whole thing as a power-of-2 histogram 📊 It keeps that histogram in an in-kernel eBPF map, which is how it stays efficient ✨

It works by kernel dynamic tracing of the ZPL interface (ZFS POSIX Layer) 🔍 Heads up though: if that interface changes, the tool needs updates to match 🙈

This is meant for the ZFS on Linux project, which lives at http://zfsonlinux.org 🌸

Since this uses BPF, only the root user can use this tool. No root, no zfsdist, no cap 👑

🧚 REQUIREMENTS 🧚

You need CONFIG_BPF and bcc. Those are the must-haves 🫶

🌈 OPTIONS 🌈

• -h — the bestie move: prints the usage message 💜
• -T — skips the timestamps on the interval output 🕒🚫
• -m — shows everything in milliseconds instead of microseconds 🍓
• -p PID — only traces the one PID you name, so you can main-character a single process 👑

🦋 EXAMPLES 🦋

Trace ZFS operation time, and print a summary when you hit Ctrl-C ⭐

# zfsdist

Trace PID 181 only 🎯

# zfsdist -p 181

Print 1 second summaries, 10 times 🔁

# zfsdist 1 10

1 second summaries, printed in milliseconds ⏱️

# zfsdist -m 1

🍓 FIELDS 🍓

• msecs — the range of milliseconds for this bucket 💖
• usecs — the range of microseconds for this bucket 💜
• count — how many operations landed in that time range 🔢
• distribution — the ASCII picture of the distribution, drawn from the count column 📊

🙈 OVERHEAD 🙈

Real talk: this adds low-overhead instrumentation to these ZFS operations, and that includes reads and writes from the file system cache. Those can be super frequent (it totally depends on the workload, like 1M/sec 😳), and at that point the tool's overhead can start to show. So measure and quantify before you use it, bestie 🧐

🌸 SOURCE 🌸

This comes from bcc 🐝

https://github.com/iovisor/bcc

Also check out the bcc distribution for a companion _examples.txt file, which has example usage, output, and commentary for this tool 📚

🐧 OS 🐧

Linux, obviously 💅

🧪 STABILITY 🧪

Unstable, still in development. Use with a little caution 🙈

💜 AUTHOR 💜

Brendan Gregg 👑

🔗 SEE ALSO 🔗

• zfssnoop(8) 🦋

---

ok that's the whole tea 🫶 Manual page: zfsdist(8) from the USER COMMANDS section, dated 2016-02-12 🎀 Stay iconic, bestie 💖✨