'\"macro stdmacro
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\" Copyright (c) 2014-2020 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMLOGGER 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogger\f1 \- create an archive for performance metrics
.SH SYNOPSIS
\f3pmlogger\f1
[\f3\-CLNoPruy?\f1]
[\f3\-c\f1 \f2conffile\f1]
[\f3\-d\f1 \f2directory\f1]
[\f3\-h\f1 \f2host\f1]
[\f3\-H\f1 \f2hostname\f1]
[\f3\-I\f1 \f2version\f1]
[\f3\-K\f1 \f2spec\f1]
[\f3\-l\f1 \f2logfile\f1]
[\f3\-m\f1 \f2note\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
[\f3\-p\f1 \f2pid\f1]
[\f3\-s\f1 \f2endsize\f1]
[\f3\-t\f1 \f2interval\f1]
[\f3\-T\f1 \f2endtime\f1]
[\f3\-U\f1 \f2username\f1]
[\f3\-v\f1 \f2volsize\f1]
[\f3\-V\f1 \f2version\f1]
[\f3\-x\f1 \f2fd\f1]
\f2archive\f1
.SH DESCRIPTION
.B pmlogger
creates the archives of performance metric values
that may be ``played back'' by other Performance Co-Pilot (see
.BR PCPIntro (1))
tools.
These logs form the basis of the VCR paradigm and retrospective
performance analysis services common to the PCP toolkit.
.PP
The mandatory argument
.I archive
is the base name for the physical files that constitute
an archive.
The
.I archive
argument may contain
.BR strftime (3)
meta-characters, which will be substituted prior to creating the
archive files.
When
.B pmlogger
is run as a service (see
.BR pmlogger_daily (1)),
the standard archive base name template is
.BR %Y%m%d.%H.%M .
.PP
The
.B \-V
option specifies the version for the archive that is generated.
By default the archive version
.B $PCP_ARCHIVE_VERSION
(set to 3 in current PCP releases)
is used, and the only values
currently supported for
.I version
are 2 or 3.
.PP
Unless directed to another host by the
.B \-h
option or when directly using PMDAs via the
.B \-o
option,
.B pmlogger
will contact the Performance Metrics Collector Daemon
(PMCD) on the local host and use that as the source of the metric
values to be logged.
.PP
To support the required flexibility and control over what is logged and
when,
.B pmlogger
maintains an independent two level logging state for each instance
of each performance metric.
At the first (mandatory) level, logging is
allowed to be
.B on
(with an associated interval between samples), or
.B off
or
.BR maybe .
In the latter case, the second (advisory) level logging is allowed
to be
.B on
(with an associated interval between samples), or
.BR off .
.PP
The
mandatory level allows universal specification that some metrics must be
logged, or must
.B not
be logged.
The default state for all instances of all metrics when
.B pmlogger
starts is mandatory maybe and advisory off.
.PP
Use
.BR pmlc (1)
to interrogate and change the logging state once
.B pmlogger
is running.
.PP
If a metric's state is mandatory (on or off) and a request is made to change it
to mandatory maybe, the new state is mandatory maybe and advisory off.
If a metric's state is already advisory (on or off) and a request is made to
change it to mandatory maybe, the current state is retained.
.PP
It is not possible for
.B pmlogger
to log specific instances of a metric and all instances of the same metric
concurrently.
If specific instances are being logged and a request to log all
instances is made, then all instances of the metric will be logged according to
the new request, superseding any prior logging request for the metric.
A request to log all instances of a metric will supersede any previous request to
log all instances.
A request to log specific instances of a metric when all
instances are already being logged is refused.
To do this one must turn off logging for all instances of the metric first.
In each case, the validity of the request is checked first;
for example a request to change a metric's
logging state to advisory on when it is currently mandatory off is never
permitted (it is necessary to change the state to mandatory maybe first).
.PP
Optionally, each system running
.BR pmcd (1)
may also be configured to run a ``primary''
.B pmlogger
instance.
This
.B pmlogger
instance is launched by
.BR $PCP_RC_DIR/pmlogger ,
and is affected by the files
.BR $PCP_SYSCONF_DIR/pmlogger/control ,
.BR $PCP_SYSCONF_DIR/pmlogger/control.d/* ,
(use
.BR chkconfig (8),
.BR systemctl (1)
or similar platform-specific commands to activate or disable the primary
.B pmlogger
instance),
.B $PCP_SYSCONFIG_DIR/pmlogger
(environment variable settings for the primary
.BR pmlogger )
.B $PCP_SYSCONF_DIR/pmlogger/pmlogger.options
(command line options passed to the primary
.BR pmlogger )
and
.B $PCP_VAR_DIR/config/pmlogger/config.default
(the default initial configuration file for the primary
.BR pmlogger ).
.PP
The primary
.B pmlogger
instance is identified by the
.B \-P
option.
There may be at most one ``primary''
.B pmlogger
instance on each system.
The primary
.B pmlogger
instance (if any)
must be running on the same host as the
.BR pmcd (1)
to which it connects (if any), so the
.B \-h
and
.B \-P
options are mutually exclusive.
.PP
Logging of some metrics is possible even in the absence of a local
.BR pmcd (1),
using the "local context" mode of operation.
This is activated using the
.B \-o
option, and causes
.B pmlogger
to make use of local DSO PMDAs instead of communicating with
.BR pmcd (1).
When operating using a local context, the
.B \-K
option may be used to control the DSO PMDAs that should be
made accessible.
The
.I spec
argument conforms to the syntax described in
.BR pmSpecLocalPMDA (3).
More than one
.B \-K
option may be used.
.PP
When launched as a non-primary instance,
.B pmlogger
will exit immediately if the configuration
file causes no metric logging to be scheduled.
The
.B \-L
option overrides this behavior, and causes a non-primary
.B pmlogger
instance to ``linger'', presumably pending some future
dynamic re-configuration and state change via
.BR pmlc (1).
.B pmlogger
will also linger without the
.B \-L
option being used if all the metrics to be logged are logged
as once only metrics.
When the once only metrics have been logged,
a warning message will be generated stating
that the event queue is empty and no more events will be scheduled.
.PP
By default all diagnostics and errors from
.B pmlogger
are written to the file
.B pmlogger.log
in the directory where
.B pmlogger
is launched.
The
.B \-l
option may be used to override the default behavior.
If the log file cannot be created or is not writable, output is
written to standard error instead.
If the \f2logfile\f1 for the
.B \-l
option is "\fB\-\fP"
(i.e.
.BR \-l\- )
then log messages are written to the standard output stream.
This can be particularly useful when running
.B pmlogger
manually, rather than as a service daemon.
.PP
The
.B \-N
option directs
.B pmlogger
to notify a service manager, typically
.BR systemd (1),
when it has started and is about to begin writing PCP archives.
This option would only normally be used when
.B pmlogger
is run as a daemon service under the control of a service manager.
For more details, see
.BR __pmServerNotifyServiceManagerReady (3)
and
.BR systemd (1).
On platforms that do not use a service manager that supports notifications,
the
.B \-N
option is basically a no-op.
.PP
If specified, the
.B \-s
option instructs
.B pmlogger
to terminate after a certain size in records, bytes or time units
has been accumulated.
If
.IR endsize
is an integer then
.IR endsize
records will be written to the archive.
If
.IR endsize
is an integer suffixed by
.B b
or
.B bytes
then
.IR endsize
bytes of the archive data will be written out
(note, however, that archive record boundaries will not be broken and
so this limit may be slightly surpassed).
Other viable file size units include:
.BR K ,
.BR Kb ,
.BR KiB ,
.BR Kbyte ,
.BR Kilobyte
for kilobytes and
.BR M ,
.BR Mb ,
.BR MiB ,
.BR Mbyte ,
.BR Megabyte
for megabytes and
.BR G ,
.BR Gb ,
.BR GiB ,
.BR Gbyte ,
.BR Gigabyte
for gigabytes.
These units may be optionally suffixed by an
.B s
and may be of mixed case.
Alternatively
.IR endsize
may be an integer or a floating point number suffixed using a time unit
as described in
.BR PCPIntro (1)
for the
.I interval
argument (to the standard PCP
.BR \-t
command line option).
.nf
Some examples of different formats:
.in 1i
.B \-s 100
.B \-s 100bytes
.B \-s 100K
.B \-s 100Mb
.B \-s 10Gbyte
.B \-s 10mins
.B \-s 1.5hours
.in
.fi
The default is for
.B pmlogger
to run forever.
.PP
The
.B \-r
option causes the size of the physical record(s) for each
group of metrics and the expected contribution of
the group to the size of the PCP archive for one full day
of collection to be reported in the log file.
This information is reported the first time each group is
successfully written to the archive.
.PP
The
.B \-U
option specifies the user account under which to run
.BR pmlogger .
The default is the current user account for interactive use.
When run as a daemon, the unprivileged "pcp" account is used
in current versions of PCP, but in older versions the superuser
account ("root") was used by default.
.PP
The archive is potentially a multi-volume data set, and the
.B \-v
option causes
.B pmlogger
to start a new volume after a certain size in records, bytes,
or time units has been accumulated for the current volume.
The format of this size specification is identical to that
of the
.B \-s
option (see above).
The default is for
.B pmlogger
to create a single volume archive.
Additional volume switches can also be forced asynchronously by
either using
.BR pmlc (1)
or sending
.B pmlogger
a SIGHUP signal (see below).
Note, if a scheduled volume switch is in operation due to the
.B \-v
option, then its counters will be reset after an
asynchronous switch.
.PP
Independent of any
.B \-v
option, each volume of an archive is limited to no more than
2^31 bytes, so
.I pmlogger
will automatically create a new volume for the archive before
this limit is reached.
.PP
Normally
.B pmlogger
operates on the distributed Performance Metrics Name Space (PMNS),
however if the
.B \-n
option is specified an alternative local PMNS is loaded
from the file
.IR pmnsfile .
.PP
Under normal circumstances,
.B pmlogger
will run forever (except for a
.B \-s
option or a termination signal).
The
.B \-T
option may be used to limit the execution time using the format
of time as prescribed by
.BR PCPIntro (1).
The time is interpreted within the time zone of the PMCD server,
unless the
.B \-y
option is given, within which case the time zone at this logger
host is used.
.nf
Some examples of different formats:
.in 1i
.B \-T 10mins
.B \-T '@ 11:30'
.in
.fi
From this it can be seen that
.B \-T 10mins
and
.B \-s 10mins
perform identical actions.
.PP
Alternatively,
.B pmlogger
runtime may be limited to the lifetime of another process by using the
.B \-p
or
.B \-\-PID
option to nominate the PID of the process of interest.
In this case the
.B pmlogger
will exit when the other process no longer exists.
.PP
When
.B pmlogger
receives a
.B SIGHUP
signal, the current volume of the archive is closed, and
a new volume is opened.
This mechanism (or the alternative mechanism
via
.BR pmlc (1))
may be used to manage the growth of the archive files \- once a log volume
is closed, that file may be archived without ill-effect on the
continued operation of
.BR pmlogger .
See also the
.B \-v
option above.
.PP
When
.B pmlogger
receives a
.B SIGUSR2
signal, the current archive is closed, and
a new archive is opened.
For this to succeed, the original
.I archive
argument must include
.BR strftime (3)
meta characters
(e.g.
.BR %Y%m%d.%H.%M ),
otherwise
.B pmlogger
will exit because the archive files will already exist and
.B pmlogger
will not over-write existing archive files.
Note that
.B SIGUSR2
triggers
.B pmlogger
to re-exec itself and re-parse all original arguments.
This means that any relative time limits placed on it's termination time
or sampling limit are reset and begin again.
This only affects relative termination times, not absolute times
e.g.
.B \-T 5s
is affected, but
.B \-T 5pm
is not.
.PP
Historically the buffers for the current archive may be flushed to disk using the
\f3flush\f1 command of
.BR pmlc (1),
or by using the
.B \-u
option.
The current version of
.I pmlogger
and the
.I libpcp
routines that underpin
.I pmlogger
unconditionally use unbuffered writes and a single
.BR fwrite (3)
for each logical record written, and so ``flushing'' does not
force any additional data to be written to the file system.
The
.B \-u
option and the
.BR pmlc (1)
.B flush
command are retained for backwards compatibility.
.PP
When launched with the
.B \-x
option, pmlogger will accept asynchronous
control requests on the file descriptor \f2fd\f1.
This option is only
expected to be used internally by PCP applications that support ``live
record mode''.
.PP
The
.B \-m
option allows the string
.I note
to be appended to the map file for this instance of
.B pmlogger
in the
.B $PCP_TMP_DIR/pmlogger
directory.
This is currently used internally to document the file descriptor (\c
.IR fd )
when the
.B \-x
option is used, or to indicate that this
.B pmlogger
instance was started under the control of
.BR pmlogger_check (1),
(\fB\-m pmlogger_check\fP)
or was re-exec'd (see
.BR execvp (3))
due to a
.B SIGUSR2
signal being received as described above (\fB\-m reexec\fP).
.PP
The
.B \-H
option allows the hostname written into the archive label to be overridden.
This mirrors the
.B \-H
option of
.BR pmcd (1)
, but allows it to be specified on the
.B pmlogger
process.
Without this option, the value returned from the logged
.BR pmcd (1)
is used.
.PP
The
.B \-C
option will cause the configuration file to be parsed and
.I pmlogger
will then exit
without creating an output archive,
so when
.B \-C
is specified, the
.I archive
command line argument is not required.
Any errors in the configuration file are reported.
.PP
The
.B \-d
or
.B \-\-directory
option may be used to specify the directory where the
.I archive
should be created.
.I directory
may include
.BR sh (1)
metacharacters, like
.BI $( ... )
or
.BR ` ... `
or
.BI $ var
and
.B pmlogger
will expand these to produce a final directory path.
The resultant path must be absolute, not relative.
The
.B \-d
option is intended primarily for use by
.BR pmlogger_check (1)
and normal users would not typically need to use the option, as the directory
for
.I archive
is either implied by
.I archive
if it contains directory components
else the current directory by default.
.SH CONFIGURATION FILE SYNTAX
The configuration file may be specified with the
.B \-c
option.
If it is not, configuration specifications are read from standard
input.
.PP
If
.I conffile
does not exist, then a search is made in the directory
.B $PCP_VAR_DIR/config/pmlogger
for a file of the same name, and if found that file is used,
e.g. if
.B config.mumble
does not exist in the current directory and
the file
.B $PCP_VAR_DIR/config/pmlogger/config.mumble
does exist, then
.B "\-c config.mumble"
and
.B "\-c $PCP_VAR_DIR/config/pmlogger/config.mumble"
are equivalent.
.PP
The syntax for the configuration file is as follows.
.IP 1. 5n
Words are separated by white space (space, tab or newline).
.IP 2. 5n
The symbol ``#'' (hash) introduces a comment, and all text up
to the next newline
is ignored.
.IP 3. 5n
Keywords (shown in
.B bold
below) must appear literally (i.e. in lower case).
.IP 4. 5n
Each specification begins with the optional keyword
.BR log ,
followed by one of the states
.BR "mandatory on" ,
.BR "mandatory off" ,
.BR "mandatory maybe" ,
.BR "advisory on"
or
.BR "advisory off" .
.IP 5. 5n
For the
.B on
states, a logging interval must follow using the syntax ``\c
.BR once '',
or ``\c
.BR default '',
or ``\c
.B every
.IR "N timeunits" '',
or simply ``\c
.IR "N timeunits" ''
\-
.I N
is an unsigned integer, and
.I timeunits
is one of the keywords
.BR msec ,
.BR millisecond ,
.BR sec ,
.BR second ,
.BR min ,
.BR minute ,
.BR hour
or the plural form of one of the above.
.sp 0.5v
Internal limitations require the
interval
to be smaller than (approximately)
74 hours.
An interval
value of zero is a synonym for
.BR once .
An interval of
.B default
means to use the default logging interval of
60 seconds; this default value may be changed to
.I interval
with the
.B \-t
command line option.
.IP ""
The
.I interval
argument follows the syntax described in
.BR PCPIntro (1),
and in the simplest form may be an unsigned integer (the implied
units in this case are seconds).
.IP 6. 5n
Following the state and possible interval specifications comes
a ``{'', followed by a list of one or more metric specifications
and a closing ``}''.
The list is white space (or comma) separated.
If there is only one metric specification in the list, the braces are optional.
.IP 7. 5n
A metric specification consists of a metric name optionally
followed by a set of instance names.
The metric name follows the standard PCP naming conventions, see
.BR PMNS (5),
and if the metric name
is a non-leaf node in the PMNS (see \c
.BR PMNS (5)),
then
.B pmlogger
will recursively descend the PMNS and apply the logging specification
to all descendent metric names that are leaf nodes in the PMNS.
The set of instance names
is a ``['', followed by a list
of one or more space (or comma) separated
names, numbers or strings, and a closing ``]''.
Elements in the list that are numbers are assumed to be
internal instance identifiers, other elements are assumed to
be external instance identifiers \- see
.BR pmGetInDom (3)
for more information.
.RS
.PP
If no instances are given, then the logging specification
is applied to all instances of the associated metric.
.RE
.IP 8. 5n
There may be an arbitrary number of logging specifications.
.IP 9. 5n
As of PCP version 4.0 and later, any metric name specification
that does not resolve to a leaf node in the PMNS is added to an
internal list of possible
.IR "dynamic subtree roots" .
PMDAs can dynamically create new metrics below a dynamic root node
in their PMNS, and send a notification to clients that the PMNS
has changed, see
.BR pmdaExtSetFlags (3)
and in particular the
.B "METRIC CHANGES"
section for API details.
This mechanism is currently supported by
.BR pmdaopenmetrics (1)
and
.BR pmdammv (1) .
When a fetch issued by
.B pmlogger
returns with the
.B PMDA_EXT_NAMES_CHANGE
flag set,
.B pmlogger
will traverse the internal list of possible dynamic subtree nodes
and dynamically discover any new metrics.
In effect,
as of PCP version 4.0 and later,
.B pmlogger
can be configured to dynamically log new metrics that appear in the future,
after the configuration file is initially parsed.
.IP 10. 5n
Following all of the logging specifications, there may be an optional
access control section, introduced by the literal token
.BR [access] .
Thereafter come access control rules that allow or disallow operations
from particular hosts or groups of hosts.
.RS 5n
.PP
The operations may be used to interrogate or control a running
.B pmlogger
using
.BR pmlc (1)
and fall into the following classes:
.TP 15
.B enquire
interrogate the status of
.B pmlogger
and the metrics it is logging
.PD 0
.TP 15
.B advisory
Change advisory logging.
.TP 15
.B mandatory
Change mandatory logging.
.TP
.B all
All of the above.
.PD
.PP
Access control rules are of the form ``\c
.B allow
.I hostlist
.B :
.I operationslist
.BR ; ''
and ``\c
.B disallow
.I hostlist
.B :
.I operationslist
.BR ; ''.
.PP
The
.I hostlist
follows the syntax and semantics for the access control mechanisms
used by PMCD and are fully documented in
.BR pmcd (1).
An
.I operationslist
is a comma separated list of the operations
.BR advisory ,
.BR mandatory ,
.B enquire
and
.BR all .
.PP
A missing
.BR [access]
section allows all access and is equivalent to
.BR "allow * : all;" .
.RE
.PP
The configuration (either from standard input or
.IR conffile )
is initially scanned by
.BR pmcpp (1)
with the options
.B \-rs
and
\fB\-I $PCP_VAR_DIR/config/pmlogger\fR.
This extends the configuration file syntax with include file
processing (\c
.BR %include ),
a common location to search for include files
(\fB$PCP_VAR_DIR/config/pmlogger\fR),
macro definitions (\c
.BR %define ),
macro expansion (\c
.BI % name
and
.BR %{ \fIname\fP } )
and conditional inclusion of lines
(\fB%ifdef \fIname\fR ... \fB%else\fR ... \fB%endif\fR and
\fB%ifndef \fIname\fR ... \fB%else\fR ... \fB%endif\fR).
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-c\fR \fIconffile\fR, \fB\-\-config\fR=\fIconffile\fR
Specify the
.I conffile
file to use.
.TP
\fB\-C\fR, \fB\-\-check\fR
Parse configuration and exit.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
Fetch performance metrics from
.BR pmcd (1)
on
.IR host ,
rather than from the default localhost.
.TP
\fB\-H\fR \fIhostname\fR, \fB\-\-labelhost\fR=\fIhostname\fR
Specify the
.I hostname
to use instead of the one returned by
.BR pmcd (1).
.TP
\fB\-I\fR \fIversion\fR, \fB\-\-pmlc-ipc-version\fR=\fIversion\fR
Normally,
.B pmlogger
and
.BR pmlc (1)
will autonegotiate a mutually acceptable version for their
private IPC channel.
Use
.B \-I
to force
.B pmlogger
to offer (at most)
.I version
as the version to be used.
This option may be required if
.B pmlogger
needs to be managed by an older version of
.BR pmlc (1)
that fails to autonegotiate correctly.
.TP
\fB\-K\fR \fIspec\fR, \fB\-\-spec\-local\fR=\fIspec\fR
When fetching metrics from a local context (see
.BR \-o ),
the
.B \-K
option may be used to control the DSO PMDAs that should be made accessible.
The
.I spec
argument conforms to the syntax described in
.BR pmSpecLocalPMDA (3).
More than one
.B \-K
option may be used.
.TP
\fB\-l\fR \fIlogfile\fR, \fB\-\-log\fR=\fIlogfile\fR
Write all diagnostics to
.B logfile
instead of the default
.BR pmlogger.log .
.TP
\fB\-L\fR, \fB\-\-linger\fR
Run even if not the primary logger instance and nothing to log.
.TP
\fB\-m\fR \fInote\fR, \fB\-\-note\fR=\fInote\fR
Append
.I note
to the port map file for this instance.
.TP
\fB\-n\fR \fIpmnsfile\fR, \fB\-\-namespace\fR=\fIpmnsfile\fR
Load an alternative Performance Metrics Name Space
.RB ( PMNS (5))
from the file
.IR pmnsfile .
.TP
\fB\-N\fR, \fB\-\-notify\fR
Notify service manager such as
.BR systemd(1)
as needed.
.TP
\fB\-o\fR, \fB\-\-local\-PMDA\fR
Use a local context to collect metrics from DSO PMDAs on the local host
without PMCD.
See also
.BR \-K .
.TP
\fB\-p\fR \fIPID\fR, \fB\-\-PID\fR=\fIPID\fR
Log specified metrics for the lifetime of the pid
.IR PID .
.TP
\fB\-P\fR, \fB\-\-primary\fR
Run as primary logger instance.
See above for more detailed description of this.
.TP
\fB\-r\fR, \fB\-\-report\fR
Report record sizes and archive growth rate.
.TP
\fB\-s\fR \fIendsize\fR, \fB\-\-size\fR=\fIendsize\fR
Terminate after archive size exceeds
.IR endsize .
.TP
\fB\-t\fR \fIinterval\fR, \fB\-\-interval\fR=\fIinterval\fR
Specify the logging
.IR interval .
The default value is 60 seconds.
Please refer to the
.B ENVIRONMENT
and
.B FILES
sections below regarding the
.B PMLOGGER_INTERVAL
environment variable and its impact on the default logging interval.
.TP
\fB\-T\fR \fIendtime\fR, \fB\-\-finish\fR=\fIendtime\fR
Specify the
.I endtime
when to end logging.
.TP
\fB\-u\fR
Use unbuffered output.
This is the default (so this option does nothing).
.TP
\fB\-U\fR \fIusername\fR, \fB\-\-username\fR=\fIusername\fR
When in daemon mode, run as user
.IR username .
.TP
\fB\-v\fR \fIvolsize\fR, \fB\-\-volsize\fR=\fIvolsize\fR
Switch volumes after reaching archive volume size
.IR volsize .
.TP
\fB\-V\fR \fIversion\fR, \fB\-\-version\fR=\fIversion\fR
Specify archive
.IR version .
The default and the only accepted value is 2.
.TP
\fB\-x\fR \fIfd\fR
Allow asynchronous control requests on the file descriptor
.IR fd .
.TP
\fB\-y\fR
Use local timezone instead of the timezone from the
.BR pmcd (1)
host.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH EXAMPLES
For each PCP utility, there is a sample
.B pmlogger
configuration file that could be used to create an archive suitable
for replaying with that tool (i.e. includes all of the performance
metrics used by the tool).
For a tool named
.I foo
this configuration file is located in
.BR $PCP_VAR_DIR/config/pmlogger/config.foo .
.PP
The following is a simple default configuration file for a primary
.B pmlogger
instance, and demonstrates most of the capabilities of the
configuration specification language.
.PP
.in +0.5i
.nf
.ft CR
log mandatory on once { hinv.ncpu hinv.ndisk }
log mandatory on every 10 minutes {
    disk.all.write
    disk.all.read
    network.interface.in.packets [ "et0" ]
    network.interface.out.packets [ "et0" ]
    nfs.server.reqs [ "lookup" "getattr" "read" "write" ]
}

log advisory on every 30 minutes {
    environ.temp
    pmcd.pdu_in.total
    pmcd.pdu_out.total
}

%include "macros.default"

%ifdef %disk_detail
log mandatory on %disk_detail_freq {
    disk.dev
}
%endif

[access]
disallow * : all except enquire;
allow localhost : mandatory, advisory;
.ft R
.fi
.in
.SH HOSTNAME CHANGES
The hostname of the PMCD that is providing metrics to
.B pmlogger
is used in several ways.
.PP
PMCD's hostname
(or the argument from the
.B \-H
option)
is included in the archive label and may be used to ensure that subsequent
operations on multiple archives, e.g. \c
.BR pmlogextract (1),
are only applied to archives from the same host.
.PP
For
.B pmlogger
instances using a local PMCD that are launched and managed by
.BR pmlogger_check (1)
and
.BR pmlogger_daily (1),
(or the
.BR systemd (1)
or
.BR cron (8)
services that use these scripts), the local hostname may also
be used to construct the name of a directory where all the archives for the
one host are stored, e.g. \c
.BR $PCP_ARCHIVE_DIR/\fI<hostname>\fB .
.PP
And PMCD's hostname is also stored in the archive via the
.B pmcd.pmlogger.hostname
metric that is used as part of the checks to ensure that there is
continuity of performance data after the nightly archive rotation by
.BR pmlogger_daily (1).
.PP
The hostname of the PMCD host may change during boot time when the system
transitions from a temporary hostname to a persistent hostname, or by
explicit administrative action anytime after the system has been booted.
When this happens,
.B pmlogger
may need to take special action, specifically if the
.B pmlogger
instance was launched from
.BR pmlogger_check (1)
or
.BR pmlogger_daily (1),
then
.B pmlogger
must exit.  Under normal circumstances
.BR systemd (1)
or
.BR cron (8)
will launch a new
.B pmlogger
shortly thereafter, and this new
.B pmlogger
instance will be operating in the context of the new
hostname for the host where PMCD is running.
.SH DERIVED METRICS
As described in
.BR pmRegisterDerived (3),
derived metrics provide a mechanism for extending the
PMNS with new metrics defined at the PCP client-side using expressions
over the existing performance metrics.
Derived metrics may be included in a
.B pmlogger
configuration file, but they come with some special handling rules.
.PP
First, the values of a derived metric,
.B not
the operand metrics in the derived metric's expression, are
stored in the archive.
This is because the definition of a derived metric exists
independent of
.B pmlogger
and
.I archive
and may be different, or not exist at all, when
.I archive
is replayed.
.PP
To avoid ambiguity during archive replay
each derived metric's
Performance Metric Identifier (PMID) is rewritten (or ``remapped'')
to indicate that this was, but now is \fInot\fP, a derived metric;
refer to
.BR pmRegisterDerived (3)
for a detailed description of the PMID remapping.
.SH DIAGNOSTICS
The archives are sufficiently precious that
.B pmlogger
will not truncate an existing physical file.
A message of the form
.br
.in +0.5v
\&...: "foo.index" already exists, not over-written
.br
\&...: File exists
.in
indicates this situation has arisen.
You must explicitly remove
the files and launch
.B pmlogger
again.
.PP
There may be at most one primary
.B pmlogger
instance per monitored host; attempting to bend this rule produces the error:
.br
.in +0.5v
pmlogger: there is already a primary pmlogger running
.in
.PP
Various other messages relating to the creation and/or deletion of
files in
.B $PCP_TMP_DIR/pmlogger
suggest a permission problem on this directory, or some feral
files have appeared therein.
.SH FILES
.TP 5
\f2archive\f3.meta
metadata (metric descriptions, instance domains, etc.) for the archive
.TP
\f2archive\f3.0
initial volume of metrics values (subsequent volumes have suffixes
.BR 1 ,
.BR 2 ,
\&...)
.TP
\f2archive\f3.index
temporal index to support rapid random access to the other files in the
archive
.TP
.B $PCP_TMP_DIR/pmlogger
.B pmlogger
maintains the files in this directory as the map between the
process id of the
.B pmlogger
instance and the IPC port that may be used to control each
.B pmlogger
instance (as used by
.BR pmlc (1))
.TP
.B $PCP_VAR_DIR/config/pmlogger/config.default
default configuration file for the primary logger instance
launched from
.B $PCP_RC_DIR/pmlogger
.TP
.B $PCP_VAR_DIR/config/pmlogger/config.*
assorted configuration files suitable for creating logs that may
be subsequently replayed with the PCP visualization and monitoring
tools
.TP
.B $PCP_ARCHIVE_DIR/\fI<hostname>\fB
Default directory for PCP archive files for performance
metric values collected from the host
.IR <hostname> .
.TP
.B $PCP_SYSCONFIG_DIR/pmlogger
additional environment variables that will be set when the primary
.B pmlogger
instance executes.
Only settings of the form "PMLOGGER_VARIABLE=value" will be honoured.
.TP
.B \&./pmlogger.log
(or
.B $PCP_ARCHIVE_DIR/\fI<hostname>\fB/pmlogger.log
when started automatically by either
.B $PCP_RC_DIR/pmlogger
or one of the
.BR pmlogger (1)
monitoring scripts such as
.BR pmlogger_check (1))
.br
all messages and diagnostics are directed here
.SH ENVIRONMENT
Normally
.B pmlogger
creates a socket to receive control messages from
.BR pmlc (1)
on the first available TCP/IP port numbered 4330 or higher.
The environment variable
.B PMLOGGER_PORT
may be used to specify an alternative starting port number.
.PP
If set to the value 1, the
.B PMLOGGER_LOCAL
environment variable will cause
.B pmlogger
to run in a localhost-only mode of operation, where it binds only
to the loopback interface.
.PP
The
.B PMLOGGER_REQUEST_TIMEOUT
variable may be set by applications such as
.BR pmlc (1)
to specify a timeout in seconds for connection requests
to the
.B pmlogger
control port.
If not set, connections may block indefinitely.
This variable would not normally be set by
.B pmlogger
itself.
.PP
The
.B PMLOGGER_MAXPENDING
variable can be set to indicate the maximum length to which the queue
of pending
.B pmlc
connections may grow.
.PP
The default sampling interval used by
.B pmlogger
can be set using the
.B PMLOGGER_INTERVAL
variable (if not set, 60 seconds will be used).
Both the command line and directives in the configuration file will
override this value.
It is an integer in units of seconds.
.PP
On platforms using
.BR systemd (1),
and when the
.B \-N
option is given,
the
.B NOTIFY_SOCKET
environment variable would normally be set by the service manager
prior to launching
.BR pmlogger .
.PP
Two additional environment variables are used as part of the
hand-off from one
.B pmlogger
instance to the next during a re-exec operation, namely
.B __PMLOGGER_REEXEC
and
.BR __PMLOGGER_TZ .
The details of how these are used is an internal implementation
detail, but end-users should avoid using variables of these
names in their shell's environment.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmlc (1),
.BR pmlogdump (1),
.BR pmlogger_check (1),
.BR pmlogger_daily (1),
.BR systemctl (1),
.BR systemd (1),
.BR PMAPI (3),
.BR __pmServerNotifyServiceManagerReady (3),
.BR execvp (3),
.BR pmRegisterDerived (3),
.BR pmSpecLocalPMDA (3),
.BR strftime (3),
.BR PMNS (5),
.BR pcp.conf (5),
.BR pcp.env (5),
.BR LOGARCHIVE (5),
.BR chkconfig (8)
and
.BR cron (8).

.\" control lines for scripts/man-spell
.\" +ok+ hinv ndisk ncpu operationslist autonegotiate
.\" +ok+ exec'd reexec getattr disk_detail_freq
.\" +ok+ hostlist reqs op {from no-op} pdu_in pdu_out
.\" +ok+ NOTIFY_SOCKET PMLOGGER_INTERVAL PMLOGGER_LOCAL PMLOGGER_MAXPENDING
.\" +ok+ PMLOGGER_PORT PMLOGGER_VARIABLE
.\" +ok+ __PMLOGGER_REEXEC __PMLOGGER_TZ