--- name: "pmdahotproc" section: "1" platform: "linux" package: "pcp" version: "2.7.4-20080507" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/pmdahotproc" --- # pmdahotproc(1) Hot Proc performance metrics domain agent (PMDA) } ## NAME **pmdahotproc** - Hot Proc performance metrics domain agent (PMDA) ## SYNOPSIS **$PCP\_PMDAS\_DIR/hotproc/pmdahotproc** \[**-C**\] \[**-d** *domain*\] \[**-l** *logfile*\] \[**-s**\] \[**-t** *interval*\] *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 reserverd 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)](/pmcd/1.md) 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)](/pmstore/1.md)** 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)](/PCPIntro/1.md). The default *interval* is 60 seconds. ## 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)](/c/1.md) and [**awk**(1)](/awk/1.md)**.** - Boolean Connectives **&&** (and), **\|\|** (or), **!** (not), **()** (precedence overidding) - 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)](/pmcd/1.md) and should never be executed directly. The Install and Remove scripts notify [**pmcd**(1)](/pmcd/1.md) 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**(4)](/pcp.conf/4.md). ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md) and [**pmstore**(1)](/pmstore/1.md). ## CAVEATS **iowait** and **schedwait** are not supported in IRIX 5.3 and 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.