numastat(8)

💖 numastat(8) — Administration 💖

🎀 NAME 🎀

okay so numastat is the tool that shows you per-NUMA-node memory stats for processes AND the whole operating system 🧚 it's giving nerdy and I'm obsessed.

📜 SYNTAX 📜

numastat

numastat [-V]

numastat [<PID>|<pattern>...]

numastat [-c] [-m] [-n] [-p <PID>|<pattern>] [-s[<node>]] [-v] [-z]
[<PID>|<pattern>...]

🌸 DESCRIPTION 🌸

bestie, if you run numastat with no options or arguments at all, it shows you per-node NUMA hit and miss stats straight from the kernel memory allocator ✨ this default behavior is strictly compatible with the old long-standing numastat perl script written by Andi Kleen, so nothing gets weird. The default stats show per-node numbers (in units of pages of memory) across these categories:

• numa_hit — memory successfully allocated on this node like it was supposed to be 🫶
• numa_miss — memory allocated on this node even though the process preferred some other node 🙈 every numa_miss has a numa_foreign on another node.
• numa_foreign — memory meant for this node that actually got allocated somewhere else 💀 every numa_foreign has a numa_miss on another node.
• interleave_hit — interleaved memory successfully allocated on this node, as intended 🦋
• local_node — memory allocated on this node while a process was literally running on it 🏠
• other_node — memory allocated on this node while a process was running on some other node 🌍

ngl, any options or arguments you add will totally change both the content AND the format of the display 💅 specified options switch the display units to megabytes of memory and change a bunch of other behaviors, as described below.

Memory usage info reflects the resident pages on the system 👑

🎀 OPTIONS 🎀

• -c — minimizes the table width by dynamically shrinking the columns based on the data inside ✨ amounts of memory get rounded to the nearest megabyte (instead of the usual two decimal places). The column width and spacing can be a little unpredictable with this one, but the denser display is super useful on systems with lots of NUMA nodes 🫧
• -m — shows the meminfo-like system-wide memory usage info 🧠 it's a per-node breakdown similar to what you'd find in /proc/meminfo.
• -n — shows the original numastat stats info. It shows the same stuff as the default behavior, but the units are megabytes of memory and there are other formatting and layout changes compared to the original numastat 🎀
• -p <PID> or <pattern> — shows per-node memory allocation info for the PID or pattern you give it 🔍 if the argument is only digits, it's treated as a numerical PID. If it has any non-digit characters, it's treated as a text fragment to search for in process command lines. For example, numastat -p qemu will find and show info for processes with "qemu" in the command line. Any command line arguments left over after option processing are treated as additional <PID> or <pattern> process specifiers, so the -p flag is actually optional: numastat qemu is equivalent to numastat -p qemu 🧚‍♀️
• -s[<node>] — sorts the table data in descending order before displaying it, so the biggest memory hogs show up first 👑 with no <node> specified, the table gets sorted by the total column. If you add the optional <node>, the data gets sorted by that <node> column. Heads up: <node> has to come right after the -s with NO white space in between (e.g., numastat -s2) 🙏 and because -s can take an optional argument, it must ALWAYS be the last option character in a compound option string.

⚠️ main character warning: instead of numastat -msc (which probably won't work the way you expect), use numastat -mcs 😭

• -v — makes some reports more verbose 📣 for multiple processes, it shows detailed info for each process. Normally, when per-node info for multiple processes is displayed, only the total lines appear.
• -V — displays the numastat version info and exits 🏷️
• -z — skips displaying table rows and columns that are only zero values 🙅‍♀️ this can cut down a ton of boring zero data on systems with lots of NUMA nodes. Just know that if zero rows or columns still show up with this option, there's probably at least one value in there that's actually non-zero but got rounded to zero for display 🫠

🌈 NOTES 🌈

numastat tries to fold each table so it's easy to read in your output terminal 📱 a terminal width of 80 characters is assumed by default. When the resize command is available, numastat tries to dynamically figure out and fine-tune the output tty width based on resize output. If the output isn't going to a tty, super long lines can show up depending on how many NUMA nodes are present. In every case, you can explicitly set the output width with the NUMASTAT_WIDTH environment variable, like NUMASTAT_WIDTH=100 numastat. On systems with tons of NUMA nodes, numastat -c -z .... can be a lifesaver for trimming the displayed info down 🫶

🦋 ENVIRONMENT VARIABLES 🦋

• NUMASTAT_WIDTH — sets the output width explicitly 🎀

📁 FILES 📁

• /proc/*/numa_maps
• /sys/devices/system/node/node*/meminfo
• /sys/devices/system/node/node*/numastat

🍓 EXAMPLES 🍓

numastat -c -z -m -n
numastat -czs libvirt kvm qemu
watch -n1 numastat
watch -n1 --differences=cumulative numastat

👩‍💻 AUTHORS 👩‍💻

The original numastat perl script was written circa 2003 by Andi Kleen <andi.kleen@intel.com>. The current numastat program was written in 2012 by Bill Gray <bgray@redhat.com> 💜 it's compatible with the original by default, and it adds options to display per-node system memory usage and per-node process memory allocation. Iconic behavior, honestly.

🔗 SEE ALSO 🔗

numactl(8), set_mempolicy(2), numa(3) ✨

okay bestie, that's the whole numastat(8) tea 🫶 written by Bill Gray, version 1.0.0, numastat(8) manual page, periodt 💅🌸