wqlat(8)

🎀 wqlat (section 8 of the manual, bestie) 🎀

okay so real quick — the manual name is wqlat and it lives in the System Manager's Manual, section 8. slay. now let's get into it 💅

---

✨ NAME ✨

wqlat — summarizes kernel workqueue latency and shows it to you as a histogram. that's the whole vibe fr fr 🌸

---

✨ SYNOPSIS ✨

wqlat [-h] [-T] [-N] [-W] [-w WQNAME] [interval [count]]

---

✨ DESCRIPTION ✨

so wqlat traces work that's waiting on a workqueue, and it records the distribution of the work's queuing latency (that's time, bestie ⏱️). then it prints it out as a histogram — either when you hit Ctrl+C, or after however many seconds of interval you asked for.

this tool uses in-kernel eBPF maps for storing timestamps and the histogram, because efficiency is the moment and we're obsessed 🫶

it hooks into the workqueue:workqueue_queue_work and workqueue:workqueue_execute_start kernel tracepoints, which is a stable tracing mechanism — iconic behavior only 👑

⚠️ okay important caveat: BPF programs can only attach to tracepoints starting from Linux 4.7, so this tool can only support kernel 4.7 or later. no cap. older kernels need not apply 🙈

and since it uses BPF, only the root user can run this tool. sorry to the non-root girlies 😭

---

✨ REQUIREMENTS ✨

• CONFIG_BPF
• bcc

both or it's not happening 💀

---

✨ OPTIONS ✨

• -h — print the usage message. the classic "what does this even do" button 🧚
• -T — include timestamps on output. so you know when things happened ⏰
• -N — output the histogram in nanoseconds instead of the default units. tiny numbers, big energy ✨
• -W — print a histogram per workqueue. one chart per queue, main character energy for every single one 👑
• -w WQNAME — trace this workqueue only. laser focus, we love a specific queen 🎯
• interval — output interval, in seconds.
• count — number of outputs.

---

✨ EXAMPLES ✨

summarize kernel workqueue latency as a histogram:

# wqlat

print 1 second summaries, 10 times:

# wqlat 1 10

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

# wqlat -NT 1

print 1 second summaries, 10 times per workqueue:

# wqlat -W 1 10

print 1 second summaries for workqueue nvmet_tcp_wq:

# wqlat -w nvmet_tcp_wq 1

---

✨ FIELDS ✨

here's what all the columns mean, bestie 🍓

• usecs — microsecond range
• nsecs — nanosecond range
• count — how many works landed in this range
• distribution — an ASCII bar chart to visualize the distribution (that's the count column). it's giving graph, it's giving data viz, we stan 🌈

---

✨ OVERHEAD ✨

this traces kernel functions and maintains in-kernel timestamps and a histogram, which are asynchronously copied to user-space. this method is very efficient, and the overhead for most workqueue scheduling rates (under 100k) should be negligible. but if you've got a higher workqueue scheduling rate, please test and quantify the overhead before use — don't just rawdog it in prod, i'm begging 😭

---

✨ SOURCE ✨

this is from bcc.

https://github.com/iovisor/bcc

also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool. it's like the director's commentary track but for tracing 🎬

---

✨ OS ✨

Linux. that's it, that's the OS 💜

---

✨ STABILITY ✨

Unstable - in development. so like… she's still growing, be nice to her 🦋

---

✨ AUTHOR ✨

Ping Gan — thank you for your service, legend 🫶

---

✨ SEE ALSO ✨

• biolatency — the sibling, go say hi 💖

---

okay that's the whole page!! and for the sign-off: this bad girl is part of the USER COMMANDS set, dated 2024-01-29, and she answers to the name wqlat(8). periodt. 💅✨🎀