xfsdist.bt(8)

📦 version 0.17.0, in debian bookworm

✨ xfsdist.bt ✨

okay bestie, so this is xfsdist.bt, and it lives in the System Manager's Manual, section 8 (that's the big-girl user-commands section, iykyk). It's the XFS latency summarizer and honestly? it's giving observability queen 💅

🌸 NAME 🌸

xfsdist.bt — summarize XFS operation latency. Uses bpftrace/eBPF. periodt.

🦋 SYNOPSIS 🦋

xfsdist.bt

no flags, no args, no drama. she just runs.

💖 DESCRIPTION 💖

so this tool sums up the time (latency, bestie, we're talking latency) spent in the common XFS file operations: reads, writes, opens, and syncs. Then it presents all of that as a power-of-2 histogram, because why would you read a million individual numbers when a vibe-check histogram can show you the shape of it 🎀

and the way it does this is lowkey iconic: it uses an in-kernel eBPF map to store the histogram, because efficiency is the moment. ✨

ngl, this works by tracing the xfs_file_operations interface functions — so if those functions ever change, this tool will need updating to match them. not a bug, just a situationship with the kernel API. 🙈
also, since this uses BPF, only the root user can use this tool. sorry to the non-root girlies 😭

🧚 REQUIREMENTS 🧚

  • CONFIG_BPF
  • bpftrace

that's it. that's the list. slay.

🍓 EXAMPLES 🍓

Trace XFS operation time, and print a summary on Ctrl-C:

# xfsdist.bt

you run it, you watch, you hit Ctrl-C, she prints. chef's kiss 👑

💜 FIELDS 💜

  • 0th — the operation name (shown in "@[...]") is printed before each I/O histogram. it's the little label that tells you what you're looking at.
  • 1st, 2nd — this is a range of latency, in microseconds (shown in "[...)" set notation). so like, the bucket. the range. the whole vibe.
  • 3rd — a column showing the count of operations in this range. how many times did we land in this bucket, fr fr.
  • 4th — this is an ASCII histogram representing the count column. visual! bars! we love a graph that fits in your terminal 📊

🌈 OVERHEAD 🌈

okay so real talk: this adds low-overhead instrumentation to these XFS operations, including reads and writes from the file system cache.

but here's the thing — those cache reads and writes can be very frequent depending on the workload (like, 1M/sec frequent, bestie), and at that point the overhead of this tool may become noticeable. so please, measure and quantify before use. don't just yolo it into prod and act surprised 💀

👑 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. basically the director's cut. 🎬

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

https://github.com/iovisor/bcc

⭐ OS ⭐

Linux. obviously. 🐧

🎀 STABILITY 🎀

Unstable - in development.

she's a work in progress and she's thriving. treat her accordingly 🫶

💅 AUTHOR 💅

Brendan Gregg

🌸 SEE ALSO 🌸

and that's the whole page, bestie! this one came from USER COMMANDS and it's dated 2018-09-08, filed under xfsdist.bt(8). go trace something pretty ✨💖

📦 where this page comes from