PMNEWLOG(1)						      General Commands Manual						       PMNEWLOG(1)

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  con-
       junction 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 pmlog-
	      ger(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 pmlog-
       ger_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 configura-
       tion 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 configura-
       tion  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.

Performance Co-Pilot							PCP							       PMNEWLOG(1)