perf-stat-hist(8)

✨ perf-stat-hist(8) ✨

okay bestie, welcome to perf-stat-hist, a lil helper from the Linux System Manager's Manual crew 🫶. it's a histogram summarizer for tracepoint values and it runs on Linux perf_events, and honestly? it's giving "small script, huge brain" 💅

---

🌸 NAME 🌸

perf-stat-hist — histogram summary of tracepoint values. Uses Linux perf_events.

---

🎀 SYNOPSIS 🎀

perf-stat-hist [-h] [-b buckets|-P power] [-m max] tracepoint variable
               [seconds]

---

💖 DESCRIPTION 💖

so this is a proof-of-concept, and it's showing off in-kernel histograms built with Linux perf_events (aka the perf command, iykyk), specifically on older kernels where perf_events doesn't have this native capability yet. it's literally the "we have histograms at home" of perf 🔥

these histograms show the distribution of variable, which lets you study the details — multiple modes, outliers, all of it. main character data analysis energy ✨

the way it works: it uses multiple counting tracepoints with different filters, one for each histogram bucket. and yes, it's summarized in-kernel, but using that many tracepoints does add additional overhead 😭. hopefully in the future this functionality will be provided in an efficient way from perf_events itself, at which point this tool can be deleted or rewritten. manifesting 🙏

---

🦋 REQUIREMENTS 🦋

• Linux perf_events: add linux-tools-common, run perf, then add any additional packages it asks for.
• Also uses awk. no cap, it's awk-pilled.

---

💅 OPTIONS 💅

• -h — usage message. the "help me bestie" flag 🥺
• -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, only two statistics are gathered: for less-than, and for greater-than-or-equal-to. the overhead is relative to the number of buckets, so specifying a single value costs the lowest overhead. economical queen 👑
• -P power — power for power-of histogram. by default, a power-of-4 histogram is created. this and the -b option are exclusive — they do not share the aux cord 🚫
• -m max — max value for power-of histograms.
• tracepoint — tracepoint specification. eg, syscalls:sys_enter_read.
• variable — the tracepoint variable name to summarize. to see what's available, cat the format file under /sys/kernel/debug/tracing/events/*/*/format. go snoop, bestie 🔍
• 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:

# perf-stat-hist syscalls:sys_enter_read count

trace read() syscall completions until Ctrl-C, and show histogram of successful returned size:

# perf-stat-hist syscalls:sys_exit_read ret

trace read() return sizes for 10 seconds, showing histogram:

# perf-stat-hist syscalls:sys_exit_read ret 10

trace network transmits until Ctrl-C, and show histogram of packet size:

# perf-stat-hist net:net_dev_xmit len

trace read() return sizes, using a power-of-10 histogram:

perf-stat-hist -P 10 syscalls:sys_exit_read ret

trace read() return sizes, using a power-of-2 histogram, and a max of 1024:

perf-stat-hist -P 2 -m 1024 syscalls:sys_exit_read ret

trace read() return sizes, using the specified bucket points:

perf-stat-hist -b "10 50 100 5000" syscalls:sys_exit_read ret

trace read() return sizes, and bifurcate statistics by the value 10:

perf-stat-hist -b 10 syscalls:sys_exit_read ret

---

⭐ FIELDS ⭐

• Range — range of the histogram bucket, in units of the variable specified.
• Count — number of occurrences (tracepoint events) of the variable in this range.
• Distribution — ASCII histogram representation of the Count column. it's giving bar chart but make it terminal 📊

---

💀 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. so like… don't go feral with buckets unless you mean it 🫣

---

🧚 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. homework but cute 📚

---

🍓 OS 🍓

Linux 🐧

---

🙈 STABILITY 🙈

Unstable — in development. she's still growing, be patient 💜

---

👑 AUTHOR 👑

Brendan Gregg

---

💜 SEE ALSO 💜

perf(1)

---

okay that's the whole page, bestie — and a lil sign-off to match the footer: this one lives under the USER COMMANDS source section, dated 2014-07-07, filed as page perf-stat-hist(8) 🎀✨ no cap, go histogram something. periodt 💅