# pmstat

## 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) 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) is bypassed, and metrics
           are fetched from PMDAs on the local host using the stand-alone
           **PM_CONTEXT_LOCAL** variant of pmNewContext(3).  When the **-h** option
           is specified, **pmstat** connects to the pmcd(1) 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) 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)
           instance, or **-p** should be used to attach **pmstat** to an existing
           pmtime(1) 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) 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) for a complete
                description of the syntax for _align_.
    
           **-g** , **--guimode**
                Start **pmstat** as the client of a new pmtime(1) server process
                for replay of archived performance data using the pmtime(1)
                graphical user interface.
    
           **-h** _host_ , **--host** =_host_
                Fetch performance metrics from pmcd(1) 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) 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).  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))
                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)
                for a complete description of the syntax for _origin_.
    
           **-p** _port_ , **--guiport** =_port_
                Attach **pmstat** to an existing pmtime(1) 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), 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) 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), 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).
    
           **-?** , **--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) 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).
    
           For environment variables affecting PCP tools, see
           pmGetOptions(3).
    


## 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 end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    


* * *