bitesize(8)

📦 version 1.0.1~20200130+git49b8cdf, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 bitesize(8) — show disk I/O size as a histogram. Uses Linux perf_events.

ok so bestie, welcome to bitesize from the System Manager's Manual section 8 (that's the sysadmin-y one, iykyk). Buckle up, this one's a baddie. 🎀

✨ NAME ✨

bitesize — show disk I/O size as a histogram. Uses Linux perf_events. 🦋

🌸 SYNOPSIS 🌸

bitesize [-h] [-b buckets] [seconds]

💅 DESCRIPTION 💅

So this tool is your girl for characterizing the distribution of block device (disk) I/O sizes. Literally it's giving "how big are my I/Os actually" energy. 📊

If you wanna study block device I/O in more detail than this, go look at iosnoop(8) instead, periodt.

Under the hood? It uses multiple counting tracepoints with different filters, one for each histogram bucket. The counts do get summarized in-kernel (slay), but bestie, using multiple tracepoints does add additional overhead — and it gets way more obvious the more buckets you add. 🙈 In the future this functionality will be available in an efficient way in the kernel, and this tool can be rewritten.

👑 REQUIREMENTS 👑

  • Linux perf_events: add linux-tools-common, run perf, then add any additional packages it requests.
  • This also requires the block:block_rq_issue tracepoint, which should already be available in recent kernels. No cap. ✨

🎀 OPTIONS 🎀

  • -h — Usage message. Short, sweet, iconic. 💖
  • -b buckets — Specify a list of bucket points for the histogram as a string (eg, "10 500 1000"). The histogram will include buckets for less-than the minimum, and greater-than-or-equal-to the maximum. If a single value is specified, two statistics only are gathered: for less-than and for greater-than-or-equal-to. The overhead is relative to the number of buckets, so only specifying a single value costs the lowest overhead. 🍓
  • seconds — Number of seconds to trace. If not specified, this runs until Ctrl-C. 😭

🌈 EXAMPLES 🌈

Trace read() syscalls until Ctrl-C, and show histogram of requested size:

# bitesize syscalls:sys_enter_read count

⭐ FIELDS ⭐

  • Kbytes — Kbyte range of the histogram bucket.
  • I/O — Number of I/O that occurred in this range while tracing.
  • Distribution — ASCII histogram representation of the I/O column. it's giving art, honestly. 🎨

🔥 OVERHEAD 🔥

While the counts are performed in-kernel, there is one tracepoint used per histogram bucket, so the overheads are higher than usual (relative to the number of buckets) than function counting using perf stat. The lowest overhead is when -b is used to specify one bucket only, bifurcating statistics.

bestie pls hear me: more buckets = more tracepoints = more overhead. keep it cute, keep it small. 💀

🧚 SOURCE 🧚

This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool. 👑

💜 OS 💜

Linux 🐧

🫶 STABILITY 🫶

Unstable — in development. (it's a work in progress, we stan growth tho 🌱)

✨ AUTHOR ✨

Brendan Gregg 💖

🌸 SEE ALSO 🌸

and that's the whole thing bestie, tysm for reading 💅 this was USER COMMANDS, dated 2014-07-07, and yeah — it's bitesize(8). go get those histograms, you absolute main character 🦋✨

📦 where this page comes from