1PMNEWLOG(1) General Commands Manual PMNEWLOG(1)
2
6 pmnewlog - stop and restart archive logging for PCP performance metrics
7
9 $PCP_BINADM_DIR/pmnewlog [-NPsV?] [-a accessfile] [-c configfile] [-C
10 saveconfig] [-n pmnsfile] [-p pid] [other pmlogger options] archive
11
13 pmnewlog may be used to stop and restart a running instance of pmlog‐
14 ger(1). This is most useful for managing multiple sets of Performance
15 Co-Pilot (PCP) archive logs. These archive logs record the history of
16 performance metric values that may be ``played back'' by other PCP
17 tools, and they form the basis of the VCR paradigm and retrospective
18 performance analysis services common to the PCP toolkit.
19 In normal usage, pmnewlog would be executed by cron(1) in the wee hours
21 to terminate one PCP archive log and start another, i.e. to perform log
22 rotation.
23 Even more common, would be the execution of pmnewlog from the PCP ar‐
25 chive management script pmlogger_daily(1). In this case, direct end-
26 user execution of pmnewlog is most unlikely.
27 The mandatory argument archive is the base name for the physical files
29 that will constitute the new archive log.
30 The pmlogger instance to be stopped and restarted must be running on
32 the same system as pmnewlog and is either the primary logger (the
33 default) or the logger with pid as specified by the -p option.
34 If the -n option is specified, then pmnewlog will use the namespace in
36 the pmnsfile, rather than the default Performance Metrics Name Space
37 (PMNS).
38 If no -c option is specified, pmnewlog will use pmlc(1) to connect to
40 the running pmlogger(1) and so determine all those metrics and
41 instances that are subject to mandatory logging or advisory on logging,
42 and the associated logging frequencies. This information is used to
43 synthesize a new pmlogger(1) configuration file. If the -n option is
44 specified, it will also be used for these interactions with pmlc(1).
45 If the -c option is specified, pmlogger(1) will be restarted with con‐
47 figfile as the configuration file. Normally configfile would be the
48 same configuration file used to start pmlogger(1) in the first place,
49 however note that since pmlogger(1) is restarted, any changes to the
50 logging status made using pmlc(1) will be lost, unless these have also
51 been reflected in changes to configfile.
52 If configfile does not exist, then a search is made in the directory
54 $PCP_VAR_DIR/config/pmlogger for a file of the same name, and if found
55 that file is used, e.g. if config.mumble does not exist in the current
56 directory and the file $PCP_VAR_DIR/config/pmlogger/config.mumble does
57 exist, then -c config.mumble and -c $PCP_VAR_DIR/config/pmlogger/con‐
58 fig.mumble are equivalent.
59 Access controls specifications for the new pmlogger(1) instance may
61 optionally be provided via the -a option. The contents of accessfile
62 should start with the literal token [access] and conform to the syntax
63 of the access controls section as described for pmlogger(1).
64 The -C option may be used to save the configuration file that pmnewlog
66 passes to the newly launched pmlogger(1).
67 If the pmlogger(1) instance needs to be started under the control of
69 pmsocks(1) to connect to a pmcd through a firewall, the -s option may
70 be used.
71 The -V option enables verbose reporting of the activity. By default no
73 output is generated unless some error or warning condition is encoun‐
74 tered.
75 The -N option enables a ``show me'' mode, where the actions are echoed,
77 but not executed, in the style of ``make -n''. Using -N in conjunction
78 with -V maximizes the diagnostic capabilities for debugging.
79 The other pmlogger options are as described for pmlogger(1). Note that
81 pmnewlog does not support the following options of pmlogger(1).
82 -h host
84 pmnewlog determines the host to which the new pmlogger(1) should
85 connect based upon the current host connection for the old
86 pmlogger(1).
87 -s samples
89 The new pmlogger(1) is expected to be long running, and the -s
90 option of pmnewlog takes precedence.
91 -T runtime
93 The new pmlogger(1) is expected to be long running.
94 -V version
96 The new pmlogger will always create the latest version PCP ar‐
97 chive format, and the -V option of pmnewlog takes precedence.
98 -x fd The launched pmlogger cannot be controlled by pmRecordCon‐
100 trol(3).
101
103 The available command line options are:
104 -a file, --access=file
106 Specify access controls file for the new pmlogger.
107 -c file, --config=file
109 Load configuration from file.
110 -C file, --save=file
112 Save the configuration of new pmlogger in file.
113 -n pmnsfile, --namespace=pmnsfile
115 Load an alternative Performance Metrics Name Space (PMNS(5)) from
116 the file pmnsfile.
117 -N, --showme
119 Perform a dry run.
120 -p PID, --pid=PID
122 Restart non-primary logger with PID PID.
123 -P, --primary
125 Execute as primary logger instance.
126 -s, --socks
128 Use pmsocks(1) to connect.
129 -V, --verbose
131 Use verbose reporting.
132 -?, --help
134 Display usage message and exit.
135
137 The following sh(1) script could be executed by root via cron(1) to
138 start a new set of archive logs for the primary logger each evening. A
139 more complete version of this script may be found in
140 $PCP_BINADM_DIR/pmlogger_daily, and is documented in the manual page
141 for pmlogger_daily(1).
142 #!/bin/sh
144 # start new logs for PCP primary logger on this host
145 # standard place for logs
147 LOGDIR=$PCP_LOG_DIR/pmlogger/`hostname`
148 # each new log is named yymmdd.hh.mm
150 LOGNAME=`date "+%Y%m%d.%H.%M"`
151 # do it
153 [ ! -d $LOGDIR ] && mkdir -p $LOGDIR
154 cd $LOGDIR
155 $PCP_BINADM_DIR/pmnewlog -l $LOGDIR/pmlogger.log $LOGDIR
156
158 If no configfile is specified, the method for synthesizing a configura‐
159 tion file using a pmlc(1) connection to the existing pmlogger(1) is, of
160 necessity, incomplete. In particular, for metrics with dynamic under‐
161 lying instance domains, it is not possible to identify a configuration
162 that logs all instances of a metric all of the time, so rather the syn‐
163 thesized configuration file requests the continued logging of the set
164 of instances that exist at the time pmlogger(1) is interrogated by
165 pmnewlog.
166 If this situation is a concern, a fixed configuration file should be
168 used, and passed to pmnewlog via the -c option.
169
171 Due to the precious nature of the archive logs, pmnewlog is rather
172 paranoid in its checking and validation, and will try very hard to
173 ensure that an appropriately configured pmlogger(1) can be restarted,
174 before terminating the existing pmlogger(1).
175 As a consequence of this checking, pmnewlog tends to generate rather
177 verbose error and warning messages.
178
180 archive.meta
181 metadata (metric descriptions, instance domains, etc.) for
182 the archive log
183 archive.0 initial volume of metrics values (subsequent volumes have
184 suffixes 1, 2, ...)
185 archive.index
186 temporal index to support rapid random access to the other
187 files in the archive log
188 $PCP_BINADM_DIR/pmlogger_daily
189 sample script to rotate archives for a number of loggers
190 SaveLogs if this directory exists within the directory that the ar‐
191 chive files will be created by a new pmlogger(1) then the log
192 file (from pmlogger's -l argument) will be linked into the
193 SaveLogs directory with the name archive.log so it can be
194 inspected at a later time. Because the cron-driven PCP ar‐
195 chive management scripts run under the uid of the user
196 ``pcp'', SaveLogs typically needs to be owned by the user
197 ``pcp''.
198
200 Environment variables with the prefix PCP_ are used to parameterize the
201 file and directory names used by PCP. On each installation, the file
202 /etc/pcp.conf contains the local values for these variables. The
203 $PCP_CONF variable may be used to specify an alternative configuration
204 file, as described in pcp.conf(5).
205
207 PCPIntro(1), pmcd(1), pmdumplog(1), pmlc(1), pmlogger(1), pmlog‐
208 ger_daily(1), pmsocks(1), pcp.conf(5), pcp.env(5) and PMNS(5).
209Performance Co-Pilot PCP PMNEWLOG(1)