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_VAR_DIR/config/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_VAR_DIR/config/pmlogger/config.mumble  does  exist,  then  -c
       config.mumble and -c $PCP_VAR_DIR/config/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.

Performance Co-Pilot                                   PCP                                           PMNEWLOG(1)