1 files changed, 315 insertions, 0 deletions
diff --git a/man/retired/pmdahotproc.1 b/man/retired/pmdahotproc.1
new file mode 100644
index 0000000..1311529
--- /dev/null
+++ b/man/retired/pmdahotproc.1
@@ -0,0 +1,315 @@
+'\"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.