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