--- name: "pcp-vmstat" section: "1" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pcp-vmstat" --- # pcp-vmstat(1) high-level system performance overview ## NAME **pcp-vmstat**, **pmstat** - high-level system performance overview ## SYNOPSIS **pcp** \[*pcp options*\] **vmstat** \[*interval* \[*samples*\]\] **pmstat** \[**-gLlPVxz?**\] \[**-a** *archive*\] \[**-A** *align*\] \[**-D** *debug*\] \[**-h** *host*\] \[**-H** *file*\] \[**-n** *pmnsfile*\] \[**-O** *offset*\] \[**-p** *port*\] \[**-s** *samples*\] \[**-S** *starttime*\] \[**-t** *interval*\] \[**-T** *endtime*\] \[**-Z** *timezone*\] **pcp-vmstat** ... ## DESCRIPTION **pmstat** provides a one line summary of system performance every *interval* unit of time (the default is 5 seconds). **pmstat** is intended to monitor system performance at the highest level, after which other tools may be used to examine subsystems in which potential performance problems may be observed in greater detail. **pcp-vmstat** is a simple wrapper for use with the [**pcp**(1)](/pcp/1.md) command, providing a more familiar command line format for some users. It also enables the extended reporting option by default, see the *-x* option below. Multiple hosts may be monitored by supplying more than one host with multiple **-h** flags (for live monitoring) or by providing a name of the hostlist file, where each line contain one host name, with **-H,** or multiple **-a** flags (for retrospective monitoring from sets of archives). By default, **pmstat** fetches metrics by connecting to the Performance Metrics Collector Daemon (PMCD) on the local host. If the **-L** option is specified, then [**pmcd**(1)](/pmcd/1.md) is bypassed, and metrics are fetched from PMDAs on the local host using the stand-alone **PM\_CONTEXT\_LOCAL** variant of [**pmNewContext**(3)](/pmNewContext/3.md). When the **-h** option is specified, **pmstat** connects to the [**pmcd**(1)](/pmcd/1.md) on *host* and fetches metrics from there. As mentioned above, multiple hosts may be monitored by supplying multiple **-h** flags. Alternatively, if the **-a** option is used, the metrics are retrieved from the Performance Co-Pilot archive files identified by *archive*, which is a comma-separated list of names, each of which may be the base name of an archive or the name of a directory containing one or more archives. Multiple sets of archives may be replayed by supplying multiple **-a** flags. When the **-a** flag is used, the **-P** flag may also be used to pause the output after each interval. Stand-alone mode can only connect to the local host, using a set of archives implies a host name, and nominating a host precludes using an archive, so the options **-L**, **-a** and **-h** are mutually exclusive. **pmstat** may relinquish its own timing control, and operate under the control of a [**pmtime**(1)](/pmtime/1.md) process that uses a GUI dialog to provide timing control. In this case, either the **-g** option should be used to start **pmstat** as the sole client of a new [**pmtime**(1)](/pmtime/1.md) instance, or **-p** should be used to attach **pmstat** to an existing [**pmtime**(1)](/pmtime/1.md) instance via the IPC channel identified by the *port* argument. The **-S**, **-T**, **-O** and **-A** options may be used to define a time window to restrict the samples retrieved, set an initial origin within the time window, or specify a \`\`natural'' alignment of the sample times; refer to [**PCPIntro**(1)](/PCPIntro/1.md) for a complete description of these options. ## OPTIONS The available command line options are: - **-a** *archive*, **--archive**=*archive* Performance metric values are retrieved from the set of Performance Co-Pilot (PCP) archive files identified by the *archive* argument, which is a comma-separated list of names, each of which may be the base name of an archive or the name of a directory containing one or more archives. - **-A** *align*, **--align**=*align* Force the initial sample to be aligned on the boundary of a natural time unit *align*. Refer to [**PCPIntro**(1)](/PCPIntro/1.md) for a complete description of the syntax for *align*. - **-g**, **--guimode** Start **pmstat** as the client of a new [**pmtime**(1)](/pmtime/1.md) server process for replay of archived performance data using the [**pmtime**(1)](/pmtime/1.md) graphical user interface. - **-h** *host*, **--host**=*host* Fetch performance metrics from [**pmcd**(1)](/pmcd/1.md) on *host*, rather than from the default localhost. - **-H** *path*, **--hostsfile**=*path* Specify the *path* to a file containing a set of hostnames where [**pmcd**(1)](/pmcd/1.md) is running , rather than using the default localhost. - **-K** *spec*, **--spec-local**=*spec* When fetching metrics from a local context (see **-L**), the **-K** option may be used to control the DSO PMDAs that should be made accessible. The *spec* argument conforms to the syntax described in [**pmSpecLocalPMDA**(3)](/pmSpecLocalPMDA/3.md). More than one **-K** option may be used. - **-l**, *--suffix* Prints the last 7 characters of a hostname in summaries involving more than one host (when more than one **-h** option has been specified on the command line). - **-L**, **--local-PMDA** Use a local context to collect metrics from DSO PMDAs on the local host without PMCD. See also **-K**. - **-n** *pmnsfile*, **--namespace**=*pmnsfile* Load an alternative Performance Metrics Name Space ([**PMNS**(5)](/PMNS/5.md)) from the file *pmnsfile*. - **-O** *origin*, **--origin**=*origin* When reporting archived metrics, start reporting at *origin* within the time window (see **-S** and **-T**). Refer to [**PCPIntro**(1)](/PCPIntro/1.md) for a complete description of the syntax for *origin*. - **-p** *port*, **--guiport**=*port* Attach **pmstat** to an existing [**pmtime**(1)](/pmtime/1.md) time control process instance via the IPC channel identified by the *port* argument. This option is normally only used by other tools, e.g. [**pmchart**(1)](/pmchart/1.md), when they launch **pmstat** with synchronized time control. - **-P**, **--pause** Pause between updates for archive replay. - **-s** *samples*, **--samples**=*samples* The *samples* option defines the number of samples to be retrieved and reported. If *samples* is 0 or **-s** is not specified, **pmstat** will sample and report continuously - this is the default behavior. - **-S** *starttime*, **--start**=*starttime* When reporting archived metrics, the report will be restricted to those records logged at or after *starttime*. Refer to [**PCPIntro**(1)](/PCPIntro/1.md) for a complete description of the syntax for *starttime*. - **-t** *interval*, **--interval**=*interval* Set the reporting *interval* to something other than the default 5 seconds. The *interval* argument follows the syntax described in [**PCPIntro**(1)](/PCPIntro/1.md), and in the simplest form may be an unsigned integer (the implied units in this case are seconds). - **-T** *endtime*, **--finish**=*endtime* When reporting archived metrics, the report will be restricted to those records logged before or at *endtime*. - **-V**, **--version** Display version number and exit. - **-x**, *--xcpu* The extended CPU metrics option, causes three additional CPU metrics to be reported, namely wait for I/O ("wa"), virtualisation steal time ("st"), and virtual guest time ("gu"). - **-z**, **--hostzone** Change the reporting timezone to the local timezone at the host that is the source of the performance metrics, as identified via either the **-h** or **-a** options. - **-Z** *timezone*, **--timezone**=*timezone* By default, **pmtime** reports the time of day according to the local timezone on the system where **pmstat** is run. The **-Z** option changes the timezone to *timezone* in the format of the environment variable TZ as described in [**environ**(7)](/environ/7.md). - **-?**, **--help** Display usage message and exit. ## OUTPUT The output from **pmstat** is directed to standard output, and the columns in the report are interpreted as follows: - **loadavg** The *1 minute* load average. - **memory** The **swpd** column indicates average swap space used during the interval, in Kbytes. The **free** column indicates average free memory during the interval, in Kbytes. The **buff** column indicates average buffer memory in use during the interval, in Kbytes. The **cache** column indicates average cached memory in use during the interval, in Kbytes. If the values become large, they are reported as Mbytes(**m** suffix) or Gbytes(**g** suffix). - **swap** The metrics in this area of the kernel instrumentation are of varying value. We try to report the average number of **pages** that are paged in (**pi**) and out (**po**) per second during the interval. If the corresponding page swapping metrics are unavailable, we report the average rate per second of swap **operations** in (**si**) and out (**so**) during the interval. It is normal for the \`\`in'' values to be non-zero, but the system is suffering memory stress if the \`\`out'' values are non-zero over an extended period. If the values become large, they are reported as thousands of operations per second(**K** suffix) or millions of operations per second(**M** suffix). - **io** The **bi** and **bo** columns indicate the average rate per second of block input and block output operations (respectfully) during the interval. Unless all file systems have a 1 Kbyte block size, these rates do not directly indicate Kbytes transferred. If the values become large, they are reported as thousands of operations per second(**K** suffix) or millions of operations per second(**M** suffix). - **system** Interrupt rate (**in**) and context switch rate (**cs**). Rates are expressed as average operations per second during the interval. Note that the interrupt rate is normally at least *HZ* (the clock interrupt rate, usually 100) interrupts per second. If the values become large, they are reported as thousands of operations per second(**K** suffix) or millions of operations per second(**M** suffix). - **cpu** Percentage of CPU time spent executing user and "nice user" code (**us**), system and interrupt processing code (**sy**), idle loop (**id**). If any values for the associated performance metrics are unavailable, the value appears as \`\`?'' in the output. ## FILES - *$PCP\_VAR\_DIR/pmns/\** default PMNS specification files - *$PCP\_VAR\_DIR/config/pmlogger/config.pmstat* [**pmlogger**(1)](/pmlogger/1.md) configuration for creating an archive suitable for replay with **pmstat** ## PCP ENVIRONMENT Environment variables with the prefix **PCP\_** are used to parameterize the file and directory names used by PCP. On each installation, the file */etc/pcp.conf* contains the local values for these variables. The **$PCP\_CONF** variable may be used to specify an alternative configuration file, as described in [**pcp.conf**(5)](/pcp.conf/5.md). For environment variables affecting PCP tools, see [**pmGetOptions**(3)](/pmGetOptions/3.md). ## DEBUGGING OPTIONS The **-D** or **--debug** option enables the output of additional diagnostics on *stderr* to help triage problems, although the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. *debug* is a comma separated list of debugging options; use [**pmdbg**(1)](/pmdbg/1.md) with the **-l** option to obtain a list of the available debugging options and their meaning. ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**pmclient**(1)](/pmclient/1.md), [**pmtime**(1)](/pmtime/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pcp.conf**(5)](/pcp.conf/5.md), [**pcp.env**(5)](/pcp.env/5.md) and [**PMNS**(5)](/PMNS/5.md).