'\"macro stdmacro
.\"
.\" Copyright (c) 2016,2019 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PCP-NUMASTAT 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pcp-numastat\f1 \- report on NUMA memory allocation
.SH SYNOPSIS
\f3pcp\f1 [\f2pcp\ options\f1] \f3numastat\f1
[\fB\-mnV?\fR] [\fB\-w\fR \fIwidth\fR] [\fB\-p\fR [\fIprocess\fR ...]]
.SH DESCRIPTION
.B pcp-numastat
displays NUMA allocation statistics from the kernel memory
allocator.
Each process has NUMA policies that specify on which node
pages are allocated.
The performance counters in the kernel track on which
nodes memory is allocated and these values are sampled and
reported by
.BR pcp-numastat .
.PP
Counters are maintained individually for each NUMA node.
Details of the semantics of each reported metric can be
retrieved using the following command:
.P
.ft CR
.nf
.in +0.5i
# pminfo \(hydt mem.numa.alloc
.in
.fi
.SH OPTIONS
When invoked via the
.BR pcp (1)
command, the
.BR \-h /\c
.BR \-\-host ,
.BR \-a /\c
.BR \-\-archive ,
.BR \-O /\c
.BR \-\-origin ,
.BR \-Z /\c
.BR \-\-timezone
and several other
.I pcp options
become indirectly available; refer to
.BR PCPIntro (1)
for a complete description of these options.
.PP
The additional command line options available for
.B pcp-numastat
are:
.TP 5
\fB\-m\fR, \fB\-\-meminfo\fR
Display meminfo-like system-wide memory usage.
.TP
\fB\-n\fR, \fB\-\-numastat\fR
Display the numastat statistics info.
.TP
\fB\-p\fR, \fB\-\-process\fR
Display per-process NUMA memory usage from \fBproc.numa_maps\fR metrics.
Any trailing \fIprocess\fR operands are treated as process IDs (when the
operand is all digits) or regular expressions for command name matching.
Matching for command names is performed against the full command line
(as reported by \fBproc.psinfo.psargs\fR).
When a single process ID operand is provided and it matches exactly one
process, a detailed table of Hugepage, Heap, Stack and Private mappings is
shown (as in \fBnumastat \-p\fR). When multiple process ID operands are
provided, a per-process summary table is shown (also like
\fBnumastat \-p\fR) and may be split into multiple node column blocks
based on the available display width.
.PP
In the per-process view, node columns are always shown for all NUMA nodes
present on the system (as reported by PCP NUMA inventory metrics), even if
individual \fBproc.numa_maps\fR metric instances omit some nodes. Missing
per-process metrics are reported as zero.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display the current version of the command.
.TP
\fB\-w\fR \fIwidth\fR, \fB\-\-width\fR=\fIwidth\fR
Limit display to
.IR width .
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH NOTES
.B pcp-numastat
is inspired by the
.BR numastat (1)
command and produces the same output for the system-wide views. The
per-process view (\fB\-p\fR) follows the \fBnumastat \-p\fR layout.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.PP
For environment variables affecting PCP tools, see \fBpmGetOptions\fP(3).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pcp (1)
and
.BR numastat (1).

.\" control lines for scripts/man-spell
.\" +ok+ numastat {from pcp-numastat} NUMA