Ubuntu Manpage: pmnewlog - stop and restart archive logging for PCP performance metrics

NAME

       pmnewlog - stop and restart archive logging for PCP performance metrics

SYNOPSIS

       $PCP_BINADM_DIR/pmnewlog  [-NPsV?]   [-a  accessfile]  [-c configfile] [-C saveconfig] [-n
       pmnsfile] [-p pid] [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).

OPTIONS

       The available command line options are:

       -a file, --access=file
            Specify access controls file for the new pmlogger.

       -c file, --config=file
            Load configuration from file.

       -C file, --save=file
            Save the configuration of new pmlogger in file.

       -n pmnsfile, --namespace=pmnsfile
            Load an alternative Performance Metrics Name Space (PMNS(5)) from the file pmnsfile.

       -N, --showme
            Perform a dry run.

       -p PID, --pid=PID
            Restart non-primary logger with PID PID.

       -P, --primary
            Execute as primary logger instance.

       -s, --socks
            Use pmsocks(1) to connect.

       -V, --verbose
            Use verbose reporting.

       -?, --help
            Display usage message and exit.

EXAMPLES

       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

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.

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.

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

       SaveLogs
            if  this directory exists within the directory that the archive files will be created
            by a new pmlogger(1) then the log file (from pmlogger's -l argument) will  be  linked
            into  the  SaveLogs  directory  with the name archive.log so it can be inspected at a
            later time.  Because the cron-driven PCP archive management scripts run under the uid
            of the user ``pcp'', SaveLogs typically needs to be owned by the user ``pcp''.

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