Scroll to navigation

PMNEWLOG(1) General Commands Manual PMNEWLOG(1)

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

pmnewlogmay be used to stop and restart a running instance ofpmlogger(1).This is most useful for managing multiple sets ofPerformance Co-Pilot (PCP) archive logs.These archive logs record the history ofperformance metric valuesthat may be ``played back'' by other PCPtools, and theyform the basis of the VCR paradigm and retrospectiveperformance analysis services common to the PCP toolkit.

In normal usage,pmnewlogwould be executed bycron(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 ofpmnewlogfrom the PCP archive management scriptpmlogger_daily(1).In this case, direct end-user execution ofpmnewlogis most unlikely.

The mandatory argumentarchiveis the base name for the physical files that will constitutethe new archive log.

Thepmloggerinstance to be stopped and restarted must be running on the same systemaspmnewlogand is either the primary logger (the default) or the logger withpidas specified by the-poption.

If the-noption is specified, thenpmnewlogwill use the namespace in thepmnsfile,rather than the default Performance Metrics Name Space (PMNS).

If no-coption is specified,pmnewlogwill usepmlc(1)to connect to the runningpmlogger(1)and so determine all those metrics and instances that are subject tomandatorylogging oradvisory onlogging, and the associated logging frequencies.This information is used to synthesize a newpmlogger(1)configuration file.If the-noption is specified, it will also be used for these interactions withpmlc(1).

If the-coption is specified,pmlogger(1)will be restarted withconfigfileas the configuration file.Normallyconfigfilewould be the same configuration file used to startpmlogger(1)in the first place, however note that sincepmlogger(1)is restarted, any changes to the logging status madeusingpmlc(1)will be lost, unless these have also been reflected in changes toconfigfile.

Ifconfigfiledoes not exist, then a search is made in the directory$PCP_VAR_DIR/config/pmloggerfor a file of the same name, and if found that file is used,e.g. ifconfig.mumbledoes not exist in the current directory andthe file$PCP_VAR_DIR/config/pmlogger/config.mumbledoes exist, then-c config.mumbleand-c $PCP_VAR_DIR/config/pmlogger/config.mumbleare equivalent.

Access controls specifications for the newpmlogger(1)instance may optionally be provided via the-aoption.The contents ofaccessfileshould start with the literal token[access]and conform to the syntax of the access controls sectionas described forpmlogger(1).

The-Coption may be used to save the configuration file thatpmnewlogpasses to the newly launchedpmlogger(1).

If thepmlogger(1)instance needs to be started under the control ofpmsocks(1)to connect to apmcdthrough a firewall, the-soption may be used.

The-Voption enables verbose reporting of the activity.By default no output is generated unless some error or warning condition isencountered.

The-Noption enables a ``show me'' mode, where the actions are echoed,but not executed, in the style of ``make -n''.Using-Nin conjunction with-Vmaximizes the diagnostic capabilities for debugging.

Theother pmlogger optionsare as described forpmlogger(1).Note thatpmnewlogdoesnotsupport the following options ofpmlogger(1).

pmnewlogdetermines the host to which the newpmlogger(1)should connect based upon the current host connection for theoldpmlogger(1).
The newpmlogger(1)is expected to be long running, and the-soption ofpmnewlogtakes precedence.
The newpmlogger(1)is expected to be long running.
The newpmloggerwill always create the latest version PCP archive format, and the-Voption ofpmnewlogtakes precedence.
The launchedpmloggercannot be controlled bypmRecordControl(3).

OPTIONS

The available command line options are:

Specify access controls file for the new pmlogger.
Load configuration from file.
Save the configuration of new pmlogger in file.
Load an alternative Performance Metrics Name Space(PMNS(5))from the filepmnsfile.
Perform a dry run.
Restart non-primary logger with PID PID.
Execute as primary logger instance.
Usepmsocks(1)to connect.
Use verbose reporting.
-?, --help
Display usage message and exit.

EXAMPLES

The followingsh(1)scriptcould be executed by root viacron(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 forpmlogger_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 noconfigfileis specified, the method for synthesizing a configuration file usingapmlc(1)connection to the existingpmlogger(1)is, of necessity, incomplete.In particular,for metrics with dynamic underlying instance domains,it is not possible to identify a configuration that logsallinstances of a metric all of the time,so rather the synthesized configuration file requests the continued loggingof the set of instances that exist at the timepmlogger(1)is interrogated bypmnewlog.

If this situation is a concern, a fixed configuration file shouldbe used, and passed topmnewlogvia the-coption.

DIAGNOSTICS

Due to the precious nature of the archive logs,pmnewlogis rather paranoid in its checking and validation, and will try veryhard to ensure that an appropriately configuredpmlogger(1)can be restarted, before terminating the existingpmlogger(1).

As a consequence of this checking,pmnewlogtends to generate rather verbose error and warning messages.

FILES

metadata (metric descriptions, instance domains, etc.) for the archive log
initial volume of metrics values (subsequent volumes have suffixes1,2,...)
temporal index to support rapid random access to the other files in thearchive log
$PCP_BINADM_DIR/pmlogger_daily
sample script to rotate archives for a number of loggers
if this directory exists within the directory that thearchivefiles will be created by a newpmlogger(1)then the log file (frompmlogger's-largument) will be linked into theSaveLogsdirectory with the namearchive.logso it can be inspected at a later time.Because the cron-driven PCP archive management scripts run underthe uid of the user ``pcp'',SaveLogstypically needs to be owned by the user ``pcp''.

PCPENVIRONMENT

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

SEEALSO

PCPIntro(1),pmcd(1),pmdumplog(1),pmlc(1),pmlogger(1),pmlogger_daily(1),pmsocks(1),pcp.conf(5),pcp.env(5)andPMNS(5).

PCP Performance Co-Pilot