xenial (1) pmnewlog.1.gz

Provided by: pcp_3.10.8build1_amd64 bug

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.