1PMLOGGER(1) General Commands Manual PMLOGGER(1)
2
6 pmlogger - create archive log for performance metrics
7
9 pmlogger [-CNLoPruy?] [-c conffile] [-h host] [-H hostname] [-K spec]
10 [-l logfile] [-m note] [-n pmnsfile] [-p pid] [-s endsize] [-t inter‐
11 val] [-T endtime] [-U username] [-v volsize] [-V version] [-x fd] ar‐
12 chive
13
15 pmlogger creates the archive logs of performance metric values that may
16 be ``played back'' by other Performance Co-Pilot (see PCPIntro(1))
17 tools. These logs form the basis of the VCR paradigm and retrospective
18 performance analysis services common to the PCP toolkit.
19 The mandatory argument archive is the base name for the physical files
21 that constitute an archive log. The archive argument may contain strf‐
22 time(3) meta-characters, which will be substituted prior to creating
23 the archive log files. When pmlogger is run as a service (see pmlog‐
24 ger_daily(1)), the standard archive base name template is %Y%m%d.%H.%M.
25 The -V option specifies the version for the archive that is generated.
27 By default a version 2 archive is generated, and the only value cur‐
28 rently supported for version is 2.
29 Unless directed to another host by the -h option or when directly using
31 PMDAs via the -o option, pmlogger will contact the Performance Metrics
32 Collector Daemon (PMCD) on the local host and use that as the source of
33 the metric values to be logged.
34 To support the required flexibility and control over what is logged and
36 when, pmlogger maintains an independent two level logging state for
37 each instance of each performance metric. At the first (mandatory)
38 level, logging is allowed to be on (with an associated interval between
39 samples), or off or maybe. In the latter case, the second (advisory)
40 level logging is allowed to be on (with an associated interval between
41 samples), or off.
42 The mandatory level allows universal specification that some metrics
44 must be logged, or must not be logged. The default state for all
45 instances of all metrics when pmlogger starts is mandatory maybe and
46 advisory off.
47 Use pmlc(1) to interrogate and change the logging state once pmlogger
49 is running.
50 If a metric's state is mandatory (on or off) and a request is made to
52 change it to mandatory maybe, the new state is mandatory maybe and
53 advisory off. If a metric's state is already advisory (on or off) and
54 a request is made to change it to mandatory maybe, the current state is
55 retained.
56 It is not possible for pmlogger to log specific instances of a metric
58 and all instances of the same metric concurrently. If specific
59 instances are being logged and a request to log all instances is made,
60 then all instances of the metric will be logged according to the new
61 request, superseding any prior logging request for the metric. A
62 request to log all instances of a metric will supersede any previous
63 request to log all instances. A request to log specific instances of a
64 metric when all instances are already being logged is refused. To do
65 this one must turn off logging for all instances of the metric first.
66 In each case, the validity of the request is checked first; for example
67 a request to change a metric's logging state to advisory on when it is
68 currently mandatory off is never permitted (it is necessary to change
69 the state to mandatory maybe first).
70 Optionally, each system running pmcd(1) may also be configured to run a
72 ``primary'' pmlogger instance. This pmlogger instance is launched by
73 $PCP_RC_DIR/pmlogger, and is affected by the files
74 $PCP_SYSCONF_DIR/pmlogger/control, $PCP_SYSCONF_DIR/pmlogger/control.d
75 (use chkconfig(8), systemctl(1) or similar platform-specific commands
76 to activate or disable the primary pmlogger instance), $PCP_SYSCON‐
77 FIG_DIR/pmlogger (environment variable settings for the primary pmlog‐
78 ger) $PCP_SYSCONF_DIR/pmlogger/pmlogger.options (command line options
79 passed to the primary pmlogger) and $PCP_VAR_DIR/config/pmlogger/con‐
80 fig.default (the default initial configuration file for the primary
81 pmlogger).
82 The primary pmlogger instance is identified by the -P option. There
84 may be at most one ``primary'' pmlogger instance on each system. The
85 primary pmlogger instance (if any) must be running on the same host as
86 the pmcd(1) to which it connects (if any), so the -h and -P options are
87 mutually exclusive.
88 Logging of some metrics is possible even in the absence of a local
90 pmcd(1), using the "local context" mode of operation. This is acti‐
91 vated using the -o option, and causes pmlogger to make use of local DSO
92 PMDAs instead of communicating with pmcd(1). When operating using a
93 local context, the -K option may be used to control the DSO PMDAs that
94 should be made accessible. The spec argument conforms to the syntax
95 described in pmSpecLocalPMDA(3). More than one -K option may be used.
96 When launched as a non-primary instance, pmlogger will exit immediately
98 if the configuration file causes no metric logging to be scheduled.
99 The -L option overrides this behavior, and causes a non-primary pmlog‐
100 ger instance to ``linger'', presumably pending some future dynamic re-
101 configuration and state change via pmlc(1). pmlogger will also linger
102 without the -L option being used if all the metrics to be logged are
103 logged as once only metrics. When the once only metrics have been
104 logged, a warning message will be generated stating that the event
105 queue is empty and no more events will be scheduled.
106 By default all diagnostics and errors from pmlogger are written to the
108 file pmlogger.log in the directory where pmlogger is launched. The -l
109 option may be used to override the default behavior. If the log file
110 cannot be created or is not writable, output is written to standard
111 error instead. If the logfile for the -l option is "-" (i.e. -l-)
112 then log messages are written to the standard output stream. This can
113 be particularly useful when running pmlogger manually, rather than as a
114 service daemon.
115 The -N option directs pmlogger to notify a service manager, typically
117 systemd(1), when it has started and is about to begin writing PCP ar‐
118 chive logs. This option would only normally be used when pmlogger is
119 run as a daemon service under the control of a service manager. For
120 more details, see __pmServerNotifyServiceManagerReady(3) and sys‐
121 temd(1). On platforms that do not use a service manager that supports
122 notifications, the -N option is basically a no-op.
123 If specified, the -s option instructs pmlogger to terminate after a
125 certain size in records, bytes or time units has been accumulated. If
126 endsize is an integer then endsize records will be written to the log.
127 If endsize is an integer suffixed by b or bytes then endsize bytes of
128 the archive data will be written out (note, however, that archive log
129 record boundaries will not be broken and so this limit may be slightly
130 surpassed). Other viable file size units include: K, Kb, KiB, Kbyte,
131 Kilobyte for kilobytes and M, Mb, MiB, Mbyte, Megabyte for megabytes
132 and G, Gb, GiB, Gbyte, Gigabyte for gigabytes. These units may be
133 optionally suffixed by an s and may be of mixed case. Alternatively
134 endsize may be an integer or a floating point number suffixed using a
135 time unit as described in PCPIntro(1) for the interval argument (to the
136 standard PCP -t command line option).
137 Some examples of different formats:
138 -s 100
139 -s 100bytes
140 -s 100K
141 -s 100Mb
142 -s 10Gbyte
143 -s 10mins
144 -s 1.5hours
145 The default is for pmlogger to run forever.
146 The -r option causes the size of the physical record(s) for each group
148 of metrics and the expected contribution of the group to the size of
149 the PCP archive for one full day of collection to be reported in the
150 log file. This information is reported the first time each group is
151 successfully written to the archive.
152 The -U option specifies the user account under which to run pmlogger.
154 The default is the current user account for interactive use. When run
155 as a daemon, the unprivileged "pcp" account is used in current versions
156 of PCP, but in older versions the superuser account ("root") was used
157 by default.
158 The log file is potentially a multi-volume data set, and the -v option
160 causes pmlogger to start a new volume after a certain size in records,
161 bytes, or time units has been accumulated for the current volume. The
162 format of this size specification is identical to that of the -s option
163 (see above). The default is for pmlogger to create a single volume
164 log. Additional volume switches can also be forced asynchronously by
165 either using pmlc(1) or sending pmlogger a SIGHUP signal (see below).
166 Note, if a scheduled volume switch is in operation due to the -v
167 option, then its counters will be reset after an asynchronous switch.
168 Independent of any -v option, each volume of an archive is limited to
170 no more than 2^31 bytes, so pmlogger will automatically create a new
171 volume for the archive before this limit is reached.
172 Normally pmlogger operates on the distributed Performance Metrics Name
174 Space (PMNS), however if the -n option is specified an alternative
175 local PMNS is loaded from the file pmnsfile.
176 Under normal circumstances, pmlogger will run forever (except for a -s
178 option or a termination signal). The -T option may be used to limit
179 the execution time using the format of time as prescribed by PCPIn‐
180 tro(1). The time is interpreted within the time zone of the PMCD
181 server, unless the -y option is given, within which case the time zone
182 at this logger host is used.
183 Some examples of different formats:
184 -T 10mins
185 -T '@ 11:30'
186 From this it can be seen that -T 10mins and -s 10mins perform identical
187 actions.
188 Alternatively, pmlogger runtime may be limited to the lifetime of
190 another process by using the -p or --PID option to nominate the PID of
191 the process of interest. In this case the pmlogger will exit when the
192 other process no longer exists.
193 When pmlogger receives a SIGHUP signal, the current volume of the log
195 is closed, and a new volume is opened. This mechanism (or the alterna‐
196 tive mechanism via pmlc(1)) may be used to manage the growth of the log
197 files - once a log volume is closed, that file may be archived without
198 ill-effect on the continued operation of pmlogger. See also the -v
199 option above.
200 When pmlogger receives a SIGUSR2 signal, the current archive log is
202 closed, and a new archive is opened. For this to succeed, the original
203 archive argument must include strftime(3) meta characters (e.g.
204 %Y%m%d.%H.%M), otherwise pmlogger will exit because the archive files
205 will already exist and pmlogger will not over-write existing archive
206 files. Note that SIGUSR2 triggers pmlogger to re-exec itself and re-
207 parse all original arguments. This means that any relative time limits
208 placed on it's termination time or sampling limit are reset and begin
209 again. This only affects relative termination times, not absolute
210 times e.g. -T 5s is affected, but -T 5pm is not.
211 Historically the buffers for the current log may be flushed to disk
213 using the flush command of pmlc(1), or by using the -u option. The
214 current version of pmlogger and the libpcp routines that underpin
215 pmlogger unconditionally use unbuffered writes and a single fwrite(3)
216 for each logical record written, and so ``flushing'' does not force any
217 additional data to be written to the file system. The -u option and
218 the pmlc(1) flush command are retained for backwards compatibility.
219 When launched with the -x option, pmlogger will accept asynchronous
221 control requests on the file descriptor fd. This option is only
222 expected to be used internally by PCP applications that support ``live
223 record mode''.
224 The -m option allows the string note to be appended to the map file for
226 this instance of pmlogger in the $PCP_TMP_DIR/pmlogger directory. This
227 is currently used internally to document the file descriptor (fd) when
228 the -x option is used, or to indicate that this pmlogger instance was
229 started under the control of pmlogger_check(1), (-m pmlogger_check) or
230 was re-exec'd (see execvp(3)) due to a SIGUSR2 signal being recieved as
231 described above (-m reexec).
232 The -H option allows the hostname written into the archive label to be
234 overridden. This mirrors the -H option of pmcd(1) , but allows it to
235 be specified on the pmlogger process. Without this option, the value
236 returned from the logged pmcd(1) is used.
237 The -C option will cause the configuration file to be parsed and pmlog‐
239 ger will then exit without creating an output archive, so when -C is
240 specified, the archive command line argument is not required. Any
241 errors in the configuration file are reported.
242
244 The configuration file may be specified with the -c option. If it is
245 not, configuration specifications are read from standard input.
246 If conffile does not exist, then a search is made in the directory
248 $PCP_VAR_DIR/config/pmlogger for a file of the same name, and if found
249 that file is used, e.g. if config.mumble does not exist in the current
250 directory and the file $PCP_VAR_DIR/config/pmlogger/config.mumble does
251 exist, then -c config.mumble and -c $PCP_VAR_DIR/config/pmlogger/con‐
252 fig.mumble are equivalent.
253 The syntax for the configuration file is as follows.
255 1. Words are separated by white space (space, tab or newline).
257 2. The symbol ``#'' (hash) introduces a comment, and all text up to
259 the next newline is ignored.
260 3. Keywords (shown in bold below) must appear literally (i.e. in
262 lower case).
263 4. Each specification begins with the optional keyword log, followed
265 by one of the states mandatory on, mandatory off, mandatory maybe,
266 advisory on or advisory off.
267 5. For the on states, a logging interval must follow using the syntax
269 ``once'', or ``default'', or ``every N timeunits'', or simply ``N
270 timeunits'' - N is an unsigned integer, and timeunits is one of
271 the keywords msec, millisecond, sec, second, min, minute, hour or
272 the plural form of one of the above.
273 Internal limitations require the interval to be smaller than
274 (approximately) 74 hours. An interval value of zero is a synonym
275 for once. An interval of default means to use the default logging
276 interval of 60 seconds; this default value may be changed to
277 interval with the -t command line option.
278 The interval argument follows the syntax described in PCPIntro(1),
280 and in the simplest form may be an unsigned integer (the implied
281 units in this case are seconds).
282 6. Following the state and possible interval specifications comes a
284 ``{'', followed by a list of one or more metric specifications and
285 a closing ``}''. The list is white space (or comma) separated.
286 If there is only one metric specification in the list, the braces
287 are optional.
288 7. A metric specification consists of a metric name optionally fol‐
290 lowed by a set of instance names. The metric name follows the
291 standard PCP naming conventions, see PMNS(5), and if the metric
292 name is a non-leaf node in the PMNS (see PMNS(5)), then pmlogger
293 will recursively descend the PMNS and apply the logging specifica‐
294 tion to all descendent metric names that are leaf nodes in the
295 PMNS. The set of instance names is a ``['', followed by a list of
296 one or more space (or comma) separated names, numbers or strings,
297 and a closing ``]''. Elements in the list that are numbers are
298 assumed to be internal instance identifiers, other elements are
299 assumed to be external instance identifiers - see pmGetInDom(3)
300 for more information.
301 If no instances are given, then the logging specification is
303 applied to all instances of the associated metric.
304 8. There may be an arbitrary number of logging specifications.
306 9. As of PCP version 4.0 and later, any metric name specification
308 that does not resolve to a leaf node in the PMNS is added to an
309 internal list of possible dynamic subtree roots. PMDAs can dynam‐
310 ically create new metrics below a dynamic root node in their PMNS,
311 and send a notification to clients that the PMNS has changed, see
312 pmdaExtSetFlags(3) and in particular the METRIC CHANGES section
313 for API details. This mechanism is currently supported by
314 pmdaopenmetrics(1) and pmdammv(1). When a fetch issued by pmlog‐
315 ger returns with the PMDA_EXT_NAMES_CHANGE flag set, pmlogger will
316 traverse the internal list of possible dynamic subtree nodes and
317 dynamically discover any new metrics. In effect, as of PCP ver‐
318 sion 4.0 and later, pmlogger can be configured to dynamically log
319 new metrics that appear in the future, after the configuration
320 file is initially parsed.
321 10. Following all of the logging specifications, there may be an
323 optional access control section, introduced by the literal token
324 [access]. Thereafter come access control rules that allow or dis‐
325 allow operations from particular hosts or groups of hosts.
326 The operations may be used to interrogate or control a running
328 pmlogger using pmlc(1) and fall into the following classes:
329 enquire interrogate the status of pmlogger and the metrics
331 it is logging
332 advisory Change advisory logging.
333 mandatory Change mandatory logging.
334 all All of the above.
335 Access control rules are of the form ``allow hostlist : opera‐
337 tionlist ;'' and ``disallow hostlist : operationlist ;''.
338 The hostlist follows the syntax and semantics for the access con‐
340 trol mechanisms used by PMCD and are fully documented in pmcd(1).
341 An operationslist is a comma separated list of the operations
342 advisory, mandatory, enquire and all.
343 A missing [access] section allows all access and is equivalent to
345 allow * : all;.
346 The configuration (either from standard input or conffile) is initially
348 scanned by pmcpp(1) with the options -rs and -I $PCP_VAR_DIR/con‐
349 fig/pmlogger. This extends the configuration file syntax with include
350 file processing (%include), a common location to search for include
351 files ($PCP_VAR_DIR/config/pmlogger), macro definitions (%define),
352 macro expansion (%name and %{name}) and conditional inclusion of lines
353 (%ifdef name ... %else ... %endif and %ifndef name ... %else ...
354 %endif).
355
357 The available command line options are:
358 -c conffile, --config=conffile
360 Specify the conffile file to use.
361 -C, --check
363 Parse configuration and exit.
364 -h host, --host=host
366 Fetch performance metrics from pmcd(1) on host, rather than from
367 the default localhost.
368 -l logfile, --log=logfile
370 Write all diagnostics to logfile instead of the default pmlog‐
371 ger.log.
372 -L, --linger
374 Run even if not the primary logger instance and nothing to log.
375 -K spec, --spec-local=spec
377 When fetching metrics from a local context (see -o), the -K option
378 may be used to control the DSO PMDAs that should be made accessi‐
379 ble. The spec argument conforms to the syntax described in
380 pmSpecLocalPMDA(3). More than one -K option may be used.
381 -m note, --note=note
383 Append note to the port map file for this instance.
384 -o, --local-PMDA
386 Use a local context to collect metrics from DSO PMDAs on the local
387 host without PMCD. See also -K.
388 -n pmnsfile, --namespace=pmnsfile
390 Load an alternative Performance Metrics Name Space (PMNS(5)) from
391 the file pmnsfile.
392 -p PID, --PID=PID
394 Log specified metrics for the lifetime of the pid PID.
395 -P, --primary
397 Run as primary logger instance. See above for more detailed
398 description of this.
399 -r, --report
401 Report record sizes and archive growth rate.
402 -s endsize, --size=endsize
404 Terminate after log size exceeds endsize.
405 -t interval, --interval=interval
407 Specify the logging interval. The default value is 60 seconds.
408 -T endtime, --finish=endtime
410 Specify the endtime when to end logging.
411 -u Use unbuffered output. This is the default (so this option does
413 nothing).
414 -U username, --username=username
416 When in daemon mode, run as user username.
417 -v volsize, --volsize=volsize
419 Switch log volumes after reaching log volume size volsize.
420 -V version, --version=version
422 Specify log archive version. The default and the only accepted
423 value is 2.
424 -x fd
426 Allow asynchronous control requests on the file descriptor fd.
427 -y Use local timezone instead of the timezone from the pmcd(1) host.
429 -?, --help
431 Display usage message and exit.
432
434 For each PCP utility, there is a sample pmlogger configuration file
435 that could be used to create an archive log suitable for replaying with
436 that tool (i.e. includes all of the performance metrics used by the
437 tool). For a tool named foo this configuration file is located in
438 $PCP_VAR_DIR/config/pmlogger/config.foo.
439 The following is a simple default configuration file for a primary
441 pmlogger instance, and demonstrates most of the capabilities of the
442 configuration specification language.
443 log mandatory on once { hinv.ncpu hinv.ndisk }
445 log mandatory on every 10 minutes {
446 disk.all.write
447 disk.all.read
448 network.interface.in.packets [ "et0" ]
449 network.interface.out.packets [ "et0" ]
450 nfs.server.reqs [ "lookup" "getattr" "read" "write" ]
451 }
452 log advisory on every 30 minutes {
454 environ.temp
455 pmcd.pdu_in.total
456 pmcd.pdu_out.total
457 }
458 %include "macros.default"
460 %ifdef %disk_detail
462 log mandatory on %disk_detail_freq {
463 disk.dev
464 }
465 %endif
466 [access]
468 disallow * : all except enquire;
469 allow localhost : mandatory, advisory;
470
472 The archive logs are sufficiently precious that pmlogger will not trun‐
473 cate an existing physical file. A message of the form
474 ...: "foo.index" already exists, not over-written
475 ...: File exists
476 indicates this situation has arisen. You must explicitly remove the
477 files and launch pmlogger again.
478 There may be at most one primary pmlogger instance per monitored host;
480 attempting to bend this rule produces the error:
481 pmlogger: there is already a primary pmlogger running
482 Various other messages relating to the creation and/or deletion of
484 files in $PCP_TMP_DIR/pmlogger suggest a permission problem on this
485 directory, or some feral files have appeared therein.
486
488 archive.meta
489 metadata (metric descriptions, instance domains, etc.) for the ar‐
490 chive log
491 archive.0
493 initial volume of metrics values (subsequent volumes have suffixes
494 1, 2, ...)
495 archive.index
497 temporal index to support rapid random access to the other files
498 in the archive log
499 $PCP_TMP_DIR/pmlogger
501 pmlogger maintains the files in this directory as the map between
502 the process id of the pmlogger instance and the IPC port that may
503 be used to control each pmlogger instance (as used by pmlc(1))
504 $PCP_VAR_DIR/config/pmlogger/config.default
506 default configuration file for the primary logger instance
507 launched from $PCP_RC_DIR/pmlogger
508 $PCP_VAR_DIR/config/pmlogger/config.*
510 assorted configuration files suitable for creating logs that may
511 be subsequently replayed with the PCP visualization and monitoring
512 tools
513 $PCP_ARCHIVE_DIR/<hostname>
515 Default directory for PCP archive files for performance metric
516 values collected from the host <hostname>.
517 $PCP_SYSCONFIG_DIR/pmlogger
519 additional environment variables that will be set when the primary
520 pmlogger instance executes. Only settings of the form "PMLOG‐
521 GER_VARIABLE=value" will be honoured.
522 ./pmlogger.log
524 (or $PCP_ARCHIVE_DIR/<hostname>/pmlogger.log when started automat‐
525 ically by either $PCP_RC_DIR/pmlogger or one of the pmlogger(1)
526 monitoring scripts such as pmlogger_check(1))
527 all messages and diagnostics are directed here
528
530 Normally pmlogger creates a socket to receive control messages from
531 pmlc(1) on the first available TCP/IP port numbered 4330 or higher.
532 The environment variable PMLOGGER_PORT may be used to specify an alter‐
533 native starting port number.
534 If set to the value 1, the PMLOGGER_LOCAL environment variable will
536 cause pmlogger to run in a localhost-only mode of operation, where it
537 binds only to the loopback interface.
538 The PMLOGGER_REQUEST_TIMEOUT variable may be set by applications such
540 as pmlc(1) to specify a timeout in seconds for connection requests to
541 the pmlogger control port. If not set, connections may block indefi‐
542 nitely. This variable would not normally be set by pmlogger itself.
543 The PMLOGGER_MAXPENDING variable can be set to indicate the maximum
545 length to which the queue of pending pmlc connections may grow.
546 The default sampling interval used by pmlogger can be set using the
548 PMLOGGER_INTERVAL variable (if not set, 60 seconds will be used). Both
549 the command line and directives in the configuration file will override
550 this value. It is an integer in units of seconds.
551 On platforms using systemd(1), and when the -N option is given, the
553 NOTIFY_SOCKET environment variable would normally be set by the service
554 manager prior to launching pmlogger.
555
557 Environment variables with the prefix PCP_ are used to parameterize the
558 file and directory names used by PCP. On each installation, the file
559 /etc/pcp.conf contains the local values for these variables. The
560 $PCP_CONF variable may be used to specify an alternative configuration
561 file, as described in pcp.conf(5).
562
564 PCPIntro(1), pmcd(1), pmdumplog(1), pmlc(1), pmlogger_check(1), system‐
565 ctl(1), systemd(1), execvp(3), pmSpecLocalPMDA(3), strftime(3),
566 __pmServerNotifyServiceManagerReady(3), pcp.conf(5), pcp.env(5), pmlog‐
567 ger(5), PMNS(5) and chkconfig(8).
568Performance Co-Pilot PCP PMLOGGER(1)