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  [-gLlPVxz?]   [-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
15       pcp-vmstat ...
16

DESCRIPTION

18       pmstat provides a one line summary of system performance every interval
19       unit of time (the default is 5 seconds).  pmstat is intended to monitor
20       system performance at the highest level, after which other tools may be
21       used to examine subsystems in which potential performance problems  may
22       be observed in greater detail.
23
24       pcp-vmstat is a simple wrapper for use with the pcp(1) command, provid‐
25       ing a more familiar command line format for some users.   It  also  en‐
26       ables  the  extended reporting option by default, see the -x option be‐
27       low.
28
29       Multiple hosts may be monitored by supplying more than  one  host  with
30       multiple  -h  flags (for live monitoring) or by providing a name of the
31       hostlist file, where each line contain one host name, with -H, or  mul‐
32       tiple -a flags (for retrospective monitoring from sets of archives).
33
34       By  default,  pmstat  fetches  metrics by connecting to the Performance
35       Metrics Collector Daemon (PMCD) on the local host.  If the -L option is
36       specified, then pmcd(1) is bypassed, and metrics are fetched from PMDAs
37       on the local host using the standalone PM_CONTEXT_LOCAL variant of  pm‐
38       NewContext(3).  When the -h option is specified, pmstat connects to the
39       pmcd(1) on host and fetches metrics from there.   As  mentioned  above,
40       multiple hosts may be monitored by supplying multiple -h flags.
41
42       Alternatively, if the -a option is used, the metrics are retrieved from
43       the Performance Co-Pilot archive files identified by archive, which  is
44       a  comma-separated list of names, each of which may be the base name of
45       an archive or the name of a directory containing one or more  archives.
46       Multiple  sets  of  archives  may  be replayed by supplying multiple -a
47       flags.  When the -a flag is used, the -P flag may also be used to pause
48       the output after each interval.
49
50       Standalone  mode can only connect to the local host, using a set of ar‐
51       chives implies a host name, and nominating a host  precludes  using  an
52       archive, so the options -L, -a and -h are mutually exclusive.
53
54       pmstat  may  relinquish  its  own timing control, and operate under the
55       control of a pmtime(1) process that uses a GUI dialog to provide timing
56       control.   In  this  case, either the -g option should be used to start
57       pmstat as the sole client of a new pmtime(1) instance, or -p should  be
58       used  to  attach  pmstat  to an existing pmtime(1) instance via the IPC
59       channel identified by the port argument.
60
61       The -S, -T, -O and -A options may be used to define a  time  window  to
62       restrict  the  samples retrieved, set an initial origin within the time
63       window, or specify a ``natural'' alignment of the sample  times;  refer
64       to PCPIntro(1) for a complete description of these options.
65

OPTIONS

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

OUTPUT

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

FILES

227       $PCP_VAR_DIR/pmns/*
228            default PMNS specification files
229
230       $PCP_VAR_DIR/config/pmlogger/config.pmstat
231            pmlogger(1) configuration for creating an archive suitable for re‐
232            play with pmstat
233

PCP ENVIRONMENT

235       Environment variables with the prefix PCP_ are used to parameterize the
236       file and directory names used by PCP.  On each installation,  the  file
237       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
238       $PCP_CONF variable may be used to specify an alternative  configuration
239       file, as described in pcp.conf(5).
240
241       For environment variables affecting PCP tools, see pmGetOptions(3).
242

SEE ALSO

244       PCPIntro(1),   pmclient(1),   pmtime(1),   PMAPI(3),   pmNewContext(3),
245       pcp.conf(5), pcp.env(5) and PMNS(5).
246
247
248
249Performance Co-Pilot                  PCP                            PMSTAT(1)
Impressum