PMDAHOTPROC(1)

NAME
pmdahotproc - Hot Proc performance metrics domain agent (PMDA)

SYNOPSIS
$PCP_PMDAS_DIR/hotproc/pmdahotproc [-C] [-d domain] [-l logfile] [-s] [-t interval] [-U username] configfile

DESCRIPTION
pmdahotproc is a Performance Metrics Domain Agent (PMDA) which exports proc performance metrics from an instance domain of processes restricted to an "interesting" or "hot" set. Unlike the proc PMDA which has an instance domain equal to the current processes, pmdahotproc has an instance domain which is a subset of this and is determined by a configuration file and a refresh interval.

As well as the proc metrics, pmdahotproc provides a cpuburn metric which specifies the cpu utilization of the process over the refresh interval, total metrics which indicate how much of the cpu that the "interesting" processes are accounting for, predicate metrics which show the values of the reserved variables (see below) that are being used in the hotproc predicate and control metrics for controlling the agent.

A brief description of the pmdahotproc command line options follows:

-C  Parse configfile, report any errors and exit.

-d  It is absolutely crucial that the performance metrics domain number specified here is unique and consistent. That is, domain should be different for every PMDA on the one host, and the same domain number should be used for the same PMDA on all hosts.

-l  Location of the log file. By default, a log file named hotproc.log is written in the current directory of pmcd(1) when pmdahotproc is started, i.e. $PCP_LOG_DIR/pmcd. If the log file cannot be created or is not writable, output is written to the standard error instead.

-s  With this option, attempts to change the agent configuration by modifying the values of hotproc.control.refresh and hotproc.control.config using pmstore(1) will not be permitted. Without this option, storing into these hotproc.control metrics will be permitted.

-t  pmdahotproc will regenerate its interesting set of processes using the configuration predicate, once every interval period. The period is specified as a time interval using the syntax described in PCPIntro(1). The default interval is 60 seconds.

-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.

CONFIGURATION
The configuration file consists of one predicate used to determine if a process should be in the interesting set or not.

Example configurations files may be found at $PCP_PMDAS_DIR/hotproc/sample.conf and $PCP_PMDAS_DIR/hotproc/general.conf .

The predicate is described using the language specified below. The symbols are based on those used by c(1) and awk(1).

Boolean Connectives
    && (and), || (or), ! (not), () (precedence overriding)

Number comparators
    < , <= , > , >= , == , !=

String comparators
    == , !=

String/Pattern comparators
    ~ (string matches pattern) , !~ (string does not match pattern)

Reserved variables
    uid (user id; type integer) uname (user name; type string), gid (group id; type integer) gname (group name; type string), fname (process file name; type string), psargs (process file name with args; type string), cpuburn (cpu utilization; type float), iodemand (I/O demand - Kbytes read/written per second; type float), ctxswitch (number of context switches per second; type float), syscalls (number of system calls per second; type float), virtualsize (virtual size in Kbytes; type float), residentsize (resident size in Kbytes; type float), iowait (blocked and raw io wait in secs/sec; type float), schedwait (time waiting in run queue in secs/sec; type float).

Literal values
    1234 (positive integer), 0.35 (positive float), "foobar" (string; delimited by "), /[fF](o)+bar/ (pattern; delimited by /), true (boolean), false (boolean)

Comments
    #this is a comment (from # to the end of the line).

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

The hotproc.predicate 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 hotproc.predicate metric may not have a value if it is not referenced in the configuration predicate.

INSTALLATION
If you want access to the names, help text and values for the Hotproc performance metrics, do the following as root:

# cd $PCP_PMDAS_DIR/hotproc
# ./Install

If you want to undo the installation, do the following as root:

# cd $PCP_PMDAS_DIR/hotproc
# ./Remove

pmdahotproc is launched by pmcd(1) and should never be executed directly. The Install and Remove scripts notify pmcd(1) when the agent is installed or removed.

FILES
$PCP_PMCDCONF_PATH
    command line options used to launch pmdahotproc
/tmp/pcp.ttymap
    tty map file used for hotproc.psinfo.ttyname
$PCP_PMDAS_DIR/hotproc/help
    default help text file for the Hotproc metrics
$PCP_PMDAS_DIR/hotproc/Install
    installation script for the pmdahotproc agent
$PCP_PMDAS_DIR/hotproc/Remove
    undo installation script for the pmdahotproc agent
$PCP_PMDAS_DIR/hotproc/sample.conf
    simple sample configuration (this is the default one)
$PCP_PMDAS_DIR/hotproc/general.conf
    another sample configuration that identifies "interesting" processes from several different classes.
$PCP_VAR_DIR/config/hotproc/hotproc.conf
    predicate configuration file from the most recent installation of the pmdahotproc agent
$PCP_LOG_DIR/pmcd/hotproc.log
    default log file for error messages and other information from pmdahotproc

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).

SEE ALSO
PCPIntro(1), pmcd(1) and pmstore(1).

CAVEATS
Some of the required metrics may not be available on some platforms and these will generate an error message on startup.

The values for hotproc.psinfo.ttyname are extracted from /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, /tmp/pcp.ttymap should be removed and pmcd restarted ($PCP_RC_DIR/pcp start); this will create a new tty map file.