Unix/Linux Go Back    


CentOS 7.0 - man page for pmnewlog (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PMNEWLOG(1)									      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 pmns-
       file] [-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 ar-
       chive 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 consti-
       tute 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 speci-
       fied 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 pmlog-
       ger(1) and so determine all those metrics and instances that are subject to mandatory log-
       ging  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 con-
       figuration 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 pmlog-
       ger(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  gener-
       ated 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 ar-
       chive 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 config-
       uration 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 check-
       ing 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 particu-
       lar, 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 synthe-
       sized 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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:16 AM.