NAME

       pmlogger_daily,  pmlogger_check, pmlogger_merge - adminis­
       tration of Performance Co-Pilot archive log files


SYNOPSIS

       $PCP_BINADM_DIR/pmlogger_daily [-NV] [-c control] [-k dis­
       card]  [-m addresses] [-s size] [-x compress] [-X program]
       [-Y regex]
       $PCP_BINADM_DIR/pmlogger_check [-NV] [-c control]
       $PCP_BINADM_DIR/pmlogger_merge [-fNV] [input-basename  ...
       output-name]


DESCRIPTION

       This  series of shell scripts and associated control files
       may be used to create a customized regime  of  administra­
       tion  and  management for Performance Co-Pilot (see PCPin­
       tro(1)) archive log files.

       pmlogger_daily , pmlogger_check , and  pmlogger_merge  are
       equivalent  to  the scripts pmlogger_daily, pmlogger_check
       and pmlogger_merge which are deprecated but  preserved  on
       IRIX for backward compatibility.

       pmlogger_daily is intended to be run once per day, prefer­
       ably in the early morning, as soon after midnight as prac­
       ticable.   Its task is to aggregate and rotate one or more
       sets of PCP archives.  After some period, old PCP archives
       are discarded.  This period is 14 days by default, but may
       be changed using the -k option.  Two  special  values  are
       recognized  for  the period (discard), namely 0 to keep no
       archives beyond the current one, and  forever  to  prevent
       any archives being discarded.

       Archive data files can optionally be compressed after some
       period (compress), to conserve disk space.  This  is  par­
       ticularly  useful  for large numbers of pmlogger processes
       under the control of pmlogger_check.  The -x option speci­
       fies  the  number  of days after which to compress archive
       data files, and the -X option specifies the program to use
       for  compression - by default this is compress(1).  Use of
       the -Y option allows a regular expression to be  specified
       causing  files in the set of files matched for compression
       to be omitted - this allows only the data file to be  com­
       pressed,  and also prevents the program from attempting to
       compress  it  more  than  once.   The  default  regex   is
       ".meta$|.index$|.Z$|.gz$"  - such files are filtered using
       the -v option to egrep(1).

       In    addition,    if    the    PCP    ``notices''    file
       ($PCP_LOG_DIR/NOTICES)  is larger than 20480 bytes, pmlog­
       ger_daily will rename the file with a ``.old'' suffix, and
       start a new ``notices'' file.  The rotate threshold may be


       Use of the -m option causes pmlogger_daily to construct  a
       summary  of the ``notices'' file entries which were gener­
       ated in the last 24 hours, and e-mail that summary to  the
       set  of  space-separated addresses.  This daily summary is
       stored in the file $PCP_LOG_DIR/NOTICES.daily, which  will
       be  empty when no new ``notices'' entries were made in the
       previous 24 hour period.

       pmlogger_check may be run at any time, and is intended  to
       check  that  the  desired set of pmlogger(1) processes are
       running, and if not to re-launch any failed loggers.

       pmlogger_merge is a wrapper script for pmlogmerge(1)  that
       merges all of the archive logs matching the input-basename
       arguments, and creates a new archive using output-name  as
       the  base  name  for the physical files that constitute an
       archive log.  The  input-basename  arguments  may  contain
       meta  characters in the style of sh(1).  If specified, the
       -f option causes all of the input files to be removed once
       the output archive has been created.

       pmlogger_merge is used by pmlogger_daily.

       Both pmlogger_daily and pmlogger_check are controlled by a
       PCP  logger  control  file  that  specifies  the  pmlogger
       instances  to  be  managed.   The  default control file is
       $PCP_VAR_DIR/config/pmlogger/control, but an alternate may
       be specified using the -c option.

       The  control  file  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.
       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 envi­
              ronment.  This is particularly useful  to  set  and
              export variables into the environment of the admin­
              istrative scripts, e.g.
                  $ PMCD_CONNECT_TIMEOUT=20
              Warning:  The  $PCP_VAR_DIR/config/pmlogger/control
              file is a potential security risk and should not be
              writable by any user other than root.
       3.     There must be a version line of the form:
                  $ version=1.1
       4.     There should be one line in the  control  file  for
              each pmlogger instance of the form:

                  host y|n y|n directory args

              rated by one or more spaces or tabs.
       6.     The first field is the name of the host that is the
              source of the performance metrics for this pmlogger
              instance.
       7.     The second field indicates if  this  is  a  primary
              pmlogger  instance  (y) or not (n).  Since the pri­
              mary 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.
       8.     The third field indicates if this pmlogger instance
              needs to be started under the control of pmsocks(1)
              to connect to a pmcd through a firewall (y or n).
       9.     The fourth field is a directory  name.   All  files
              associated with this pmlogger instance will be cre­
              ated in this directory, and this will be  the  cur­
              rent  directory  for  the execution of any programs
              required in the maintenance of those  archives.   A
              useful  convention  is that primary logger archives
              for the local host with hostname myhost  are  main­
              tained   in   the   directory   $PCP_LOG_DIR/pmlog­
              ger/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  mum­
              ble are maintained in $PCP_LOG_DIR/pmlogger/mumble.
       10.    All other fields are interpreted as arguments to be
              passed  to  pmlogger(1)  and/or  pmnewlog(1).  Most
              typically this would be the -c option.

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

       $version=1.1
       bozo   y  n  $PCP_LOG_DIR/pmlogger/bozo   -c config.default
       boing  n  n  $PCP_LOG_DIR/pmlogger/boing  -c ./pmlogger.config

       Typical  crontab(5)  entries  for  periodic  execution  of
       pmlogger_daily    and    pmlogger_check   are   given   in
       $PCP_VAR_DIR/config/pmlogger/crontab and shown below.  Due
       to the file permissions involved, these should be added to
       the crontab for root if automated PCP archive log  mainte­
       nance is desired.

       # daily processing of archive logs
       10      0       *       *       *       $PCP_BINADM_DIR/pmlogger_daily
       # every 30 minutes, check pmlogger instances are running
       25,55   *       *       *       *       $PCP_BINADM_DIR/pmlogger_check

       Alternate  redirection of the output from the cron(1) exe­
       cution of the scripts may be controlled as follows:

           ing  of their activity.  By default the scripts gener­
           ate no output unless some error or  warning  condition
           is encountered.

       (2) To redirect the e-mail from cron(1) away from the root
           login,

           + Instead of using the ``root'' login, create  a  spe­
             cial  IRIX  login  with uid equal to 0, e.g. su_pcp.
             The password may be locked and/or the shell  invalid
             to  prevent  login or su (1), but the home directory
             should exist.  For example the  following  entry  in
             /etc/passwd:

                 su_pcp:x:0:0:PCP Housekeeping:/usr/people/su_pcp:/dev/null

           + Create a $HOME/.forward for su_pcp, else an entry in
             /usr/lib/aliases for su_pcp, redirecting the  e-mail
             to a real user or user(s).

           + Add  the  ``crontab''  entries  above to the crontab
             file  for  su_pcp  not  root,  e.g.  in   the   file
             /usr/spool/cron/crontabs/su_pcp

       The  -N  option  enables  a  ``show  me''  mode, where the
       actions are echoed, but not  executed,  in  the  style  of
       ``make  -n''.   Using  -N in conjunction with -V maximizes
       the diagnostic capabilities for debugging.

       The script $PCP_BINADM_DIR/pmlogger_daily could be  copied
       and  modified  to  implement a site-specific procedure for
       end-of-week and/or end-of-month management for  a  set  of
       PCP archives.


