1PMSTAT(1)                   General Commands Manual                  PMSTAT(1)
2
3
4

NAME

6       pcp-vmstat, pmstat - high-level system performance overview
7

SYNOPSIS

9       pcp [pcp options] vmstat [interval [samples]]
10
11       pmstat  [-gLlPxz] [-A align] [-a archive] [-h host] [-H file] [-n pmns‐
12       file] [-O offset] [-p port] [-S starttime] [-s  samples]  [-T  endtime]
13       [-t interval] [-Z timezone]
14

DESCRIPTION

16       pmstat provides a one line summary of system performance every interval
17       unit of time (the default is 5 seconds).  pmstat is intended to monitor
18       system performance at the highest level, after which other tools may be
19       used to examine subsystems in which potential performance problems  may
20       be observed in greater detail.
21
22       pcp-vmstat is a simple wrapper for use with the pcp(1) command, provid‐
23       ing a more familiar command  line  format  for  some  users.   It  also
24       enables  the  extended  reporting  option by default, see the -x option
25       below.
26
27       Multiple hosts may be monitored by supplying more than  one  host  with
28       multiple  -h  flags (for live monitoring) or by providing a name of the
29       hostlist file, where each line contain one host name, with -H, or  mul‐
30       tiple -a flags (for retrospective monitoring from sets of archives).
31
32       The  -t  option  may  be used to change the default reporting interval.
33       The interval argument follows the syntax described in PCPIntro(1),  and
34       in  the  simplest form may be an unsigned integer (the implied units in
35       this case are seconds).
36
37       By default, pmstat fetches metrics by  connecting  to  the  Performance
38       Metrics Collector Daemon (PMCD) on the local host.  If the -L option is
39       specified, then pmcd(1) is bypassed, and metrics are fetched from PMDAs
40       on  the  local  host  using  the standalone PM_CONTEXT_LOCAL variant of
41       pmNewContext(3).  When the -h option is specified, pmstat  connects  to
42       the  pmcd(1)  on  host  and  fetches  metrics from there.  As mentioned
43       above, multiple hosts may be monitored by supplying multiple -h flags.
44
45       Alternatively, if the -a option is used, the metrics are retrieved from
46       the Performance Co-Pilot archive log files identified by archive, which
47       is a comma-separated list of names, each of which may be the base  name
48       of  an  archive  or  the name of a directory containing one or more ar‐
49       chives.  Multiple sets of archives may be replayed by supplying  multi‐
50       ple  -a  flags.  When the -a flag is used, the -P flag may also be used
51       to pause the output after each interval.
52
53       Standalone mode can only connect to the local host, using a set of  ar‐
54       chives  implies  a  host name, and nominating a host precludes using an
55       archive, so the options -L, -a and -h are mutually exclusive.
56
57       Normally pmstat operates on the default Performance Metrics Name  Space
58       (PMNS),  however if the -n option is specified an alternative namespace
59       is loaded from the file pmnsfile.
60
61       If the -s the option is specified, samples defines the number  of  sam‐
62       ples to be retrieved and reported.  If samples is 0 or -s is not speci‐
63       fied, pmstat will sample and report continuously - this is the  default
64       behavior.
65
66       When processing a set of archives, pmstat may relinquish its own timing
67       control, and operate as a ``slave'' of a pmtime(1) process that uses  a
68       GUI  dialog  to  provide  timing  control.  In this case, either the -g
69       option should be used to start pmstat  as  the  sole  slave  of  a  new
70       pmtime(1)  instance, or -p should be used to attach pmstat to an exist‐
71       ing pmtime(1) instance via the IPC channel identified by the port argu‐
72       ment.
73
74       The  -S,  -T,  -O and -A options may be used to define a time window to
75       restrict the samples retrieved, set an initial origin within  the  time
76       window,  or  specify a ``natural'' alignment of the sample times; refer
77       to PCPIntro(1) for a complete description of these options.
78
79       The -l option prints the last 7 characters of a hostname  in  summaries
80       involving  more  than  one  host (when more than one -h option has been
81       specified on the command line).
82
83       The -x option (extended CPU metrics) causes two additional CPU  metrics
84       to  be  reported,  namely  wait for I/O ("wa") and virtualisation steal
85       time ("st").
86
87       The output from pmstat is directed to standard output, and the  columns
88       in the report are interpreted as follows:
89
90       loadavg   The 1 minute load average.
91
92       memory    The  swpd column indicates average swap space used during the
93                 interval, in Kbytes.  The free column indicates average  free
94                 memory during the interval, in Kbytes.  The buff column indi‐
95                 cates average buffer memory in use during  the  interval,  in
96                 Kbytes.   The cache column indicates average cached memory in
97                 use during the interval, in Kbytes.
98
99                 If the values become large, they are reported  as  Mbytes  (m
100                 suffix) or Gbytes (g suffix).
101
102       swap      The metrics in this area of the kernel instrumentation are of
103                 varying value.  We try to report the average number of  pages
104                 that  are  paged  in  (pi) and out (po) per second during the
105                 interval.  If the corresponding  page  swapping  metrics  are
106                 unavailable,  we  report  the average rate per second of swap
107                 operations in (si) and out (so) during the interval.   It  is
108                 normal  for  the ``in'' values to be non-zero, but the system
109                 is suffering memory stress if the ``out'' values are non-zero
110                 over an extended period.
111
112                 If the values become large, they are reported as thousands of
113                 operations per second (K suffix) or  millions  of  operations
114                 per second (M suffix).
115
116       io        The bi and bo columns indicate the average rate per second of
117                 block input and block output operations (respectfully) during
118                 the  interval.   Unless all file systems have a 1 Kbyte block
119                 size, these rates do  not  directly  indicate  Kbytes  trans‐
120                 ferred.
121
122                 If the values become large, they are reported as thousands of
123                 operations per second (K suffix) or  millions  of  operations
124                 per second (M suffix).
125
126       system    Interrupt  rate (in) and context switch rate (cs).  Rates are
127                 expressed as average operations per second during the  inter‐
128                 val.   Note  that  the interrupt rate is normally at least HZ
129                 (the clock interrupt rate, usually 100) interrupts  per  sec‐
130                 ond.
131
132                 If the values become large, they are reported as thousands of
133                 operations per second (K suffix) or  millions  of  operations
134                 per second (M suffix).
135
136       cpu       Percentage  of  CPU time spent executing user and "nice user"
137                 code (us), system and interrupt processing  code  (sy),  idle
138                 loop (id).
139
140       If  any  values for the associated performance metrics are unavailable,
141       the value appears as ``?'' in the output.
142
143       By default, pmstat reports the time of day according to the local time‐
144       zone  on  the  system  where  pmstat is run.  The -Z option changes the
145       timezone to timezone in the format of the environment  variable  TZ  as
146       described  in  environ(7).   The  -z option changes the timezone to the
147       local timezone at the host that is the source of the  performance  met‐
148       rics, as identified via either the -h or -a options.
149

FILES

151       $PCP_VAR_DIR/pmns/*
152                 default PMNS specification files
153       $PCP_VAR_DIR/config/pmlogger/config.pmstat
154                 pmlogger(1)  configuration  for  creating an archive suitable
155                 for replay with pmstat
156

PCP ENVIRONMENT

158       Environment variables with the prefix PCP_ are used to parameterize the
159       file  and  directory names used by PCP.  On each installation, the file
160       /etc/pcp.conf contains the  local  values  for  these  variables.   The
161       $PCP_CONF  variable may be used to specify an alternative configuration
162       file, as described in pcp.conf(5).
163

SEE ALSO

165       PCPIntro(1),   pmclient(1),   pmtime(1),   PMAPI(3),   pmNewContext(3),
166       pcp.conf(5) and pcp.env(5).
167

DIAGNOSTICS

169       All  are  generated  on  standard  error,  and are intended to be self-
170       explanatory.
171
172
173
174Performance Co-Pilot                  PCP                            PMSTAT(1)
Impressum