1PMSTAT(1) General Commands Manual PMSTAT(1)
2
6 pmstat - high-level system performance overview
7
9 pmstat [-gLlPxz] [-A align] [-a archive] [-h host] [-H file] [-n pmns‐
10 file] [-O offset] [-p port] [-S starttime] [-s samples] [-T endtime]
11 [-t interval] [-Z timezone]
12
14 pmstat provides a one line summary of system performance every interval
15 unit of time (the default is 5 seconds). pmstat is intended to monitor
16 system performance at the highest level, after which other tools may be
17 used to examine subsystems in which potential performance problems may
18 be observed in greater detail.
19 Multiple hosts may be monitored by supplying more than one host with
21 multiple -h flags (for live monitoring) or by providing a name of the
22 hostlist file, where each line contain one host name, with -H, or mul‐
23 tiple -a flags (for retrospective monitoring from an archive).
24 The -t option may be used to change the default reporting interval.
26 The interval argument follows the syntax described in PCPIntro(1), and
27 in the simplest form may be an unsigned integer (the implied units in
28 this case are seconds).
29 By default, pmstat fetches metrics by connecting to the Performance
31 Metrics Collector Daemon (PMCD) on the local host. If the -L option is
32 specified, then pmcd(1) is bypassed, and metrics are fetched from PMDAs
33 on the local host using the standalone PM_CONTEXT_LOCAL variant of
34 pmNewContext(3). When the -h option is specified, pmstat connects to
35 the pmcd(1) on host and fetches metrics from there. As mentioned
36 above, multiple hosts may be monitored by supplying multiple -h flags.
37 Alternatively, if the -a option is used, the metrics are retrieved from
39 the Performance Co-Pilot archive log files identified by the base name
40 archive. Multiple archives may be replayed by supplying multiple -a
41 flags. When the -a flag is used, the -P flag may also be used to pause
42 the output after each interval.
43 Standalone mode can only connect to the local host, using an archive
45 implies a host name, and nominating a host precludes using an archive,
46 so the options -L, -a and -h are mutually exclusive.
47 Normally pmstat operates on the default Performance Metrics Name Space
49 (PMNS), however if the -n option is specified an alternative namespace
50 is loaded from the file pmnsfile.
51 If the -s the option is specified, samples defines the number of sam‐
53 ples to be retrieved and reported. If samples is 0 or -s is not speci‐
54 fied, pmstat will sample and report continuously - this is the default
55 behavior.
56 When processing an archive, pmstat may relinquish its own timing con‐
58 trol, and operate as a ``slave'' of a pmtime(1) process that uses a GUI
59 dialog to provide timing control. In this case, either the -g option
60 should be used to start pmstat as the sole slave of a new pmtime(1)
61 instance, or -p should be used to attach pmstat to an existing
62 pmtime(1) instance via the IPC channel identified by the port argument.
63 The -S, -T, -O and -A options may be used to define a time window to
65 restrict the samples retrieved, set an initial origin within the time
66 window, or specify a ``natural'' alignment of the sample times; refer
67 to PCPIntro(1) for a complete description of these options.
68 The -l option prints the last 7 characters of a hostname in summaries
70 involving more than one host (when more than one -h option has been
71 specified on the command line).
72 The -x option (extended CPU metrics) causes two additional CPU metrics
74 to be reported, namely wait for I/O ("wa") and virtualisation steal
75 time ("st").
76 The output from pmstat is directed to standard output, and the columns
78 in the report are interpreted as follows:
79 loadavg The 1 minute load average.
81 memory The swpd column indicates average swap space used during the
83 interval, in Kbytes. The free column indicates average free
84 memory during the interval, in Kbytes. The buff column indi‐
85 cates average buffer memory in use during the interval, in
86 Kbytes. The cache column indicates average cached memory in
87 use during the interval, in Kbytes.
88 If the values become large, they are reported as Mbytes (m
90 suffix) or Gbytes (g suffix).
91 swap The metrics in this area of the kernel instrumentation are of
93 varying value. We try to report the average number of pages
94 that are paged in (pi) and out (po) per second during the
95 interval. If the corresponding page swapping metrics are
96 unavailable, we report the average rate per second of swap
97 operations in (si) and out (so) during the interval. It is
98 normal for the ``in'' values to be non-zero, but the system
99 is suffering memory stress if the ``out'' values are non-zero
100 over an extended period.
101 If the values become large, they are reported as thousands of
103 operations per second (K suffix) or millions of operations
104 per second (M suffix).
105 io The bi and bo columns indicate the average rate per second of
107 block input and block output operations (respectfully) during
108 the interval. Unless all file systems have a 1 Kbyte block
109 size, these rates do not directly indicate Kbytes trans‐
110 ferred.
111 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 system Interrupt rate (in) and context switch rate (cs). Rates are
117 expressed as average operations per second during the inter‐
118 val. Note that the interrupt rate is normally at least HZ
119 (the clock interrupt rate, usually 100) interrupts per sec‐
120 ond.
121 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 cpu Percentage of CPU time spent executing user and "nice user"
127 code (us), system and interrupt processing code (sy), idle
128 loop (id).
129 If any values for the associated performance metrics are unavailable,
131 the value appears as ``?'' in the output.
132 By default, pmstat reports the time of day according to the local time‐
134 zone on the system where pmstat is run. The -Z option changes the
135 timezone to timezone in the format of the environment variable TZ as
136 described in environ(7). The -z option changes the timezone to the
137 local timezone at the host that is the source of the performance met‐
138 rics, as identified via either the -h or -a options.
139
141 $PCP_VAR_DIR/pmns/*
142 default PMNS specification files
143 $PCP_VAR_DIR/config/pmlogger/config.pmstat
144 pmlogger(1) configuration for creating an archive suitable
145 for replay with pmstat
146
148 Environment variables with the prefix PCP_ are used to parameterize the
149 file and directory names used by PCP. On each installation, the file
150 /etc/pcp.conf contains the local values for these variables. The
151 $PCP_CONF variable may be used to specify an alternative configuration
152 file, as described in pcp.conf(5).
153
155 PCPIntro(1), pmclient(1), pmtime(1), PMAPI(3), pmNewContext(3),
156 pcp.conf(5) and pcp.env(5).
157
159 All are generated on standard error, and are intended to be self-
160 explanatory.
161Performance Co-Pilot PCP PMSTAT(1)