NAME

       pmnewlog - stop and restart archive logging for PCP performance metrics

SYNOPSIS

       $PCP_BINADM_DIR/pmnewlog   [-a  accessfile]  [-C  saveconfig]  [-c  configfile]  [-N]  [-n
       pmnsfile] [-P] [-p pid] [-s] [-V] [other pmlogger options] archive

DESCRIPTION

       pmnewlog may be used to stop and restart a running instance of pmlogger(1).  This is  most
       useful  for  managing  multiple  sets  of  Performance Co-Pilot (PCP) archive logs.  These
       archive logs record the history of performance metric values that may be  ``played  back''
       by  other  PCP  tools,  and  they  form  the  basis  of the VCR paradigm and retrospective
       performance analysis services common to the PCP toolkit.

       In normal usage, pmnewlog would be executed by cron(1) in the wee hours to  terminate  one
       PCP archive log and start another, i.e. to perform log rotation.

       Even  more  common,  would  be  the  execution of pmnewlog from the PCP archive management
       script pmlogger_daily(1).  In this case, direct end-user execution  of  pmnewlog  is  most
       unlikely.

       The  mandatory  argument  archive  is  the  base  name  for  the  physical files that will
       constitute the new archive log.

       The pmlogger instance to be stopped and restarted must be running on the  same  system  as
       pmnewlog  and  is  either  the  primary  logger  (the  default)  or the logger with pid as
       specified by the -p option.

       If the -n option is specified, then pmnewlog will  use  the  namespace  in  the  pmnsfile,
       rather than the default Performance Metrics Name Space (PMNS).

       If  no  -c  option  is  specified,  pmnewlog  will  use  pmlc(1) to connect to the running
       pmlogger(1) and so determine all those metrics and instances that are subject to mandatory
       logging  or advisory on logging, and the associated logging frequencies.  This information
       is used to synthesize  a  new  pmlogger(1)  configuration  file.   If  the  -n  option  is
       specified, it will also be used for these interactions with pmlc(1).

       If  the  -c  option  is  specified,  pmlogger(1)  will be restarted with configfile as the
       configuration file.  Normally configfile would be the  same  configuration  file  used  to
       start  pmlogger(1)  in  the first place, however note that since pmlogger(1) is restarted,
       any changes to the logging status made using pmlc(1) will be lost, unless these have  also
       been reflected in changes to configfile.

       If   configfile   does   not   exist,   then   a   search   is   made   in  the  directory
       $PCP_SYSCONF_DIR/pmlogger for a file of the same name, and if found  that  file  is  used,
       e.g.   if   config.mumble   does   not  exist  in  the  current  directory  and  the  file
       $PCP_SYSCONF_DIR/pmlogger/config.mumble  does  exist,  then  -c   config.mumble   and   -c
       $PCP_SYSCONF_DIR/pmlogger/config.mumble are equivalent.

       Access controls specifications for the new pmlogger(1) instance may optionally be provided
       via the -a option.  The contents  of  accessfile  should  start  with  the  literal  token
       [access]  and  conform  to  the  syntax  of  the  access controls section as described for
       pmlogger(1).

       The -C option may be used to save the configuration file that pmnewlog passes to the newly
       launched pmlogger(1).

       If the pmlogger(1) instance needs to be started under the control of pmsocks(1) to connect
       to a pmcd through a firewall, the -s option may be used.

       The -V option enables verbose  reporting  of  the  activity.   By  default  no  output  is
       generated unless some error or warning condition is encountered.

       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  other pmlogger options are as described for pmlogger(1).  Note that pmnewlog does not
       support the following options of pmlogger(1).

       -h host
              pmnewlog determines the host to which the new pmlogger(1) should connect based upon
              the current host connection for the old pmlogger(1).

       -s samples
              The  new  pmlogger(1) is expected to be long running, and the -s option of pmnewlog
              takes precedence.

       -T runtime
              The new pmlogger(1) is expected to be long running

       -V version
              The new pmlogger will always create the latest version PCP archive format, and  the
              -V option of pmnewlog takes precedence.

       -x fd  The launched pmlogger cannot be controlled by pmRecordControl(3).

EXAMPLE

       The  following  sh(1)  script  could be executed by root via cron(1) to start a new set of
       archive logs for the primary logger each evening.  A more complete version of this  script
       may  be  found in $PCP_BINADM_DIR/pmlogger_daily, and is documented in the manual page for
       pmlogger_daily(1).

               #!/bin/sh
               # start new logs for PCP primary logger on this host

               # standard place for logs
               LOGDIR=$PCP_LOG_DIR/pmlogger/`hostname`

               # each new log is named yymmdd.hh.mm
               LOGNAME=`date "+%Y%m%d.%H.%M"`

               # do it
               [ ! -d $LOGDIR ] && mkdir -p $LOGDIR
               cd $LOGDIR
               $PCP_BINADM_DIR/pmnewlog -l $LOGDIR/pmlogger.log $LOGDIR

FILES

       archive.meta
                 metadata (metric descriptions, instance domains, etc.) for the archive log
       archive.0 initial volume of metrics values (subsequent volumes have suffixes 1, 2, ...)
       archive.index
                 temporal index to support rapid random access to the other files in the  archive
                 log
       $PCP_BINADM_DIR/pmlogger_daily
                 sample script to rotate archives for a number of loggers

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), pmdumplog(1), pmlc(1), pmlogger(1),  pmlogger_daily(1),  pmsocks(1),
       pcp.conf(5) and pcp.env(5).

DIAGNOSTICS

       Due  to  the  precious  nature  of  the  archive  logs, pmnewlog is rather paranoid in its
       checking and validation, and will try very hard to ensure that an appropriately configured
       pmlogger(1) can be restarted, before terminating the existing pmlogger(1).

       As  a  consequence  of  this checking, pmnewlog tends to generate rather verbose error and
       warning messages.

CAVEATS

       If no configfile is specified, the method for synthesizing a configuration  file  using  a
       pmlc(1)  connection  to  the  existing  pmlogger(1)  is,  of  necessity,  incomplete.   In
       particular, for metrics with dynamic underlying instance domains, it is  not  possible  to
       identify  a  configuration  that logs all instances of a metric all of the time, so rather
       the synthesized configuration file requests the continued logging of the set of  instances
       that exist at the time pmlogger(1) is interrogated by pmnewlog.

       If  this  situation is a concern, a fixed configuration file should be used, and passed to
       pmnewlog via the -c option.