diff options
Diffstat (limited to 'man/man1/pmstat.1')
| -rw-r--r-- | man/man1/pmstat.1 | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/man/man1/pmstat.1 b/man/man1/pmstat.1 new file mode 100644 index 0000000..2bac73b --- /dev/null +++ b/man/man1/pmstat.1 @@ -0,0 +1,325 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSTAT 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmstat\f1 \- high-level system performance overview +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmstat\f1 +[\f3\-gLlPxz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-H\f1 \f2file\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-Z\f1 \f2timezone\f1] +.SH DESCRIPTION +.B pmstat +provides a one line summary of system performance every +.I interval +unit of time (the default is 5 seconds). +.B 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. +.P +Multiple hosts may be monitored by supplying more than +one host with multiple +.B \-h +flags (for live monitoring) or by providing a name of the hostlist file, where +each line contain one host name, with +.B \-H, +or multiple +.B \-a +flags (for retrospective monitoring from an archive). +.P +The +.B \-t +option may be used to change the default reporting +.IR interval . +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.PP +By default, +.B pmstat +fetches metrics by connecting to the Performance Metrics Collector +Daemon (PMCD) on the local host. If the +.B \-L +option is specified, then +.BR pmcd (1) +is bypassed, and metrics are fetched from PMDAs on the local host +using the standalone +.B PM_CONTEXT_LOCAL +variant of +.BR pmNewContext (3). +When the +.B \-h +option is specified, +.B pmstat +connects to the +.BR pmcd (1) +on +.I host +and fetches metrics from there. +As mentioned above, multiple hosts may be monitored +by supplying multiple +.B \-h +flags. +.PP +Alternatively, if the +.B \-a +option is used, the metrics are retrieved from the Performance Co-Pilot +archive log files identified by the base name +.IR archive . +Multiple archives may be replayed by supplying multiple +.B \-a +flags. +When the +.B \-a +flag is used, +the +.B \-P +flag may also be used to pause the output after each interval. +.PP +Standalone mode can only connect to the local host, using an archive implies +a host name, and nominating a host precludes using an archive, so the options +.BR \-L , +.B \-a +and +.B \-h +are mutually exclusive. +.PP +Normally +.B pmstat +operates on the default Performance Metrics Name Space (PMNS), however +if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile . +.PP +If the +.B \-s +the option is specified, +.I samples +defines the number of samples to be retrieved and reported. +If +.I samples +is 0 or +.B \-s +is not specified, +.B pmstat +will sample and report continuously \- this is the default behavior. +.PP +When processing an archive, +.B pmstat +may relinquish its own timing control, and operate as a ``slave'' of a +.BR pmtime (1) +process that uses a GUI dialog to provide timing control. +In this case, either the +.B \-g +option should be used to start +.B pmstat +as the sole slave of a new +.BR pmtime (1) +instance, or +.B \-p +should be used to attach +.B pmstat +to an existing +.BR pmtime (1) +instance via the IPC channel identified by the port argument. +.PP +The +.BR \-S , +.BR \-T , +.BR \-O +and +.B \-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 +.BR PCPIntro (1) +for a complete description of these options. +.PP +The +.B \-l +option prints the last 7 characters of a hostname in summaries involving +more than one host (when more than one +.B \-h +option has been specified on the command line). +.PP +The +.B \-x +option (extended CPU metrics) causes two additional CPU metrics to be +reported, namely wait for I/O ("wa") and virtualisation steal time ("st"). +.PP +The output from +.B pmstat +is directed to standard output, and the columns +in the report are interpreted as follows: +.PP +.TP 10 +.B loadavg +The +.I "1 minute" +load average. +.TP +.B memory +The \f3swpd\fP column indicates average swap space used during the interval, +in Kbytes. +The \f3free\fP column indicates average free memory during the interval, +in Kbytes. +The \f3buff\fP column indicates average buffer memory in use during the interval, +in Kbytes. +The \f3cache\fP column indicates average cached memory in use during the interval, +in Kbytes. +.RS +.PP +If the values become large, they are reported as Mbytes +.BR "" ( m " suffix)" +or Gbytes +.BR "" ( g " suffix)." +.RE +.TP +.B swap +The metrics in this area of the kernel instrumentation are of +varying value. We try to report the average number of \f3pages\fP +that are paged in (\f3pi\fP) and out (\f3po\fP) per second during +the interval. +If the corresponding page swapping metrics are unavailable, we report +the average rate per second +of swap \f3operations\fP in (\f3si\fP) and out (\f3so\fP) 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. +.RS +.PP +If the values become large, they are reported as thousands of +operations per second +.BR "" ( K " suffix)" +or millions of operations per second +.BR "" ( M " suffix)." +.RE +.TP +.B io +The \f3bi\fP and \f3bo\fP 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. +.RS +.PP +If the values become large, they are reported as thousands of +operations per second +.BR "" ( K " suffix)" +or millions of operations per second +.BR "" ( M " suffix)." +.RE +.TP +.B system +Interrupt rate (\f3in\fP) and +context switch rate (\f3cs\fP). +Rates are expressed as average operations per second during the interval. +Note that the interrupt rate is normally at least +.I HZ +(the clock interrupt rate, usually 100) +interrupts per second. +.RS +.PP +If the values become large, they are reported as thousands of +operations per second +.BR "" ( K " suffix)" +or millions of operations per second +.BR "" ( M " suffix)." +.RE +.TP +.B cpu +Percentage of CPU time spent executing user and "nice user" code (\f3us\fP), +system and interrupt processing code (\f3sy\fP), idle loop (\f3id\fP). +.P +If any values for the associated performance metrics are unavailable, +the value appears as ``?'' in the output. +.PP +By default, +.B pmstat +reports the time of day according to the local timezone on the +system where +.B pmstat +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the +host that is the source of the performance metrics, as identified via +either the +.B \-h +or +.B \-a +options. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.TP +.BI $PCP_SYSCONF_DIR/pmlogger/config.pmstat +.BR pmlogger (1) +configuration for creating an archive suitable for replay with +.B pmstat +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmclient (1), +.BR pmtime (1), +.BR PMAPI (3), +.BR pmNewContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All are generated on standard error, and are intended to be self-explanatory. |