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_SYSCONF_DIR/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_SYSCONF_DIR/pmlogger/config.mumble does
exist, then
-c config.mumble and
-c
$PCP_SYSCONF_DIR/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.