FILES

       $PCP_VAR_DIR/config/pmlogger/control
                 the PCP logger control file
                 Warning:  this file is a potential security risk
                 and should not be writable  by  any  user  other
                 than root.

       $PCP_VAR_DIR/config/pmlogger/crontab
                 sample crontab for automated script execution by
                 root

       $PCP_VAR_DIR/config/pmlogger/config.default
                 default  pmlogger  configuration  file  for  the
                 local primary logger

       $PCP_VAR_DIR/config/pmlogger/config.*
                 other  pmlogger  configuration  files suited for
                 particular PCP monitoring tools, add-on products
                 and application environments

                 default  location  for  archives  of performance
                 information collected from the host hostname

       $PCP_LOG_DIR/pmloggerhostname/lock
                 transient lock file to guarantee  mutual  exclu­
                 sion during pmlogger administration for the host
                 hostname - if present, can be safely removed  if
                 neither  pmlogger_daily  nor  pmlogger_check are
                 running

       $PCP_LOG_DIR/pmloggerhostname/Latest
                 PCP archive folio created  by  mkaf(1)  for  the
                 most  recently  launched archive containing per­
                 formance metrics from the host hostname

       $PCP_LOG_DIR/NOTICES
                 PCP ``notices'' file used by pmie(1) and friends


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


SEE ALSO

       compress(1), cron(1), egrep(1),  PCP(1),  pmlc(1),  pmlog­
       ger(1), pmlogmerge(1), pmnewlog(1) and pmsocks(1).


Man(1) output converted with man2html