'\"macro stdmacro
.TH PMTOP 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmtop\f1 \- report top process resource usage
.SH SYNOPSIS
\f3pmtop\f1
[\f3\-h\f1 \f2host\f1]
[\f3\-m\f1 \f2top\f1]
[\f3\-p\f1 \f2spec,...\f1]
[\f3\-s\f1 \f2samples\f1]
[\f3\-t\f1 \f2interval\f1]
[\f3\-w\f1]
[\f3\-z\f1]
[\f3\-Z\f1 \f2timezone\f1]
.SH DESCRIPTION
.B pmtop
reports per-process resource usage statistics
within the Performance Co-Pilot framework.
It outputs the highest \f2top\f1 values for the process
resources of cpu utilization, system calls per second,
context switches per second, kilobytes of data written per second,
kilobytes of data read per second and resident set size. 
A subset of this information may be selected using the
.B \-p
option.
.SH COMMAND LINE OPTIONS
The command line options for
.B pmtop
are as follows:
.TP
\f3\-h\f1 \f2host\f1
Fetch performance metrics from
.BR pmcd (1)
on
.IR host ,
rather than the default local:.
.TP
\f3\-m\f1 \f2top\f1
Report the \f2top\f1 highest values for a particular process 
resource category.
The default is the top 5.
.TP
\f3\-p\f1 \f2spec,...\f1
Print out the process resource categories specified in the list of
\f2spec\f1s. The specification is constructed from a comma
separated list of categories from the following set:
\f3cpu\f1, \f3sysc\f1, \f3ctx\f1, \f3read\f1,
\f3write\f1 and \f3rss\f1.
For example, "\f3\-p\f1 \f3cpu,ctx,rss\f1", will show
three reports for the categories of cpu utilization, context switches and
resident memory. It will also only show the category columns
of \f3CPU%\f1, \f3CTX\f1 and \f3RSS\f1. 
The default is to display all the categories.
.TP
\f3\-s\f1 \f2samples\f1
Determines how many samples (iterations) of process data
are displayed.
The default is to do an infinite number of samples.
.TP
\f3\-t\f1 \f2interval\f1
This value is used to determine the interval between fetching
process data and reporting it.
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).
The default is 2 seconds.
.TP
\f3\-w\f1
Normally the report is truncated at the 80th column.
This option relieves this restriction.
.TP
\f3\-Z\f1 \f2timezone\f1
By default,
.B pmtop
reports the time of day according to the local timezone on the system where
.B pmtop
is run.  The
.B \-Z
option changes the default timezone to 
.I timezone
which should be in the format of the environment variable
.B TZ
as described in 
.BR environ (5).
.TP
\f3\-z\f1
Change the reporting timezone to the local timezone at the host that is the
source of the performance metrics, as identified via the
.B \-h
option.
.SH "REPORT FORMAT"
.PP
The report is divided up into a number of sections, one for each
process category as specified by the 
.B \-p
option.
This also affects which columns are displayed. 
.P
At the top of the CPU%, SYSCALLS and CTX sections 
it specifies how much the top
processes used of the resource compared with how much was
used globally by all the processes over the interval. 
For example, for the
CPU utilization category looking at the top 5 processes, 
a value of 90% indicates that the top 5 processes account
for 90% of the cpu consumption, the other 10% is used by processes
which are not shown. These other processes are either not
in the top 5, started after the beginning of the interval or 
exited before the end of the interval.  
.PP
The columns in the report should be interpreted as follows:
.PP
.TP 10
.B PID
Process ID.
.TP
.B CPU%
Percentage of CPU Utilization.
.TP
.B SYSCALLS
The number of system calls per second.
.TP
.B CTX
The number of context switches per second.
.TP
.B WRITES
The number of kilobytes of data written per second.
.TP
.B READS
The number of kilobytes of data read per second.
.TP
.B RSS
The current resident set size in kilobytes.
.TP
.B CMD
The command and arguments, truncated so each line in the
report is at most 80 columns (unless the
.B \-w
option is given).
.SH SEE ALSO
.BR pmcd (1),
.BR pmem (1)
and
.BR pminfo (1).