# pmdaoverhead

## NAME



           **pmdaoverhead** - performance metrics domain agent (PMDA) exporting
           resource consumption metrics for groups of processes
    


## SYNOPSIS



           **$PCP_PMDAS_DIR/overhead/pmdaoverhead**[**-C**] [**-c** _config_] [**-D** _debug_]
           [**-d** _domain_] [**-l** _logfile_] [**-R** _interval_]
    


## DESCRIPTION



           **pmdaoverhead** is a configurable Performance Metrics Domain Agent
           (PMDA) for exporting resource consumption for groups of related
           processes.
    
           The **pmdaoverhead** command line options are:
    
           **-C** parse the configuration file(s) and exit after reporting any
               errors.
    
           **-c** configuration file(s), _config_ may be either a file or a
               directory; in the latter case all the files within _config_ are
               assumed to be configuration files for **pmdaoverhead** and they
               will all be processed.
    
               Each configuration file defines one or more ``groups'' of
               processes of interest, using the syntax described in the
               ``CONFIGURATION'' section below.
    
               By default all configuration files below the
               _$PCP_SYSCONF_DIR/overhead/conf.d/_ directory are used.
    
           **-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
               _overhead.log_ is written in the current directory of pmcd(1)
               when **pmdaoverhead** 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.
    
           **-R** The PMDA uses a separate thread to periodically scan all
               processes to determine which processes are deemed
               ``interesting'' in each group, and extracting resource
               consumption for those processes.  The _interval_ (in seconds)
               determines how often this scanning and resource calculation is
               done, the default is 60 (seconds).
    


## CONFIGURATION



           Each configuration file defines one or more ``groups'' of
           processes.  The file format is simple and follows the following
           rules.
    
           1.  Lines beginning with a hash ``#'' are treated as comments.
               More generally, except for the **pattern:** clause described
               below, all text between a hash and the end of line is treated
               as a comment.
    
           2.  White space (spaces or tabs or newlines) are required to
               separate lexical components.  Spaces and tabs are otherwise
               ignored.  Other than terminating comments and the _regex_ in a
               **pattern:** clause, newlines are also ignored.
    
           3.  Each group is introduced by a **group** clause that has the form
                       **group** _name_ **{**_parameters_ **}**
               where _name_ is a unique name for the group across all groups in
               the **pmdaoverhead** configuration files.  As _name_ becomes
               embedded in the Performance Metrics Name Space (PMNS) if must
               follow the rules for metric name components as described in
               PMNS(5), namely beginning with an alphabetic character,
               followed by zero or more characters drawn from the
               alphabetics, numerics and the underscore ``_'' character.
    
           4.  The _parameters_ must include one **id:** clause and one **pattern:**
               clause.
    
           5.  An **id:** clause has the form
                       **id:**_ident_
               where _ident_ is a unique identifier number for the group across
               all groups in the **pmdaoverhead** configuration files.  Valid
               values for _ident_ are in the range 0 to 4094 (inclusive).
    
           6.  A **pattern:** clause has the form
                       **pattern:**_regex_
               where _regex_ is an extended regular expression notation in the
               style of **egrep**(1).  The _regex_ starts at the first non-
               whitespace character after **pattern:** and extends to the next
               newline.
    
               The processes that are considered to be members of the group
               are those for which the command name, as reported by
                       $ pminfo -f proc.psinfo.cmd
               is matched by _regex_ **plus** all the descendents of those
               processes.  So for example the _regex_ **^pmcd$** will match pmcd(1)
               and all the PMDA processes launched by pmcd(1) and any of
               their children, etc.
    


## INSTALLATION



           If you want access to the names, help text and values for the
           overhead performance metrics, do the following as root:
    
                # cd $PCP_PMDAS_DIR/overhead
                # ./Install
    
           If you want to undo the installation, do the following as root:
    
                # cd $PCP_PMDAS_DIR/overhead
                # ./Remove
    
           **pmdaoverhead** is launched by **pmcd** and should never be executed
           directly.  The Install and Remove scripts notify **pmcd** when the
           agent is installed or removed.
    


## FILES



           **$PCP_PMCDCONF_PATH**
                  command line options used to launch **pmdaoverhead**
           **$PCP_PMDAS_DIR/overhead/Install**
                  installation script for the **pmdaoverhead** agent
           **$PCP_PMDAS_DIR/overhead/Remove**
                  undo installation script for the **pmdaoverhead** agent
           **$PCP_LOG_DIR/pmcd/overhead.log**
                  default log file for error messages and other information
                  from **pmdaoverhead**
           **$PCP_SYSCONF_DIR/overhead/conf.d**
                  directory containing configuration files for the overhead
                  metrics
    


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


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    
           Debugging options specific to **pmdaoverhead** are as follows:
           ┌────────┬────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼────────────────────────────────┤
           │ **appl0** │ _configfile_ parsing             │
           ├────────┼────────────────────────────────┤
           │ **appl1** │ refresh() start-end timestamps │
           ├────────┼────────────────────────────────┤
           │ **appl2** │ /proc selection in refresh()   │
           └────────┴────────────────────────────────┘
    


* * *