Man Linux: Main Page and Category List

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