btrfsdist(8)

📦 version 0.35.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ btrfsdist(8) ✨

Okay bestie, let's talk about btrfsdist 💖, the tool that summarizes btrfs operation latency. It's giving "how long did that actually take" energy, and it uses Linux eBPF/bcc to do it 🔥.

🎀 NAME

btrfsdist — summarize btrfs operation latency. Uses Linux eBPF/bcc. 🦋

💅 SYNOPSIS

btrfsdist [-h] [-T] [-N] [-d] [interval] [count]

🌸 DESCRIPTION

okay so this tool tracks the time (latency) spent in common btrfs file operations: reads, writes, opens, and syncs 📖. It shows the results as a power-of-2 histogram, and it stores that histogram in an in-kernel eBPF map so it stays super efficient ✨.

Since this works by tracing the btrfs_file_operations interface functions, it will need updating to match any changes to these functions 🙈.

Only the root user can use this tool, because it uses BPF. Not me trying to run it as a regular user 💀.

📋 REQUIREMENTS

You need CONFIG_BPF and bcc 🧚.

⭐ OPTIONS

  • -h — print the usage message 💜.
  • -T — don't include timestamps on interval output 🌈.
  • -m — output in milliseconds ⏱️.
  • -p PID — trace this PID only 🎯.

🍓 EXAMPLES

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

# btrfsdist

Trace PID 181 only:

# btrfsdist -p 181

Print 1 second summaries, 10 times:

# btrfsdist 1 10

1 second summaries, printed in milliseconds:

# btrfsdist -m 1

🫶 FIELDS

  • msecs — range of milliseconds for this bucket 🕐.
  • usecs — range of microseconds for this bucket 🕑.
  • count — number of operations in this time range 🔢.
  • distribution — ASCII representation of the distribution (the count column) 📊.

🧚 OVERHEAD

Okay this one is important bestie 👀. This adds low-overhead instrumentation to btrfs writes and fsyncs, as well as all system reads and opens (because of how the current btrfs_file_operations interface is implemented). Reads and writes from the file system cache will take extra overhead while tracing. Those can be super frequent depending on the workload (like 1M/sec), and at that point the overhead of this tool may get noticeable. So measure and quantify before you use it, periodt 😭.

🌈 SOURCE

This is from bcc ✨.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool 📚.

🦋 OS

Linux 🐧.

🌙 STABILITY

Unstable, still in development 🚧.

👑 AUTHOR

Brendan Gregg 💜.

🔗 SEE ALSO

btrfsslower(8) 💫.

USER COMMANDS 2016-02-15 btrfsdist(8) — bye bestie, this manpage is a whole mood 🎀🫶💖

📦 where this page comes from