cpuunclaimed(8)

✨ NAME ✨

bestie, this is the System Manager's Manual page for cpuunclaimed(8) 🎀 It's a tool that samples CPU run queues and works out unclaimed idle CPU. It uses Linux eBPF/bcc, so it's giving low-level Linux tracing energy 💜

🦋 SYNOPSIS 🦋

cpuunclaimed [-T] [-j] [-J] [interval [count]]

💖 DESCRIPTION 💖

okay so this tool samples the length of the run queues and figures out when there are idle CPUs 👀 but there are also threads queued up waiting for their turn. That's the real tea ☕ It reports the leftover idle CPU (the stuff that isn't being claimed by waiting threads) as a system-wide percentage.

This can happen for a few reasons, and they're kinda iconic 😭

• An application got bound to some CPUs but not all of them, so its runnable threads can't hop over to the other CPUs because of that setup 🙈
• CPU affinity 🧚 This is an optimization that keeps threads on the CPUs where the caches are still warm, even if that means a short wait while other CPUs sit idle. The wait period is tunable (see sysctl, kernel.sched*) ✨
• Scheduler bugs 💀

Here's the vibe check: an unclaimed idle below 1% is probably CPU affinity, and honestly not usually something to stress about 💅 Leaving the CPU idle can even improve overall system throughput. This tool is best at spotting the bigger issues, like anything above 2%, because its samples only fire at 99 Hertz so it's kinda coarse 🌸

This tool is experimental 🧪 It works by sampling to keep overhead low, and it leans on a few assumptions:

• CPU samples consistently fire around the same offset 🕰️ Sometimes there's a lag because higher-priority interrupts delay a sample, but the later samples are expected to catch back up to the expected offsets (and that's what happens in practice). You can use -J to inspect sample offsets. Some systems power down CPUs when idle, and when those CPUs wake up they may start firing at a skewed offset. When that happens this tool detects the skew, prints an error, and exits 😭
• All CPUs are online (see ncpu) 🌈

If it flags unclaimed CPU, you can double-check by dumping the raw samples with -j, and you can also use other tracing tools to instrument scheduler events. Heads up though, that second approach has way higher overhead 👀

Since this uses BPF, only the root user can run this tool. No exceptions, bestie 🔥

🎀 REQUIREMENTS 🎀

You'll need CONFIG_BPF and bcc 💜

🍓 EXAMPLES 🍓

Sample and calculate unclaimed idle CPUs, output every 1 second (default:

# cpuunclaimed

Print 5 second summaries, 10 times:

# cpuunclaimed 5 10

Print 1 second summaries with timestamps:

# cpuunclaimed -T 1

Raw dump of all samples (verbose), as comma-separated values:

# cpuunclaimed -j

🌷 FIELDS 🌷

• %CPU — CPU utilization as a system-wide percentage ✨
• unclaimed idle — the percentage of CPU resources that were idle while work was queued up on other CPUs, as a system-wide percentage 👀
• TIME — the time, formatted as HH:MM:SS ⏰
• TIMESTAMP_ns — the timestamp, in nanoseconds 💫
• CPU# — the CPU ID 🦋
• OFFSET_ns_CPU# — the time offset at which a sample fired within a sample group for this CPU 🧚

🫶 OVERHEAD 🫶

The overhead is expected to be low, basically negligible 🥹 This tool samples at 99 Hertz on all CPUs, which has a fixed and small cost. Other approaches sample every scheduler event instead, and that can mean instrumenting millions of events per second, which is a whole mood 💀 Sampled CPUs, run queue lengths, and timestamps get written to ring buffers, and user space reads them periodically for reporting. Still, measure the overhead in a test environment first, no shortcuts 🙈

🌈 SOURCE 🌈

This comes from bcc 💖

• https://github.com/iovisor/bcc

There's also a companion _examples.txt file in the bcc distribution with example usage, output, and commentary for this tool, so go check that out too 📚

💜 OS 💜

Linux 🐧

🧪 STABILITY 🧪

Unstable, it's still in development 🚧

👑 AUTHOR 👑

Brendan Gregg, the legend himself ✨

🔗 SEE ALSO 🔗

• runqlen(8) 🌸

---

Till next time, bestie 🦋 That's the USER COMMANDS manual, dated 2016-12-21, for cpuunclaimed(8) 💅✨