NAME
pmstat - high-level system performance overview
SYNOPSIS
pmstat [-gLlPxz] [-A align] [-a archive] [-h host] [-H file] [-n
pmnsfile] [-O offset] [-p port] [-S starttime] [-s samples] [-T
endtime] [-t interval] [-Z timezone]
DESCRIPTION
pmstat provides a one line summary of system performance every interval
unit of time (the default is 5 seconds). pmstat is intended to monitor
system performance at the highest level, after which other tools may be
used to examine subsystems in which potential performance problems may
be observed in greater detail.
Multiple hosts may be monitored by supplying more than one host with
multiple -h flags (for live monitoring) or by providing a name of the
hostlist file, where each line contain one host name, with -H, or
multiple -a flags (for retrospective monitoring from an archive).
The -t option may be used to change the default reporting interval.
The interval argument follows the syntax described in PCPIntro(1), and
in the simplest form may be an unsigned integer (the implied units in
this case are seconds).
By default, pmstat fetches metrics by connecting to the Performance
Metrics Collector Daemon (PMCD) on the local host. If the -L option is
specified, then pmcd(1) is bypassed, and metrics are fetched from PMDAs
on the local host using the standalone PM_CONTEXT_LOCAL variant of
pmNewContext(3). When the -h option is specified, pmstat connects to
the pmcd(1) on host and fetches metrics from there. As mentioned
above, multiple hosts may be monitored by supplying multiple -h flags.
Alternatively, if the -a option is used, the metrics are retrieved from
the Performance Co-Pilot archive log files identified by the base name
archive. Multiple archives may be replayed by supplying multiple -a
flags. When the -a flag is used, the -P flag may also be used to pause
the output after each interval.
Standalone mode can only connect to the local host, using an archive
implies a host name, and nominating a host precludes using an archive,
so the options -L, -a and -h are mutually exclusive.
Normally pmstat operates on the default Performance Metrics Name Space
(PMNS), however if the -n option is specified an alternative namespace
is loaded from the file pmnsfile.
If the -s the option is specified, samples defines the number of
samples to be retrieved and reported. If samples is 0 or -s is not
specified, pmstat will sample and report continuously - this is the
default behavior.
When processing an archive, pmstat may relinquish its own timing
control, and operate as a ‘‘slave’’ of a pmtime(1) process that uses a
GUI dialog to provide timing control. In this case, either the -g
option should be used to start pmstat as the sole slave of a new
pmtime(1) instance, or -p should be used to attach pmstat to an
existing pmtime(1) instance via the IPC channel identified by the port
argument.
The -S, -T, -O and -A options may be used to define a time window to
restrict the samples retrieved, set an initial origin within the time
window, or specify a ‘‘natural’’ alignment of the sample times; refer
to PCPIntro(1) for a complete description of these options.
The -l option prints the last 7 characters of a hostname in summaries
involving more than one host (when more than one -h option has been
specified on the command line).
The -x option (extended CPU metrics) causes two additional CPU metrics
to be reported, namely wait for I/O ("wa") and virtualisation steal
time ("st").
The output from pmstat is directed to standard output, and the columns
in the report are interpreted as follows:
loadavg The 1 minute load average.
memory The swpd column indicates average swap space used during the
interval, in Kbytes. The free column indicates average free
memory during the interval, in Kbytes. The buff column
indicates average buffer memory in use during the interval,
in Kbytes. The cache column indicates average cached memory
in use during the interval, in Kbytes.
If the values become large, they are reported as Mbytes (m
suffix) or Gbytes (g suffix).
swap The metrics in this area of the kernel instrumentation are of
varying value. We try to report the average number of pages
that are paged in (pi) and out (po) per second during the
interval. If the corresponding page swapping metrics are
unavailable, we report the average rate per second of swap
operations in (si) and out (so) during the interval. It is
normal for the ‘‘in’’ values to be non-zero, but the system
is suffering memory stress if the ‘‘out’’ values are non-zero
over an extended period.
If the values become large, they are reported as thousands of
operations per second (K suffix) or millions of operations
per second (M suffix).
io The bi and bo columns indicate the average rate per second of
block input and block output operations (respectfully) during
the interval. Unless all file systems have a 1 Kbyte block
size, these rates do not directly indicate Kbytes transfered.
If the values become large, they are reported as thousands of
operations per second (K suffix) or millions of operations
per second (M suffix).
system Interrupt rate (in) and context switch rate (cs). Rates are
expressed as average operations per second during the
interval. Note that the interrupt rate is normally at least
HZ (the clock interrupt rate, usually 100) interrupts per
second.
If the values become large, they are reported as thousands of
operations per second (K suffix) or millions of operations
per second (M suffix).
cpu Percentage of CPU time spent executing user and "nice user"
code (usr), system and interrupt processing code (sys), idle
loop (idl).
If any values for the associated performance metrics are unavailable,
the value appears as ‘‘?’’ in the output.
By default, pmstat reports the time of day according to the local
timezone on the system where pmstat is run. The -Z option changes the
timezone to timezone in the format of the environment variable TZ as
described in environ(5). The -z option changes the timezone to the
local timezone at the host that is the source of the performance
metrics, as identified via either the -h or -a options.
FILES
$PCP_VAR_DIR/pmns/*
default PMNS specification files
$PCP_VAR_DIR/config/pmlogger/config.pmstat
pmlogger(1) configuration for creating an archive suitable
for replay with pmstat
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the
file and directory names used by PCP. On each installation, the file
/etc/pcp.conf contains the local values for these variables. The
$PCP_CONF variable may be used to specify an alternative configuration
file, as described in pcp.conf(4).
SEE ALSO
PCPIntro(1), pmclient(1), pmtime(1), PMAPI(3), pmNewContext(3),
pcp.conf(4) and pcp.env(4).
DIAGNOSTICS
All are generated on standard error, and are intended to be self-
explanatory.