'\"macro stdmacro
.\"
.\" Copyright (c) 2017,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-MPSTAT 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pcp-mpstat\f1 \- Report CPU and interrupt related statistics.
.SH SYNOPSIS
.B pcp
[\f2pcp\ options\f1]
.B mpstat [ -A ] [ -u ] [ -V ] [ -I {
.B SUM | CPU | SCPU | ALL } ] [ -P {
.I cpu1,cpu2
.B [,...] | ON | ALL } ] [ -t
.I interval
.B ] [ -s
.I count
.B ] [ -a
.I archive
.B ] [ -? ]
.SH DESCRIPTION
.B pcp-mpstat
command writes to standard output activities for each available processor,
processor 0 being the first one.
If no activity/option has been selected, then the
default report is the CPU utilization (\f3-u\f1) report.
.PP
The
.I interval
parameter specifies the amount of time in seconds between each report.
The default is one second.
The value of
.I count
parameter determines the number of samples to be displayed.
The default is continous.
.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 \-s /\c
.BR \-\-samples ,
.BR \-t /\c
.BR \-\-interval ,
.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-mpstat
are:
.IP -A
This option is equivalent to specifying
.BR "-u -I ALL -P ALL"
.IP "-I { SUM | CPU | SCPU | ALL }"
Report interrupts statistics.
.br
With the
.B SUM
keyword, the
.B pcp-mpstat
command reports the total number of interrupts per processor.
The following values are displayed:
.PP
.B CPU
.RS
.RS
Processor number.
The keyword
.I all
indicates that statistics are calculated as averages among all
processors.
.RE

.B intr/s
.RS
Show the total number of interrupts received per second by
the CPU or CPUs.
.RE

With the
.B CPU
keyword, the number of each individual interrupt received per
second by the CPU or CPUs is displayed.
Interrupts are those under the kernel.percpu.interrupts metric tree.

With the
.B SCPU
keyword, the number of each individual software interrupt received per
second by the CPU or CPUs is displayed.
Software interrupts are those under the kernel.percpu.softirqs tree

The
.B ALL
keyword is equivalent to specifying all the keywords above and
therefore all the interrupts statistics are displayed.
.RE

.IP "-P { cpu1,cpu2[,...] | ON | ALL }"
Indicate the processor number for which statistics are to be reported.
.I cpu1 and cpu2
are the processor numbers.
A list of required processor numbers can be provided.
Note that processor 0 is the first processor.

The
.B ON
keyword indicates that statistics are to be reported for every
online processor, whereas the
.B ALL
keyword indicates that statistics are to be reported for all processors.
.IP -u
Report CPU utilization.
The following values are displayed:

.B CPU
.RS
.RS
Processor number.
The keyword
.I ALL
indicates that statistics are calculated as averages among all
processors.
.RE

.B %usr
.RS
Show the percentage of CPU utilization that occurred while
executing at the user level (application).
.RE

.B %nice
.RS
Show the percentage of CPU utilization that occurred while
executing at the user level with nice priority.
.RE

.B %sys
.RS
Show the percentage of CPU utilization that occurred while
executing at the system level (kernel).
Note that this does not
include time spent servicing hardware and software interrupts.
.RE

.B %iowait
.RS
Show the percentage of time that the CPU or CPUs were idle during which
the system had an outstanding disk I/O request.
.RE

.B %irq
.RS
Show the percentage of time spent by the CPU or CPUs to service hardware
interrupts.
.RE

.B %soft
.RS
Show the percentage of time spent by the CPU or CPUs to service software
interrupts.
.RE

.B %steal
.RS
Show the percentage of time spent in involuntary wait by the virtual CPU
or CPUs while the hypervisor was servicing another virtual processor.
.RE

.B %guest
.RS
Show the percentage of time spent by the CPU or CPUs to run a virtual
processor.
.RE

.B %gnice
.RS
Show the percentage of time spent by the CPU or CPUs to run a niced
guest.
.RE

.B %idle
.RS
Show the percentage of time that the CPU or CPUs were idle and the system
did not have an outstanding disk I/O request.
.RE

Note: On SMP machines a processor that does not have any activity at all
is a disabled (offline) processor.
.RE

.IP "-s \ N , --samples = N"
Set the number of samples to be displayed.
Since the first sample is used for the rate conversion of some of the metrics,
the total number of samples reported are one less that N.
Default is continous.

.IP "-t DELTA , --interval = DELTA"
Set the interval between two samples.
The default is one second.

.IP "-a  FILE , --archive = FILE "
Causes \f3pcp-mpstat\f1 to use the specified archive than connecting to PMCD.
The argument to \f3-a\f1 is a comma-separated list of names, each of which may
be the base name of an archive or the name of a directory containing one or more archives.

.IP "-V , --version"
Print version number then exit.

.IP "-? , --help"
Print usage message then exit.
.SH EXAMPLES
.B pcp-mpstat -t 2 -s 5
.RS
Display four reports of global statistics among all processors at two second intervals.
.RE
.PP
.B pcp mpstat -P ALL -t 2 -s 5
.RS
Display four reports of statistics for all processors at two second intervals.
.SH NOTES
.B pcp-mpstat
is inspired by the
.BR mpstat (1)
command and aims to be command line and output compatible with it.
.SH ENVIRONMENT
.BR TZ
and
.BR LC_TIME
environment variables can be used to override the default date display format for
.BR pcp-mpstat .
.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),
.BR mpstat(1),
.BR pmParseInterval (3),
.BR pmTraversePMNS (3)
and
.BR environ (7).