runqlen.bt(8)

📦 version 0.17.0, in debian bookworm

💖 runqlen.bt — bestie's guide to run queue length 💖

okay so this is runqlen.bt(8), a page from the System Manager's Manual, and it's literally about watching your CPU scheduler's run queue length as a histogram. it uses bpftrace/eBPF. iykyk. ✨

✨ NAME ✨

runqlen.bt — CPU scheduler run queue length as a histogram. Uses bpftrace/eBPF. 🎀

🦋 SYNOPSIS 🦋

runqlen.bt

🌸 DESCRIPTION 🌸

so like, this program summarizes your scheduler queue length as a histogram, and it can also show you run queue occupancy. the way it does that? it samples the run queue length on all CPUs at 99 Hertz. no cap. 💅

you'd use this tool to spot imbalances — for example, when processes are bound to CPUs and that's causing queueing, or when interrupt mappings are doing the exact same thing. it's giving "why is this CPU fighting for its life". 😭

since this uses BPF, only the root user can use this tool. periodt. 👑

⭐ REQUIREMENTS ⭐

CONFIG_BPF and bpftrace. that's it, that's the list. 🫶

🔥 EXAMPLES 🔥

trace CPU run queue length system wide, and it prints a histogram when you hit Ctrl-C:

# runqlen.bt

💜 FIELDS 💜

  • 1st, 2nd — the run queue length is shown in the first field (right after the [). 🌈
  • 3rd — a column showing the count of samples for that length. 🍓
  • 4th — this is the ASCII histogram representing the count column. iconic. ✨

🧚 OVERHEAD 🧚

it samples scheduler structs at 99 Hertz across all CPUs. relatively speaking that's a super low rate of events, so the overhead of this tool is expected to be near zero. we love an efficient queen. 👑

💖 SOURCE 💖

this is from bpftrace.

https://github.com/iovisor/bpftrace

also bestie, go look in the bpftrace distribution for a companion _examples.txt file — it's got example usage, output, and commentary for this tool. very much worth a read. 📖

this is a bpftrace version of the bcc tool of the same name. heads up though: the bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

🌈 OS 🌈

Linux. obviously. 💀

💅 STABILITY 💅

Unstable — in development. it's still growing, give it grace. 🙈

👑 AUTHOR 👑

Brendan Gregg

🌟 SEE ALSO 🌟

runqlat.bt(8), mpstat(1), pidstat(1), uptime(1)

and that's the whole vibe, bestie 🎀 — this lil page comes from the USER COMMANDS section, dated 2018-10-07, and you can find it hanging out as runqlen.bt(8). go forth and sample those run queues. slay. 💖✨

📦 where this page comes from