1PMSTAT(1) General Commands Manual PMSTAT(1)
2
3
4
6 pcp-vmstat, pmstat - high-level system performance overview
7
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
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
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
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
165 PCPIntro(1), pmclient(1), pmtime(1), PMAPI(3), pmNewContext(3),
166 pcp.conf(5) and pcp.env(5).
167
169 All are generated on standard error, and are intended to be self-
170 explanatory.
171
172
173
174Performance Co-Pilot PCP PMSTAT(1)