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  archive]  [-A  align] [-h host] [-H file] [-n
12       pmnsfile] [-O offset] [-p port] [-s samples] [-S starttime] [-t  inter‐
13       val] [-T endtime] [-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       By  default,  pmstat  fetches  metrics by connecting to the Performance
33       Metrics Collector Daemon (PMCD) on the local host.  If the -L option is
34       specified, then pmcd(1) is bypassed, and metrics are fetched from PMDAs
35       on the local host using  the  standalone  PM_CONTEXT_LOCAL  variant  of
36       pmNewContext(3).   When  the -h option is specified, pmstat connects to
37       the pmcd(1) on host and  fetches  metrics  from  there.   As  mentioned
38       above, multiple hosts may be monitored by supplying multiple -h flags.
39
40       Alternatively, if the -a option is used, the metrics are retrieved from
41       the Performance Co-Pilot archive log files identified by archive, which
42       is  a comma-separated list of names, each of which may be the base name
43       of an archive or the name of a directory containing  one  or  more  ar‐
44       chives.   Multiple sets of archives may be replayed by supplying multi‐
45       ple -a flags.  When the -a flag is used, the -P flag may also  be  used
46       to pause the output after each interval.
47
48       Standalone  mode can only connect to the local host, using a set of ar‐
49       chives implies a host name, and nominating a host  precludes  using  an
50       archive, so the options -L, -a and -h are mutually exclusive.
51
52       pmstat  may  relinquish  its  own  timing  control,  and  operate  as a
53       ``slave'' of a pmtime(1) process that uses a GUI dialog to provide tim‐
54       ing  control.   In  this  case,  either the -g option should be used to
55       start pmstat as the sole slave of  a  new  pmtime(1)  instance,  or  -p
56       should  be  used to attach pmstat to an existing pmtime(1) instance via
57       the IPC channel identified by the port argument.
58
59       The -S, -T, -O and -A options may be used to define a  time  window  to
60       restrict  the  samples retrieved, set an initial origin within the time
61       window, or specify a ``natural'' alignment of the sample  times;  refer
62       to PCPIntro(1) for a complete description of these options.
63

OPTIONS

65       The available command line options are:
66
67       -a archive, --archive=archive
68            Performance  metric  values  are retrieved from the set of Perfor‐
69            mance Co-Pilot (PCP) archive log files identified by  the  archive
70            argument,  which is a comma-separated list of names, each of which
71            may be the base name of an archive or the name of a directory con‐
72            taining one or more archives.
73
74       -A align, --align=align
75            Force  the initial sample to be aligned on the boundary of a natu‐
76            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
77            tion of the syntax for align.
78
79       -g, --guimode
80            Start pmstat as the slave of a new pmtime(1) process for replay of
81            archived performance  data  using  the  pmtime(1)  graphical  user
82            interface.
83
84       -h host, --host=host
85            Fetch  performance  metrics from pmcd(1) on host, rather than from
86            the default localhost.
87
88       -H path, --hostsfile=path
89            Specify the path to a file containing a  set  of  hostnames  where
90            pmcd(1) is running , rather than using the default localhost.
91
92       -K spec, --spec-local=spec
93            When fetching metrics from a local context (see -L), the -K option
94            may be used to control the DSO PMDAs that should be made  accessi‐
95            ble.   The  spec  argument  conforms  to  the  syntax described in
96            pmSpecLocalPMDA(3).  More than one -K option may be used.
97
98       -l, --suffix
99            Prints the last 7 characters of a hostname in summaries  involving
100            more  than  one host (when more than one -h option has been speci‐
101            fied on the command line).
102
103       -L, --local-PMDA
104            Use a local context to collect metrics from DSO PMDAs on the local
105            host without PMCD.  See also -K.
106
107       -n pmnsfile, --namespace=pmnsfile
108            Load  an alternative Performance Metrics Name Space (PMNS(5)) from
109            the file pmnsfile.
110
111       -O origin, --origin=origin
112            When reporting archived metrics, start reporting at origin  within
113            the  time window (see -S and -T).  Refer to PCPIntro(1) for a com‐
114            plete description of the syntax for origin.
115
116       -p port, --guiport=port
117            Attach pmstat  to  an  existing  pmtime(1)  time  control  process
118            instance  via  the  IPC  channel  identified by the port argument.
119            This  option  is  normally  only  used  by   other   tools,   e.g.
120            pmchart(1),  when  they  launch pmstat with synchronized time con‐
121            trol.
122
123       -s samples, --samples=samples
124            The samples option defines the number of samples to  be  retrieved
125            and reported.  If samples is 0 or -s is not specified, pmstat will
126            sample and report continuously - this is the default behavior.
127
128       -S starttime, --start=starttime
129            When reporting archived metrics, the report will be restricted  to
130            those  records logged at or after starttime.  Refer to PCPIntro(1)
131            for a complete description of the syntax for starttime.
132
133       -t interval, --interval=interval
134            Set the reporting interval to something other than the  default  1
135            second.   The  interval  argument  follows the syntax described in
136            PCPIntro(1), and in the simplest form may be an  unsigned  integer
137            (the implied units in this case are seconds).
138
139       -T endtime, --finish=endtime
140            When  reporting archived metrics, the report will be restricted to
141            those records logged before or at endtime.
142
143       -x, --xcpu
144            The extended CPU metrics option, causes two additional CPU metrics
145            to  be  reported,  namely  wait  for I/O ("wa") and virtualisation
146            steal time ("st").
147
148       -z, --hostzone
149            Change the reporting timezone to the local timezone  at  the  host
150            that  is  the source of the performance metrics, as identified via
151            either the -h or -a options.
152
153       -Z timezone, --timezone=timezone
154            By default, pmtime reports the time of day according to the  local
155            timezone on the system where pmstat is run.  The -Z option changes
156            the timezone to timezone in the format of the environment variable
157            TZ as described in environ(7).
158

OUTPUT

160       The  output from pmstat is directed to standard output, and the columns
161       in the report are interpreted as follows:
162
163       loadavg   The 1 minute load average.
164
165       memory    The swpd column indicates average swap space used during  the
166                 interval,  in Kbytes.  The free column indicates average free
167                 memory during the interval, in Kbytes.  The buff column indi‐
168                 cates  average  buffer  memory in use during the interval, in
169                 Kbytes.  The cache column indicates average cached memory  in
170                 use during the interval, in Kbytes.
171
172                 If  the  values  become large, they are reported as Mbytes (m
173                 suffix) or Gbytes (g suffix).
174
175       swap      The metrics in this area of the kernel instrumentation are of
176                 varying  value.  We try to report the average number of pages
177                 that are paged in (pi) and out (po)  per  second  during  the
178                 interval.   If  the  corresponding  page swapping metrics are
179                 unavailable, we report the average rate per  second  of  swap
180                 operations  in  (si) and out (so) during the interval.  It is
181                 normal for the ``in'' values to be non-zero, but  the  system
182                 is suffering memory stress if the ``out'' values are non-zero
183                 over an extended period.
184
185                 If the values become large, they are reported as thousands of
186                 operations  per  second  (K suffix) or millions of operations
187                 per second (M suffix).
188
189       io        The bi and bo columns indicate the average rate per second of
190                 block input and block output operations (respectfully) during
191                 the interval.  Unless all file systems have a 1  Kbyte  block
192                 size,  these  rates  do  not  directly indicate Kbytes trans‐
193                 ferred.
194
195                 If the values become large, they are reported as thousands of
196                 operations  per  second  (K suffix) or millions of operations
197                 per second (M suffix).
198
199       system    Interrupt rate (in) and context switch rate (cs).  Rates  are
200                 expressed  as average operations per second during the inter‐
201                 val.  Note that the interrupt rate is normally  at  least  HZ
202                 (the  clock  interrupt rate, usually 100) interrupts per sec‐
203                 ond.
204
205                 If the values become large, they are reported as thousands of
206                 operations  per  second  (K suffix) or millions of operations
207                 per second (M suffix).
208
209       cpu       Percentage of CPU time spent executing user and  "nice  user"
210                 code  (us),  system  and interrupt processing code (sy), idle
211                 loop (id).
212
213       If any values for the associated performance metrics  are  unavailable,
214       the value appears as ``?'' in the output.
215

DIAGNOSTICS

217       All  are  generated  on  standard  error  and  are intended to be self-
218       explanatory.
219

FILES

221       $PCP_VAR_DIR/pmns/*
222                 default PMNS specification files
223       $PCP_VAR_DIR/config/pmlogger/config.pmstat
224                 pmlogger(1) configuration for creating  an  archive  suitable
225                 for replay with pmstat
226

PCP ENVIRONMENT

228       Environment variables with the prefix PCP_ are used to parameterize the
229       file and directory names used by PCP.  On each installation,  the  file
230       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
231       $PCP_CONF variable may be used to specify an alternative  configuration
232       file, as described in pcp.conf(5).
233

SEE ALSO

235       PCPIntro(1),   pmclient(1),   pmtime(1),   PMAPI(3),   pmNewContext(3),
236       pcp.conf(5), pcp.env(5) and PMNS(5).
237
238
239
240Performance Co-Pilot                  PCP                            PMSTAT(1)
Impressum