| .TH compactsnoop 8 "2019-11-1" "USER COMMANDS" |
| .SH NAME |
| compactsnoop \- Trace compact zone events. Uses Linux eBPF/bcc. |
| .SH SYNOPSIS |
| .B compactsnoop [\-h] [\-T] [\-p PID] [\-d DURATION] [\-K] [\-e] |
| .SH DESCRIPTION |
| compactsnoop traces the compact zone events, showing which processes are |
| allocing pages with memory compaction. This can be useful for discovering |
| when compact_stall (/proc/vmstat) continues to increase, whether it is |
| caused by some critical processes or not. |
| |
| This works by tracing the compact zone events using raw_tracepoints and one |
| kretprobe. |
| |
| For the Centos 7.6 (3.10.x kernel), see the version under tools/old, which |
| uses an older memory compaction mechanism. |
| |
| Since this uses BPF, only the root user can use this tool. |
| .SH REQUIREMENTS |
| CONFIG_BPF and bcc. |
| .SH OPTIONS |
| .TP |
| \-h |
| Print usage message. |
| .TP |
| \-T |
| Include a timestamp column. |
| .TP |
| \-p PID |
| Trace this process ID only (filtered in-kernel). |
| .TP |
| \-d DURATION |
| Total duration of trace in seconds. |
| .TP |
| \-K |
| Output kernel stack trace |
| .TP |
| \-e |
| Show extended fields. |
| .SH EXAMPLES |
| .TP |
| Trace all compact zone events: |
| # |
| .B compactsnoop |
| .TP |
| Trace all compact zone events, for 10 seconds only: |
| # |
| .B compactsnoop -d 10 |
| .SH FIELDS |
| .TP |
| TIME(s) |
| Time of the call, in seconds. |
| .TP |
| COMM |
| Process name |
| .TP |
| PID |
| Process ID |
| .TP |
| NODE |
| Memory node |
| .TP |
| ZONE |
| Zone of the node (such as DMA, DMA32, NORMAL eg) |
| .TP |
| ORDER |
| Shows which order alloc cause memory compaction, -1 means all orders (eg: write |
| to /proc/sys/vm/compact_memory) |
| .TP |
| MODE |
| SYNC OR ASYNC |
| .TP |
| FRAGIDX (extra column) |
| The FRAGIDX is short for fragmentation index, which only makes sense if an |
| allocation of a requested size would fail. If that is true, the fragmentation |
| index indicates whether external fragmentation or a lack of memory was the |
| problem. The value can be used to determine if page reclaim or compaction |
| should be used. |
| .PP |
| .in +8n |
| Index is between 0 and 1 so return within 3 decimal places |
| .PP |
| .in +8n |
| 0 => allocation would fail due to lack of memory |
| .PP |
| .in +8n |
| 1 => allocation would fail due to fragmentation |
| .TP |
| MIN (extra column) |
| The min watermark of the zone |
| .TP |
| LOW (extra column) |
| The low watermark of the zone |
| .TP |
| HIGH (extra column) |
| The high watermark of the zone |
| .TP |
| FREE (extra column) |
| The nr_free_pages of the zone |
| .TP |
| LAT(ms) |
| compact zone's latency |
| .TP |
| STATUS |
| The compaction's result. |
| .PP |
| .in +8n |
| For (CentOS 7.6's kernel), the status include: |
| .PP |
| .in +8n |
| "skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or |
| direct reclaim was more suitable |
| .PP |
| .in +8n |
| "continue" (COMPACT_CONTINUE): compaction should continue to another pageblock |
| .PP |
| .in +8n |
| "partial" (COMPACT_PARTIAL): direct compaction partially compacted a zone and |
| there are suitable pages |
| .PP |
| .in +8n |
| "complete" (COMPACT_COMPLETE): The full zone was compacted |
| .PP |
| .in +8n |
| For (kernel 4.7 and above): |
| .PP |
| .in +8n |
| "not_suitable_zone" (COMPACT_NOT_SUITABLE_ZONE): For more detailed tracepoint |
| output - internal to compaction |
| .PP |
| .in +8n |
| "skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or |
| direct reclaim was more suitable |
| .PP |
| .in +8n |
| "deferred" (COMPACT_DEFERRED): compaction didn't start as it was deferred due |
| to past failures |
| .PP |
| .in +8n |
| "no_suitable_page" (COMPACT_NOT_SUITABLE_PAGE): For more detailed tracepoint |
| output - internal to compaction |
| .PP |
| .in +8n |
| "continue" (COMPACT_CONTINUE): compaction should continue to another pageblock |
| .PP |
| .in +8n |
| "complete" (COMPACT_COMPLETE): The full zone was compacted scanned but wasn't |
| successful to compact suitable pages. |
| .PP |
| .in +8n |
| "partial_skipped" (COMPACT_PARTIAL_SKIPPED): direct compaction has scanned part |
| of the zone but wasn't successful to compact suitable pages. |
| .PP |
| .in +8n |
| "contended" (COMPACT_CONTENDED): compaction terminated prematurely due to lock |
| contentions |
| .PP |
| .in +8n |
| "success" (COMPACT_SUCCESS): direct compaction terminated after concluding that |
| the allocation should now succeed |
| .PP |
| .in +8n |
| .SH OVERHEAD |
| This traces the kernel compact zone kprobe/kretprobe or raw_tracepoints and |
| prints output for each event. As the rate of this is generally expected to be |
| low (< 1000/s), the overhead is also expected to be negligible. |
| .SH SOURCE |
| This is from bcc. |
| .IP |
| https://github.com/iovisor/bcc |
| .PP |
| Also look in the bcc distribution for a companion _examples.txt file containing |
| example usage, output, and commentary for this tool. |
| .SH OS |
| Linux |
| .SH STABILITY |
| Unstable - in development. |
| .SH AUTHOR |
| Wenbo Zhang |
