compactsnoop(8)

✨ compactsnoop(8) ✨

okay bestie, welcome to your new fave little tool — it lives in the System Manager's Manual and its whole name is compactsnoop, section 8. Let's get into it 💅

---

🎀 NAME 🎀

compactsnoop — traces compact zone events. uses Linux eBPF/bcc, no cap.

🦋 SYNOPSIS 🦋

compactsnoop [-h] [-T] [-p PID] [-d DURATION] [-K] [-e]

🌸 DESCRIPTION 🌸

so basically compactsnoop traces the compact zone events and shows you which processes are allocing pages with memory compaction. it's genuinely so useful for figuring out when compact_stall (in /proc/vmstat) just keeps going up — and whether some critical process is the one causing it or not. iykyk.

the way it works: it traces the compact zone events using raw_tracepoints and one kretprobe. iconic.

for Centos 7.6 (3.10.x kernel), there's a version under tools/old — that one uses an older memory compaction mechanism. different vibe, same energy.

💀 real talk though: since this uses BPF, only the root user can use this tool. no exceptions, bestie.

🫶 REQUIREMENTS 🫶

• CONFIG_BPF
• bcc

that's it. that's the list.

✨ OPTIONS ✨

• -h — prints the usage message. the classic cry-for-help flag 🥺
• -T — adds a timestamp column. time is real.
• -p PID — trace this process ID only (and yes, it's filtered in-kernel, so it's giving efficient).
• -d DURATION — total duration of the trace, in seconds. clock it.
• -K — outputs the kernel stack trace. spicy.
• -e — shows the extended fields. more data, more fun.

🔥 EXAMPLES 🔥

trace all compact zone events:

# compactsnoop

trace all compact zone events, but for 10 seconds only:

# compactsnoop -d 10

👑 FIELDS 👑

• TIME(s) — time of the call, in seconds.
• COMM — process name.
• PID — process ID.
• NODE — memory node.
• ZONE — zone of the node (such as DMA, DMA32, NORMAL eg).
• ORDER — shows which order alloc caused memory compaction; -1 means all orders (eg: write to /proc/sys/vm/compact_memory).
• MODE — SYNC or ASYNC.
• FRAGIDX (extra column) — short for fragmentation index, which only makes sense if an allocation of a requested size would fail. if that's true, the fragmentation index tells you whether external fragmentation or a lack of memory was the problem. you can use the value to determine if page reclaim or compaction should be used. index is between 0 and 1 so it returns within 3 decimal places:
  • 0 => allocation would fail due to lack of memory
  • 1 => allocation would fail due to fragmentation
• MIN (extra column) — the min watermark of the zone.
• LOW (extra column) — the low watermark of the zone.
• HIGH (extra column) — the high watermark of the zone.
• FREE (extra column) — the nr_free_pages of the zone.
• LAT(ms) — compact zone's latency.
• STATUS — the compaction's result. and ooh, this one's got layers:

for (CentOS 7.6's kernel), the status includes:

• "skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or direct reclaim was more suitable
• "continue" (COMPACT_CONTINUE): compaction should continue to another pageblock
• "partial" (COMPACT_PARTIAL): direct compaction partially compacted a zone and there are suitable pages
• "complete" (COMPACT_COMPLETE): the full zone was compacted

for (kernel 4.7 and above):

• "not_suitable_zone" (COMPACT_NOT_SUITABLE_ZONE): for more detailed tracepoint output - internal to compaction
• "skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or direct reclaim was more suitable
• "deferred" (COMPACT_DEFERRED): compaction didn't start as it was deferred due to past failures
• "no_suitable_page" (COMPACT_NOT_SUITABLE_PAGE): for more detailed tracepoint output - internal to compaction
• "continue" (COMPACT_CONTINUE): compaction should continue to another pageblock
• "complete" (COMPACT_COMPLETE): the full zone was compacted scanned but wasn't successful to compact suitable pages
• "partial_skipped" (COMPACT_PARTIAL_SKIPPED): direct compaction has scanned part of the zone but wasn't successful to compact suitable pages
• "contended" (COMPACT_CONTENDED): compaction terminated prematurely due to lock contentions
• "success" (COMPACT_SUCCESS): direct compaction terminated after concluding that the allocation should now succeed

🧚 OVERHEAD 🧚

this traces the kernel compact zone kprobe/kretprobe or raw_tracepoints and prints output for each event. and because the rate of this is generally expected to be low (< 1000/s), the overhead is also expected to be negligible. so yeah, it's lightweight, it's not gonna eat your CPU, we love a low-maintenance queen 💖

⭐ SOURCE ⭐

this is from bcc.

https://github.com/iovisor/bcc

also like… look in the bcc distribution for a companion _examples.txt file — it's got example usage, output, and commentary for this tool. free bonus content, obsessed.

🌈 OS 🌈

Linux (obviously, bestie)

💜 STABILITY 💜

Unstable - in development. she's still growing, be nice to her 🥺

🍓 AUTHOR 🍓

Wenbo Zhang

---

and that's the whole page, mwah 💋 — this cutie came out of USER COMMANDS, dated 2019-11-1, and she answers to the name compactsnoop(8). go forth and trace, bestie 🌟