Provided by: pcp_6.2.0-1.1build4_amd64 bug

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 must be a version line in the control file of the form:
               $version=1.1
       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 the
           name of 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/pcp 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.
       12. 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.

       The following sample control lines specify a primary logger on the local host (bozo),  and
       non-primary  loggers  to  collect and log performance metrics from the hosts wobbly, boing
       and the local host (i.e. bozo).

       $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

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

SEE ALSO

       PCPIntro(1),  pmcd(1),  pmlogctl(1),  pmlogger(1),  pmlogger_check(1),  pmlogger_daily(1),
       pmlogger_daily_report(1), pmsocks(1), systemd(1) and cron(8).