--- name: "pmnewlog" section: "1" platform: "linux" package: "pcp" version: "4.3.2+really4.3.1-0.1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/pmnewlog" --- # pmnewlog(1) stop and restart archive logging for PCP performance metrics ## 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)](/pmlogger/1.md). 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)](/pmlogger_daily/1.md). 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)](/pmlc/1.md) to connect to the running [**pmlogger**(1)](/pmlogger/1.md) 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)](/pmlogger/1.md) configuration file. If the **-n** option is specified, it will also be used for these interactions with [**pmlc**(1)](/pmlc/1.md). If the **-c** option is specified, [**pmlogger**(1)](/pmlogger/1.md) will be restarted with *configfile* as the configuration file. Normally *configfile* would be the same configuration file used to start [**pmlogger**(1)](/pmlogger/1.md) in the first place, however note that since [**pmlogger**(1)](/pmlogger/1.md) is restarted, any changes to the logging status made using [**pmlc**(1)](/pmlc/1.md) 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 equivalent. Access controls specifications for the new [**pmlogger**(1)](/pmlogger/1.md) 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)](/pmlogger/1.md). The **-C** option may be used to save the configuration file that **pmnewlog** passes to the newly launched [**pmlogger**(1)](/pmlogger/1.md). If the [**pmlogger**(1)](/pmlogger/1.md) instance needs to be started under the control of [**pmsocks**(1)](/pmsocks/1.md) 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)](/pmlogger/1.md). Note that **pmnewlog** does **not** support the following options of [**pmlogger**(1)](/pmlogger/1.md). - **-h** *host* **pmnewlog** determines the host to which the new [**pmlogger**(1)](/pmlogger/1.md) should connect based upon the current host connection for the old [**pmlogger**(1)](/pmlogger/1.md). - **-s** *samples* The new [**pmlogger**(1)](/pmlogger/1.md) is expected to be long running, and the **-s** option of **pmnewlog** takes precedence. - **-T** *runtime* The new [**pmlogger**(1)](/pmlogger/1.md) 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)](/pmRecordControl/3.md). ## EXAMPLE The following [**sh**(1)](/sh/1.md) 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)](/pmlogger_daily/1.md). ``` #!/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 - **SaveLogs** if this directory exists within the directory that the *archive* files will be created by a new [**pmlogger**(1)](/pmlogger/1.md) then the log file (from **pmlogger**'s **-l** argument) will be linked into the **SaveLogs** directory with the name *archive***.log** so it can be inspected at a later time. Because the cron-driven PCP archive management scripts run under the uid of the user \`\`pcp'', **SaveLogs** typically needs to be owned by the user \`\`pcp''. ## 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)](/pcp.conf/5.md). ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmdumplog**(1)](/pmdumplog/1.md), [**pmlc**(1)](/pmlc/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pmlogger\_daily**(1)](/pmlogger_daily/1.md), [**pmsocks**(1)](/pmsocks/1.md), [**pcp.conf**(5)](/pcp.conf/5.md) and [**pcp.env**(5)](/pcp.env/5.md). ## 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)](/pmlogger/1.md) can be restarted, before terminating the existing [**pmlogger**(1)](/pmlogger/1.md). 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)](/pmlc/1.md) connection to the existing [**pmlogger**(1)](/pmlogger/1.md) 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)](/pmlogger/1.md) 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.