cpudist(8)

✨ cpudist(8) ✨

System Manager's Manual 💅

🌸 NAME 🌸

cpudist — on- and off-CPU task time, served as a histogram 📊

🎀 SYNOPSIS 🎀

cpudist [-h] [-O] [-T] [-m] [-P] [-L] [-p PID] [-I] [-e] [interval]
[count]

💖 DESCRIPTION 💖

okay so this bad boy measures how long a task stays on the CPU before it gets descheduled, then shows you the times as a histogram 📊 tasks that only last a super short time on the CPU can be a sign of excessive context-switches and poor workload distribution 😭 it might even point to a shared source of contention that keeps tasks switching in and out as stuff becomes available, like a mutex 🔒

it can also measure how long a task spends off-CPU before it gets scheduled again ✨ this is lowkey so helpful for spotting long blocking and I/O operations, or on the flip side, super short descheduling times caused by short-lived locks or timers 🧚

by default CPU idle time is excluded, and it's giving simple: it just excludes PID 0 🙈

this tool uses in-kernel eBPF maps to store the timestamps and the histogram, which is very efficient 🦋 but ngl the overhead can get significant for some workloads, so check out the OVERHEAD section 👀

⚠️ since this runs on BPF, only the root user can use this tool. no cap, it's root-only 👑

🌈 REQUIREMENTS 🌈

CONFIG_BPF and bcc. ✨

🦋 OPTIONS 🦋

• -h — pull up the usage message 📖
• -O — measure off-CPU time instead of on-CPU time 🌙
• -T — slap timestamps onto the output ⏰
• -m — show the histogram in milliseconds instead 🍓
• -P — get a histogram for each PID (tgid from the kernel's perspective) 🧚
• -L — get a histogram for each TID (pid from the kernel's perspective) 💜
• -p PID — only show this PID (filtered in kernel, so it's efficient) 🎯
• -I — include CPU idle time (by default these get excluded) ☕
• -e — show the extension summary (average/total/count) 📈
• interval — how many seconds between outputs ⏳
• count — how many outputs you want 🔢

🍓 EXAMPLES 🍓

Summarize task on-CPU time as a histogram:

# cpudist

Summarize task off-CPU time as a histogram:

# cpudist -O

Print 1 second summaries, 10 times:

# cpudist 1 10

Print 1 second summaries, using milliseconds as units for the histogram, and include timestamps on output:

# cpudist -mT 1

Trace PID 185 only, 1 second summaries:

# cpudist -p 185 1

Include CPU idle time:

# cpudist -I

Also show extension summary:

# cpudist -e

🫶 FIELDS 🫶

• usecs — the microsecond range 🕐
• msecs — the millisecond range ⏱️
• count — how many times a task event landed in this range 🎯
• distribution — an ASCII bar chart showing the distribution (count column) 📊

🔥 OVERHEAD 🔥

this traces scheduler tracepoints, and those can get super frequent 😭 eBPF has very low overhead and this tool uses in-kernel maps to stay efficient, but for some workloads the scheduler events can be frequent enough that the overhead becomes significant 💀 measure it in a lab environment to quantify the overhead before you use it in the wild 🧪

🌷 SOURCE 🌷

this is from bcc 💖

https://github.com/iovisor/bcc

also look in the bcc distribution for a companion _example.txt file with example usage, output, and commentary for this tool 📚

🌙 OS 🌙

Linux 🐧

⭐ STABILITY ⭐

Unstable - in development. 🚧

👑 AUTHOR 👑

Sasha Goldshtein, Rocky Xing 🫶

🦋 SEE ALSO 🦋

pidstat(1), runqlat(8) ✨

---

bestie, that's the whole tea 🫖 this page was from the USER COMMANDS section, dated 2016-06-28, and it's all about cpudist(8) 🎀💜