PMNEWLOG(1)                General Commands Manual               PMNEWLOG(1)

NAME         top

       pmnewlog  - stop and restart archive logging for PCP performance met‐

SYNOPSIS         top

       $PCP_BINADM_DIR/pmnewlog [-a accessfile] [-C saveconfig] [-c
       configfile] [-N] [-n pmnsfile] [-P] [-p pid] [-s] [-V] [other
       pmlogger options] archive

DESCRIPTION         top

       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

       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

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

       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

       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

       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

       -x fd  The launched pmlogger cannot be controlled by

EXAMPLE         top

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

               # start new logs for PCP primary logger on this host

               # standard place for logs

               # each new log is named
               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         top

                 metadata (metric descriptions, instance domains, etc.) for
                 the archive log
       archive.0 initial volume of metrics values (subsequent volumes have
                 suffixes 1, 2, ...)
                 temporal index to support rapid random access to the other
                 files in the archive log
                 sample script to rotate archives for a number of loggers


       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         top

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

DIAGNOSTICS         top

       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         top

       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.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨git://⟩ on 2017-03-13.  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail

Performance Co-Pilot                 PCP                         PMNEWLOG(1)