# pmlogger.control

## NAME



           **pmlogger.control** - control files for Performance Co-Pilot
           archiving
    


## DESCRIPTION



           Historical archiving of performance data for Performance Co-Pilot
           (see PCPIntro(1)) uses pmlogger(1) and one or more instances of
           **pmlogger** may be managed by pmlogger_check(1) and
           pmlogger_daily(1).
    
           pmlogger_check(1) may be run at any time of the day and is
           intended to check that the desired set of **pmlogger** processes are
           running.  If not, it (re-)starts any missing logger processes.  By
           default, pmlogger_check(1) also calls pmlogger_daily(1) with a **-K**
           option to execute any required archive compression tasks.
    
           pmlogger_daily(1) is intended to be run once per day, preferably
           in the early morning, as soon after midnight as practicable.  Its
           task is to aggregate, rotate and perform general housekeeping for
           one or more sets of PCP archives.
    
           Both pmlogger_check(1) and pmlogger_daily(1) operate on a family
           of shared control files, namely the _$PCP_PMLOGGERCONTROL_PATH_ file
           and files within the _$PCP_PMLOGGERCONTROL_PATH.d_ directory.  These
           files must not be writable by any user other than root.
    
           The control file(s) should be customized according to the
           following rules that define for the current version (1.1) of the
           control file format.
    
           1.  Lines beginning with a ``#'' are comments.  A special case is
               lines beginning ``#!#''; these are control lines for a
               **pmlogger** that has been stopped using pmlogctl(1).
           2.  Lines beginning with a ``$'' are assumed to be assignments to
               environment variables in the style of **sh**(1), and all text
               following the ``$'' will be **eval** 'ed by the script reading the
               control file, and the corresponding variable exported into the
               environment.  This is particularly useful to set and export
               variables into the environment of the administrative scripts,
               e.g.
                   $ PMCD_CONNECT_TIMEOUT=20
               If the value to the right of the ``='' contains any white
               space, then the value should be enclosed in double (") or
               single (') quotes.
           3.  There should be a version line in the control file of the
               form:
                   $version=1.1
               But since the only version currently supported is 1.1, this
               declaration provides no additional value beyond documentation.
    
           4.  Fields within a line of the control file(s) are usually
               separated by one or more spaces or tabs (although refer to the
               description of the _directory_ field below for some important
               exceptions).
    
           5.  There should be one line in the control file(s) for each
               **pmlogger** instance with at least 4 fields of the form:
                   _host primary socks directory args_ ...
    
           6.  The _host_ field is the name of the host that is the source of
               the performance metrics for this **pmlogger** instance.  The
               reserved word **LOCALHOSTNAME** will be replaced by **local:**(so
               connection to pmcd(1) on the local host).
    
           7.  The _primary_ field indicates if this is a primary **pmlogger**
               instance (**y**) or not (**n**).  Since the primary logger must run on
               the local host, and there may be at most one primary logger
               for a particular host, this field can be **y** for at most one
               **pmlogger** instance, in which case the host name must be the
               name of the local host (or **LOCALHOSTNAME**).
    
           8.  The _socks_ field indicates if this **pmlogger** instance needs to
               be started under the control of pmsocks(1) to connect to a
               pmcd(1) through a firewall (**y** or **n**).
    
           9.  The _directory_ field is a directory name.  All archive files
               associated with this **pmlogger** instance will be created in this
               directory, and this will be the current directory for the
               execution of any programs required to maintain those archives.
               A useful convention is that primary logger archives for the
               local host with hostname _myhost_ are maintained in the
               directory _$PCP_ARCHIVE_DIR/myhost_ (this is where the default
               **pmlogger** start-up script in _$PCP_RC_DIR/pmlogger_ will create
               the archives), while archives for the remote host _mumble_ are
               maintained in _$PCP_ARCHIVE_DIR/mumble_.
    
           10. The _directory_ field may contain embedded shell syntax that
               will be evaluated by **sh**(1) to produce the real directory name
               to be used.  The allowed constructs are:
               • Any text (including white space) enclosed with **$(** and **)** will
                 be interpreted as a shell command.
               • Any text (including white space) enclosed with **`** and **`**(back
                 quotes) will be interpreted as a shell command.
               • Within a single line only one style of embedded shell
                 command is allowed, so either **$(**...**)** or **`**...**`** , but not
                 both.
               • An initial double quote (") followed by arbitrary text
                 (including white space, but excluding an embedded double
                 quote) and a final double quote.
               • An initial single quote (') followed by arbitrary text
                 (including white space, but excluding an embedded single
                 quote) and a final single quote.
               • Any word containing a **$**(assumed to introduce an environment
                 variable name).
           11. In the _directory_ field, the reserved word **LOCALHOSTNAME** will
               be replaced by the name of the local host.  Similarly the
               reserved words **PCP_ARCHIVE_DIR** and **PCP_LOG_DIR** appearing
               anywhere in the _directory_ field will be replaced by the values
               of the corresponding environment variables.
           12. If the _directory_ field (after any shell substitution) begins
               with ``+'' then this indicates that pmlogger(1) will be
               executed with a **-R** option in _args_ to ``push'' the archive to a
               remote pmproxy(1) server.  In this case, no archive files are
               stored locally, but _directory_ (after the leading ``+'' is
               stripped) is used as the directory in which the log file from
               the local pmlogger(1) will be stored and possibly the location
               for the pmlogger(1) configuration file (see the example
               below).
           13. The optional _args_ field and any remaining fields are
               interpreted as arguments to be passed to pmlogger(1).  Most
               typically this would be at least the **-c** option to specify the
               metrics to be logged and the logging frequencies, and/or **-R** in
               the case of a ``push'' archive.
    
           The following sample control lines specify a primary logger on the
           local host (_bozo_), non-primary loggers to collect and log
           performance metrics from the hosts _wobbly_ , _boing_ and the local
           host (i.e. _bozo_) and a logger pushing archives to the remote
           pmproxy(1) on the host _grunt_.
    
           $version=1.1
           bozo          y  n  $PCP_ARCHIVE_DIR/bozo   -c config.default
           wobbly        n  n  "/store/wobbly/$(date +%Y)"  -c ./wobbly.config
           boing         n  n  $PCP_ARCHIVE_DIR/boing   -c ./pmlogger.config
           LOCALHOSTNAME n  n  /cluster/LOCALHOSTNAME   -c ./precious.config
           LOCALHOSTNAME n  n  +PCP_ARCHIVE_DIR/remote -R http://grunt:44322 \
                               -c ./remote.config
    


## SCHEDULED EXECUTION



           The periodic execution of pmlogger_check(1) and pmlogger_daily(1)
           is controlled by either systemd(1) or cron(8).
    
           Typical crontab(5) entries are provided in
           _$PCP_SYSCONF_DIR/pmlogger/crontab_ (unless installed by default in
           _/etc/cron.d_ already) and shown below.
    
           # daily processing of archives
           14      0       *       *       *       $PCP_BINADM_DIR/pmlogger_daily
           # every 30 minutes, check pmlogger instances are running
           25,55   *       *       *       *       $PCP_BINADM_DIR/pmlogger_check
    
           When using systemd(1) on Linux, no **crontab** entries are needed as
           the timer mechanism provided by **systemd** is used instead to achieve
           the same period execution as the crontab example above.
    


## FILES



           _$PCP_PMLOGGERCONTROL_PATH_
                the PCP logger control file.  For a new installation this
                file contains no pmlogger(1) control lines (the real control
                files are all in the _$PCP_PMLOGGERCONTROL_PATH.d_ directory),
                but this file is still processed to support any legacy
                configurations therein from earlier PCP releases.
                **Warning** : this file must not be writable by any user other
                than root.
    
           _$PCP_PMLOGGERCONTROL_PATH.d_
                optional directory containing additional PCP logger control
                files, with one or more per **pmlogger** specification per file.
                **Warning** : the files herein must not be writable by any user
                other than root.
    
           _$PCP_SYSCONF_DIR/pmlogger/crontab_
                sample crontab for automated script execution by $PCP_USER
                (or root).  Exists only if the platform does not support the
                /etc/cron.d mechanism.
    


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


* * *