NAME

       pmnewlog  -  stop and restart archive logging for PCP per­
       formance 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 met­
       ric values that may be ``played back'' by other PCP tools,
       and they form the basis of the VCR paradigm and retrospec­
       tive 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 Perfor­
       mance 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 spec­
       ified, 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.  Nor­
       mally configfile would be the same configuration file used

       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 con­
       fig.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/con­
       fig/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 fire­
       wall, 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 pmlog­
       ger(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 ver­
              sion  PCP  archive  format,  and  the  -V option of


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


SEE ALSO

       PCPIntro(1), pmcd(1), pmdumplog(1), pmlc(1),  pmlogger(1),
       pmlogger_daily(1), pmsocks(1), pcp.conf(4) and pcp.env(4).


DIAGNOSTICS

       Due to the precious nature of the archive  logs,  pmnewlog
       is  rather  paranoid  in  its checking and validation, and

       ured  pmlogger(1) can be restarted, before terminating the
       existing pmlogger(1).

       As a consequence of this checking, pmnewlog tends to  gen­
       erate 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.


Man(1) output converted with man2html