'\"macro stdmacro
.TH PMDAHOTPROC 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdahotproc\f1 \- Hot Proc performance metrics domain agent (PMDA)
.SH SYNOPSIS
\f3$PCP_PMDAS_DIR/hotproc/pmdahotproc\f1
[\f3\-C\f1]
[\f3\-d\f1 \f2domain\f1]
[\f3\-l\f1 \f2logfile\f1]
[\f3\-s\f1]
[\f3\-t\f1 \f2interval\f1]
[\f3\-U\f1 \f2username\f1]
\f2configfile\f1
.br
.SH DESCRIPTION
.B pmdahotproc
is a Performance Metrics Domain Agent (PMDA) which exports
.B proc 
performance metrics from an instance domain of processes restricted
to an "interesting" or "hot" set. Unlike the 
.B proc 
PMDA which has an instance domain equal to the current processes,
.B pmdahotproc
has an instance domain which is a subset of this and is
determined by a configuration file and a refresh interval. 
.P
As well as
the
.B proc
metrics, 
.B pmdahotproc
provides a \f3cpuburn\f1 metric which specifies the cpu utilization
of the process over the refresh interval, \f3total\f1 metrics which
indicate how much of the cpu that the "interesting" processes are
accounting for, \f3predicate\f1 metrics which show the values of
the reserved variables (see below) that
are being used in the hotproc predicate and \f3control\f1 metrics
for controlling the agent.
.PP
A brief description of the
.B pmdahotproc
command line options follows:
.TP 5
.B \-C
Parse
.IR configfile ,
report any errors and exit.
.TP 5
.B \-d
It is absolutely crucial that the performance metrics
.I domain
number specified here is unique and consistent.
That is,
.I domain
should be different for every PMDA on the one host, and the same
.I domain
number should be used for the same PMDA on all hosts.
.TP 5
.B \-l
Location of the log file.  By default, a log file named
.I hotproc.log
is written in the current directory of
.BR pmcd (1)
when
.B pmdahotproc
is started, i.e.
.BR $PCP_LOG_DIR/pmcd .
If the log file cannot
be created or is not writable, output is written to the standard error instead.
.TP 5
.B \-s
With this option, attempts to change the agent configuration by
modifying the values of
\f3hotproc.control.refresh\f1 and \f3hotproc.control.config\f1 using 
.BR pmstore(1)
will not be permitted.
Without this option, storing into these \f3hotproc.control\f1 metrics will
be permitted.
.TP 5
.B \-t
.B pmdahotproc
will regenerate its interesting set of processes using the configuration
predicate, once every
.I interval
period.
The period is specified as a time interval using the syntax
described in 
.BR PCPIntro (1).
The default
.I interval
is 60 seconds.
.TP 5
.B \-U
User account under which to run the agent.
The default is the unprivileged "pcp" account in current versions of PCP,
but in older versions the superuser account ("root") was used by default.
.SH CONFIGURATION
The configuration file consists of one predicate used to determine if
a process should be in the interesting set or not.
.PP
Example configurations files may be found at
.B $PCP_PMDAS_DIR/hotproc/sample.conf
and
.B $PCP_PMDAS_DIR/hotproc/general.conf .
.PP
The predicate is described
using the language specified below. The symbols are based on those
used by 
.BR c (1) 
and 
.BR awk (1) .
.TP 
Boolean Connectives
.B &&
(and),
.B ||
(or),
.B !
(not),
.B ()
(precedence overriding)
.TP 
Number comparators
.B <
,
.B <=
,
.B >
,
.B >=
,
.B ==
,
.B !=
.TP 
String comparators
.B ==
,
.B !=
.TP 
String/Pattern comparators
.B ~
(string matches pattern)
,
.B !~
(string does not match pattern)
.TP 
Reserved variables
.B uid
(user id; type integer)
.B uname
(user name; type string),
.B gid
(group id; type integer)
.B gname
(group name; type string),
.B fname
(process file name; type string),
.B psargs
(process file name with args; type string),
.B cpuburn
(cpu utilization; type float),
.B iodemand
(I/O demand - Kbytes read/written per second; type float),
.B ctxswitch
(number of context switches per second; type float),
.B syscalls
(number of system calls per second; type float),
.B virtualsize
(virtual size in Kbytes; type float),
.B residentsize
(resident size in Kbytes; type float),
.B iowait
(blocked and raw io wait in secs/sec; type float),
.B schedwait
(time waiting in run queue in secs/sec; type float).
.TP
Literal values
.B 1234
(positive integer),
.B 0.35
(positive float),
\f3"foobar"\f1
(string; delimited by \f3"\f1),
.B /[fF](o)+bar/
(pattern; delimited by \f3/\f1),
.B true
(boolean),
.B false
(boolean)
.TP
Comments
.B #this is a comment
(from \f3#\f1 to the end of the line).
.TP
Examples
  cpuburn > 0.2 # cpu utilization of more than 20%
  cpuburn > 0.2 && uname == "root"
  cpuburn > 0.2 && (uname == "root" || uname == "hot")
  psargs ~ /pmda/ && cpuburn > 0.4

.PP
The \f3hotproc.predicate\f1 metrics may be used
to see what the values of the reserved variables are
that were used by the predicate at the last refresh.
They do not cover the reserved variables which are
already exported elsewhere. A \f3hotproc.predicate\f1 metric
may not have a value if it is not referenced in the configuration
predicate. 
 

.SH INSTALLATION
If you want access to the names, help text and values for the Hotproc
performance metrics, do the following as root:
.PP
.ft CW
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/hotproc
# ./Install
.in
.fi
.ft 1
.PP
If you want to undo the installation, do the following as root:
.PP
.ft CW
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/hotproc
# ./Remove
.in
.fi
.ft 1
.PP
.B pmdahotproc
is launched by
.BR pmcd (1)
and should never be executed directly.
The Install and Remove scripts notify
.BR pmcd (1)
when the agent is installed or removed.
.SH FILES
.PD 0
.TP 10
.B $PCP_PMCDCONF_PATH
command line options used to launch
.B pmdahotproc
.TP 10
.B /tmp/pcp.ttymap
tty map file used for hotproc.psinfo.ttyname
.TP 10
.B $PCP_PMDAS_DIR/hotproc/help
default help text file for the Hotproc metrics
.TP 10
.B $PCP_PMDAS_DIR/hotproc/Install
installation script for the
.B pmdahotproc
agent
.TP 10
.B $PCP_PMDAS_DIR/hotproc/Remove
undo installation script for the 
.B pmdahotproc
agent
.TP 10
.B $PCP_PMDAS_DIR/hotproc/sample.conf
simple sample configuration (this is the default one)
.TP 10
.B $PCP_PMDAS_DIR/hotproc/general.conf
another sample configuration that identifies "interesting"
processes from several different classes.
.TP 10
.B $PCP_VAR_DIR/config/hotproc/hotproc.conf
predicate configuration file from the most recent installation
of the
.B pmdahotproc
agent
.TP 10
.B $PCP_LOG_DIR/pmcd/hotproc.log
default log file for error messages and other information from
.B pmdahotproc
.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
.B /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 pmcd (1)
and
.BR pmstore (1).
.SH CAVEATS
Some of the required metrics may not be available on some platforms and these
will generate an error
message on startup.
.P
The values for hotproc.psinfo.ttyname are extracted from 
.B /tmp/pcp.ttymap
which is created on the very first fetch of proc.psinfo.ttyname or 
hotproc.psinfo.ttyname.
If new tty's are created past the high-water mark in /dev, then
this file will be out of date. To fix this, 
.B /tmp/pcp.ttymap 
should be removed and pmcd restarted ($PCP_RC_DIR/pcp start); 
this will create a new tty map file.