# pmlogger

## NAME



           **pmlogger** - create an archive for performance metrics
    


## SYNOPSIS



           **pmlogger**[**-CLNoPruy?**]  [**-c** _conffile_] [**-D** _debug_] [**-d** _directory_] [**-h**
           _host_] [**-H** _hostname_] [**-I** _version_] [**-K** _spec_] [**-l** _logfile_] [**-m** _note_]
           [**-n** _pmnsfile_] [**-p** _pid_] [**-s** _endsize_] [**-t** _interval_] [**-T** _endtime_] [**-U**
           _username_] [**-v** _volsize_] [**-V** _version_] [**-x** _fd_] [_archive_]
    


## DESCRIPTION



           **pmlogger** creates the archives of performance metric values that
           may be ``played back'' by other Performance Co-Pilot (see
           PCPIntro(1)) tools.  These logs form the basis of the VCR paradigm
           and retrospective performance analysis services common to the PCP
           toolkit.
    
           The mandatory argument _archive_ is either the base name for the
           physical files that constitute an archive on the local filesystem,
           or the remote HTTP server that will receive the logged data.
    
           The local _archive_ argument may contain strftime(3) meta-
           characters, which will be substituted prior to creating the
           archive files.  When **pmlogger** is run as a service (see
           pmlogger_daily(1)), the standard archive base name template is
           **%Y%m%d.%H.%M**.
    
           The remote _archive_ form specifies the location of the pmproxy(1)
           server to which components of the archive are sent as they are
           being generated by **pmlogger**.  The value provided must contain
           protocol, hostname and optional port, e.g.
           **http://example.com:44322 **.  This **pmproxy** server will select an
           archive name based on the start time, in a similar fashion to the
           model used by default in pmlogger_check(1).
    
           The **-V** option specifies the version for the archive that is
           generated.  By default the archive version **$PCP_ARCHIVE_VERSION**
           (set to 3 in current PCP releases) is used, and the only values
           currently supported for _version_ are 2 or 3.
    
           Unless directed to another host by the **-h** option or when directly
           using PMDAs via the **-o** option, **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.
    
           To support the required flexibility and control over what is
           logged and when, **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 **on**(with an
           associated interval between samples), or **off** or **maybe**.  In the
           latter case, the second (advisory) level logging is allowed to be
           **on**(with an associated interval between samples), or **off**.
    
           The mandatory level allows universal specification that some
           metrics must be logged, or must **not** be logged.  The default state
           for all instances of all metrics when **pmlogger** starts is mandatory
           maybe and advisory off.
    
           Use pmlc(1) to interrogate and change the logging state once
           **pmlogger** is running.
    
           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.
    
           It is not possible for **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).
    
           Optionally, each system running pmcd(1) may also be configured to
           run a ``primary'' **pmlogger** instance.  This **pmlogger** instance is
           launched by **$PCP_RC_DIR/pmlogger** , and is affected by the files
           **$PCP_SYSCONF_DIR/pmlogger/control** ,
           **$PCP_SYSCONF_DIR/pmlogger/control.d/*** , (use **chkconfig**(8),
           systemctl(1) or similar platform-specific commands to activate or
           disable the primary **pmlogger** instance),
           **$PCP_SYSCONFIG_DIR/pmlogger**(environment variable settings for the
           primary **pmlogger**) **$PCP_SYSCONF_DIR/pmlogger/pmlogger.options**
           (command line options passed to the primary **pmlogger**) and
           **$PCP_VAR_DIR/config/pmlogger/config.default**(the default initial
           configuration file for the primary **pmlogger**).
    
           The primary **pmlogger** instance is identified by the **-P** option.
           There may be at most one ``primary'' **pmlogger** instance on each
           system.  The primary **pmlogger** instance (if any) must be running on
           the same host as the pmcd(1) to which it connects (if any), so the
           **-h** and **-P** options are mutually exclusive.
    
           Logging of some metrics is possible even in the absence of a local
           pmcd(1), using the "local context" mode of operation.  This is
           activated using the **-o** option, and causes **pmlogger** to make use of
           local DSO PMDAs instead of communicating with pmcd(1).  When
           operating using a local context, the **-K** option may be used to
           control the DSO PMDAs that should be made accessible.  The _spec_
           argument conforms to the syntax described in pmSpecLocalPMDA(3).
           More than one **-K** option may be used.
    
           When launched as a non-primary instance, **pmlogger** will exit
           immediately if the configuration file causes no metric logging to
           be scheduled.  The **-L** option overrides this behavior, and causes a
           non-primary **pmlogger** instance to ``linger'', presumably pending
           some future dynamic re-configuration and state change via pmlc(1).
           **pmlogger** will also linger without the **-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.
    
           By default all diagnostics and errors from **pmlogger** are written to
           the file **pmlogger.log** in the directory where **pmlogger** is launched.
           The **-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 _logfile_ for the **-l**
           option is "**-** " (i.e.  **-l-**) then log messages are written to the
           standard output stream.  This can be particularly useful when
           running **pmlogger** manually, rather than as a service daemon.
    
           The **-N** option directs **pmlogger** to notify a service manager,
           typically systemd(1), when it has started and is about to begin
           writing PCP archives.  This option would only normally be used
           when **pmlogger** is run as a daemon service under the control of a
           service manager.  For more details, see
           __pmServerNotifyServiceManagerReady(3) and systemd(1).  On
           platforms that do not use a service manager that supports
           notifications, the **-N** option is basically a no-op.
    
           If specified, the **-s** option instructs **pmlogger** to terminate after
           a certain size in records, bytes or time units has been
           accumulated.  If _endsize_ is an integer then _endsize_ records will
           be written to the archive.  If _endsize_ is an integer suffixed by **b**
           or **bytes** then _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: **K** , **Kb** , **KiB** , **Kbyte** , **Kilobyte** for kilobytes
           and **M** , **Mb** , **MiB** , **Mbyte** , **Megabyte** for megabytes and **G** , **Gb** , **GiB** ,
           **Gbyte** , **Gigabyte** for gigabytes.  These units may be optionally
           suffixed by an **s** and may be of mixed case.  Alternatively _endsize_
           may be an integer or a floating point number suffixed using a time
           unit as described in PCPIntro(1) for the _interval_ argument (to the
           standard PCP **-t** command line option).
           Some examples of different formats:
              **-s 100**
              **-s 100bytes**
              **-s 100K**
              **-s 100Mb**
              **-s 10Gbyte**
              **-s 10mins**
              **-s 1.5hours**
           The default is for **pmlogger** to run forever.
    
           The **-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.
    
           The **-U** option specifies the user account under which to run
           **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.
    
           The archive is potentially a multi-volume data set, and the **-v**
           option causes **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 **-s** option (see above).  The default is
           for **pmlogger** to create a single volume archive.  Additional volume
           switches can also be forced asynchronously by either using pmlc(1)
           or sending **pmlogger** a SIGHUP signal (see below).  Note, if a
           scheduled volume switch is in operation due to the **-v** option, then
           its counters will be reset after an asynchronous switch.
    
           Independent of any **-v** option, each volume of an archive is limited
           to no more than 2^31 bytes, so _pmlogger_ will automatically create
           a new volume for the archive before this limit is reached.
    
           Normally **pmlogger** operates on the distributed Performance Metrics
           Name Space (PMNS), however if the **-n** option is specified an
           alternative local PMNS is loaded from the file _pmnsfile_.
    
           Under normal circumstances, **pmlogger** will run forever (except for
           a **-s** option or a termination signal).  The **-T** option may be used
           to limit the execution time using the format of time as prescribed
           by PCPIntro(1).  The time is interpreted within the time zone of
           the PMCD server, unless the **-y** option is given, within which case
           the time zone at this logger host is used.
           Some examples of different formats:
              **-T 10mins**
              **-T '@ 11:30'**
           From this it can be seen that **-T 10mins** and **-s 10mins** perform
           identical actions.
    
           Alternatively, **pmlogger** runtime may be limited to the lifetime of
           another process by using the **-p** or **--PID** option to nominate the
           PID of the process of interest.  In this case the **pmlogger** will
           exit when the other process no longer exists.
    
           When **pmlogger** receives a **SIGHUP** signal, the current volume of the
           archive is closed, and a new volume is opened.  This mechanism (or
           the alternative mechanism via 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 **pmlogger**.  See also the **-v** option above.
    
           When **pmlogger** receives a **SIGUSR2** signal, the current archive is
           closed, and a new archive is opened.  For this to succeed, the
           original _archive_ argument must include strftime(3) meta characters
           (e.g.  **%Y%m%d.%H.%M**), otherwise **pmlogger** will exit because the
           archive files will already exist and **pmlogger** will not over-write
           existing archive files.  Note that **SIGUSR2** triggers **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.  **-T 5s** is
           affected, but **-T 5pm** is not.
    
           Historically the buffers for the current archive may be flushed to
           disk using the **flush** command of pmlc(1), or by using the **-u**
           option.  The current version of _pmlogger_ and the _libpcp_ routines
           that underpin _pmlogger_ unconditionally use unbuffered writes and a
           single fwrite(3) for each logical record written, and so
           ``flushing'' does not force any additional data to be written to
           the file system.  The **-u** option and the pmlc(1) **flush** command are
           retained for backwards compatibility.
    
           When launched with the **-x** option, pmlogger will accept
           asynchronous control requests on the file descriptor _fd_.  This
           option is only expected to be used internally by PCP applications
           that support ``live record mode''.
    
           The **-m** option allows the string _note_ to be appended to the map
           file for this instance of **pmlogger** in the **$PCP_TMP_DIR/pmlogger**
           directory.  This is currently used internally to document the file
           descriptor (_fd_) when the **-x** option is used, or to indicate that
           this **pmlogger** instance was started under the control of
           pmlogger_check(1), (**-m pmlogger_check**) or was re-exec'd (see
           execvp(3)) due to a **SIGUSR2** signal being received as described
           above (**-m reexec**).
    
           The **-H** option allows the hostname written into the archive label
           to be overridden.  This mirrors the **-H** option of pmcd(1) , but
           allows it to be specified on the **pmlogger** process.  Without this
           option, the value returned from the logged pmcd(1) is used.
    
           The **-C** option will cause the configuration file to be parsed and
           _pmlogger_ will then exit without creating an output archive, so
           when **-C** is specified, the _archive_ command line argument is not
           required.  Any errors in the configuration file are reported.
    
           The **-d** or **--directory** option may be used to specify the directory
           where the _archive_ should be created.  _directory_ may include **sh**(1)
           metacharacters, like **$(**_..._**)** or **`**...**`** or **$**_var_ and **pmlogger** will
           expand these to produce a final directory path.  The resultant
           path must be absolute, not relative.  The **-d** option is intended
           primarily for use by pmlogger_check(1) and normal users would not
           typically need to use the option, as the directory for _archive_ is
           either implied by _archive_ if it contains directory components else
           the current directory by default.
    


## CONFIGURATION FILE SYNTAX



           The configuration file may be specified with the **-c** option.  If it
           is not, configuration specifications are read from standard input.
    
           If _conffile_ 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.
    
           The syntax for the configuration file is as follows.
    
           1.   Words are separated by white space (space, tab or newline).
    
           2.   The symbol ``#'' (hash) introduces a comment, and all text up
                to the next newline is ignored.
    
           3.   Keywords (shown in **bold** below) must appear literally (i.e. in
                lower case).
    
           4.   Each specification begins with the optional keyword **log** ,
                followed by one of the states **mandatory on** , **mandatory off** ,
                **mandatory maybe** , **advisory on** or **advisory off**.
    
           5.   For the **on** states, a logging interval must follow using the
                syntax ``**once** '', or ``**default** '', or ``**every** _N timeunits_ '', or
                simply ``_N timeunits_ '' - _N_ is an unsigned integer, and
                _timeunits_ is one of the keywords **msec** , **millisecond** , **sec** ,
                **second** , **min** , **minute** , **hour** or the plural form of one of the
                above.
                Internal limitations require the interval to be smaller than
                (approximately) 74 hours.  An interval value of zero is a
                synonym for **once**.  An interval of **default** means to use the
                default logging interval of 60 seconds; this default value
                may be changed to _interval_ with the **-t** command line option.
    
                The _interval_ argument follows the syntax described in
                PCPIntro(1), and in the simplest form may be an unsigned
                integer (the implied units in this case are seconds).
    
           6.   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.
    
           7.   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 PMNS(5), and if the
                metric name is a non-leaf node in the PMNS (see PMNS(5)),
                then **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 pmGetInDom(3) for more
                information.
    
                If no instances are given, then the logging specification is
                applied to all instances of the associated metric.
    
           8.   There may be an arbitrary number of logging specifications.
    
           9.   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 _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 pmdaExtSetFlags(3) and
                in particular the **METRIC CHANGES** section for API details.
                This mechanism is currently supported by pmdaopenmetrics(1)
                and pmdammv(1).  When a fetch issued by **pmlogger** returns with
                the **PMDA_EXT_NAMES_CHANGE** flag set, **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, **pmlogger** can be configured to
                dynamically log new metrics that appear in the future, after
                the configuration file is initially parsed.
    
           10.  Following all of the logging specifications, there may be an
                optional access control section, introduced by the literal
                token **[access]**.  Thereafter come access control rules that
                allow or disallow operations from particular hosts or groups
                of hosts.
    
                The operations may be used to interrogate or control a
                running **pmlogger** using pmlc(1) and fall into the following
                classes:
    
                **enquire**
                       interrogate the status of **pmlogger** and the metrics it
                       is logging
                **advisory**
                       Change advisory logging.
                **mandatory**
                       Change mandatory logging.
                **all** All of the above.
    
                Access control rules are of the form ``**allow** _hostlist_ **:**
                _operationslist_ **;** '' and ``**disallow** _hostlist_ **:**_operationslist_
                **;** ''.
    
                The _hostlist_ follows the syntax and semantics for the access
                control mechanisms used by PMCD and are fully documented in
                pmcd(1).  An _operationslist_ is a comma separated list of the
                operations **advisory** , **mandatory** , **enquire** and **all**.
    
                A missing **[access]** section allows all access and is
                equivalent to **allow * : all;**.
    
           The configuration (either from standard input or _conffile_) is
           initially scanned by pmcpp(1) with the options **-rs** and **-I**
           **$PCP_VAR_DIR/config/pmlogger**.  This extends the configuration file
           syntax with include file processing (**%include**), a common location
           to search for include files (**$PCP_VAR_DIR/config/pmlogger**), macro
           definitions (**%define**), macro expansion (**%**_name_ and **%{**_name_**}**) and
           conditional inclusion of lines (**%ifdef** _name_ ... **%else**... **%endif**
           and **%ifndef** _name_ ... **%else**... **%endif**).
    


## OPTIONS



           The available command line options are:
    
           **-c** _conffile_ , **--config** =_conffile_
                Specify the _conffile_ file to use.
    
           **-C** , **--check**
                Parse configuration and exit.
    
           **-h** _host_ , **--host** =_host_
                Fetch performance metrics from pmcd(1) on _host_ , rather than
                from the default localhost.
    
           **-H** _hostname_ , **--labelhost** =_hostname_
                Specify the _hostname_ to use instead of the one returned by
                pmcd(1).
    
           **-I** _version_ , **--pmlc-ipc-version** =_version_
                Normally, **pmlogger** and pmlc(1) will autonegotiate a mutually
                acceptable version for their private IPC channel.  Use **-I** to
                force **pmlogger** to offer (at most) _version_ as the version to
                be used.  This option may be required if **pmlogger** needs to be
                managed by an older version of pmlc(1) that fails to
                autonegotiate correctly.
    
           **-K** _spec_ , **--spec-local** =_spec_
                When fetching metrics from a local context (see **-o**), the **-K**
                option may be used to control the DSO PMDAs that should be
                made accessible.  The _spec_ argument conforms to the syntax
                described in pmSpecLocalPMDA(3).  More than one **-K** option may
                be used.
    
           **-l** _logfile_ , **--log** =_logfile_
                Write all diagnostics to **logfile** instead of the default
                **pmlogger.log**.
    
           **-L** , **--linger**
                Run even if not the primary logger instance and nothing to
                log.
    
           **-m** _note_ , **--note** =_note_
                Append _note_ to the port map file for this instance.
    
           **-n** _pmnsfile_ , **--namespace** =_pmnsfile_
                Load an alternative Performance Metrics Name Space (PMNS(5))
                from the file _pmnsfile_.
    
           **-N** , **--notify**
                Notify service manager such as systemd(1) as needed.
    
           **-o** , **--local-PMDA**
                Use a local context to collect metrics from DSO PMDAs on the
                local host without PMCD.  See also **-K**.
    
           **-p** _PID_ , **--PID** =_PID_
                Log specified metrics for the lifetime of the process
                identified by _PID_.
    
           **-P** , **--primary**
                Run as primary logger instance.  See above for more detailed
                description of this.
    
           **-r** , **--report**
                Report record sizes and archive growth rate.
    
           **-s** _endsize_ , **--size** =_endsize_
                Terminate after archive size exceeds _endsize_.
    
           **-t** _interval_ , **--interval** =_interval_
                Specify the logging _interval_.  The default value is 60
                seconds.  Please refer to the **ENVIRONMENT** and **FILES** sections
                below regarding the **PMLOGGER_INTERVAL** environment variable
                and its impact on the default logging interval.
    
           **-T** _endtime_ , **--finish** =_endtime_
                Specify the _endtime_ when to end logging.
    
           **-u** Use unbuffered output.  This is the default (so this option
                does nothing).
    
           **-U** _username_ , **--username** =_username_
                When in daemon mode, run as user _username_.
    
           **-v** _volsize_ , **--volsize** =_volsize_
                Switch volumes after reaching archive volume size _volsize_.
    
           **-V** _version_ , **--version** =_version_
                Specify archive _version_.  The default and the only accepted
                value is 2.
    
           **-x** _fd_
                Allow asynchronous control requests on the file descriptor
                _fd_.
    
           **-y** Use local timezone instead of the timezone from the pmcd(1)
                host.
    
           **-?** , **--help**
                Display usage message and exit.
    


## EXAMPLES



           For each PCP utility, there is a sample **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 _foo_ this
           configuration file is located in
           **$PCP_VAR_DIR/config/pmlogger/config.foo**.
    
           The following is a simple default configuration file for a primary
           **pmlogger** instance, and demonstrates most of the capabilities of
           the configuration specification language.
    
                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;
    


## HOSTNAME CHANGES



           The hostname of the PMCD that is providing metrics to **pmlogger** is
           used in several ways.
    
           PMCD's hostname (or the argument from the **-H** option) is included
           in the archive label and may be used to ensure that subsequent
           operations on multiple archives, e.g. pmlogextract(1), are only
           applied to archives from the same host.
    
           For **pmlogger** instances using a local PMCD that are launched and
           managed by pmlogger_check(1) and pmlogger_daily(1), (or the
           systemd(1) or 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.
           **$PCP_ARCHIVE_DIR/**_< hostname>_.
    
           And PMCD's hostname is also stored in the archive via the
           **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 pmlogger_daily(1).
    
           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, **pmlogger** may need to
           take special action, specifically if the **pmlogger** instance was
           launched from pmlogger_check(1) or pmlogger_daily(1), then
           **pmlogger** must exit.  Under normal circumstances systemd(1) or
           cron(8) will launch a new **pmlogger** shortly thereafter, and this
           new **pmlogger** instance will be operating in the context of the new
           hostname for the host where PMCD is running.
    


## DERIVED METRICS



           As described in 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 **pmlogger**
           configuration file, but they come with some special handling
           rules.
    
           First, the values of a derived metric, **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 **pmlogger** and _archive_ and may be different, or not exist at all,
           when _archive_ is replayed.
    
           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 _not_ , a derived
           metric; refer to pmRegisterDerived(3) for a detailed description
           of the PMID remapping.
    


## DIAGNOSTICS



           The archives are sufficiently precious that **pmlogger** will not
           truncate an existing physical file.  A message of the form
            ...: "foo.index" already exists, not over-written
            ...: File exists
           indicates this situation has arisen.  You must explicitly remove
           the files and launch **pmlogger** again.
    
           There may be at most one primary **pmlogger** instance per monitored
           host; attempting to bend this rule produces the error:
            pmlogger: there is already a primary pmlogger running
    
           Various other messages relating to the creation and/or deletion of
           files in **$PCP_TMP_DIR/pmlogger** suggest a permission problem on
           this directory, or some feral files have appeared therein.
    


## FILES



           _archive_**.meta**
                metadata (metric descriptions, instance domains, etc.) for
                the archive
    
           _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
    
           **$PCP_TMP_DIR/pmlogger**
                **pmlogger** maintains the files in this directory as the map
                between the process id of the **pmlogger** instance and the IPC
                port that may be used to control each **pmlogger** instance (as
                used by pmlc(1))
    
           **$PCP_VAR_DIR/config/pmlogger/config.default**
                default configuration file for the primary logger instance
                launched from **$PCP_RC_DIR/pmlogger**
    
           **$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
    
           **$PCP_ARCHIVE_DIR/**_< hostname>_
                Default directory for PCP archive files for performance
                metric values collected from the host _< hostname>_.
    
           **$PCP_SYSCONFIG_DIR/pmlogger**
                additional environment variables that will be set when the
                primary **pmlogger** instance executes.  Only settings of the
                form "PMLOGGER_VARIABLE=value" will be honoured.
    
           **./pmlogger.log**
                (or **$PCP_ARCHIVE_DIR/**_< hostname>_**/pmlogger.log** when started
                automatically by either **$PCP_RC_DIR/pmlogger** or one of the
                pmlogger(1) monitoring scripts such as pmlogger_check(1))
                all messages and diagnostics are directed here
    


## ENVIRONMENT



           Normally **pmlogger** creates a socket to receive control messages
           from pmlc(1) on the first available TCP/IP port numbered 4330 or
           higher.  The environment variable **PMLOGGER_PORT** may be used to
           specify an alternative starting port number.
    
           If set to the value 1, the **PMLOGGER_LOCAL** environment variable
           will cause **pmlogger** to run in a localhost-only mode of operation,
           where it binds only to the loopback interface.
    
           The **PMLOGGER_REQUEST_TIMEOUT** variable may be set by applications
           such as pmlc(1) to specify a timeout in seconds for connection
           requests to the **pmlogger** control port.  If not set, connections
           may block indefinitely.  This variable would not normally be set
           by **pmlogger** itself.
    
           The **PMLOGGER_MAXPENDING** variable can be set to indicate the
           maximum length to which the queue of pending **pmlc** connections may
           grow.
    
           The default sampling interval used by **pmlogger** can be set using
           the **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.
    
           On platforms using systemd(1), and when the **-N** option is given,
           the **NOTIFY_SOCKET** environment variable would normally be set by
           the service manager prior to launching **pmlogger**.
    
           Two additional environment variables are used as part of the hand-
           off from one **pmlogger** instance to the next during a re-exec
           operation, namely **__PMLOGGER_REEXEC** and **__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.
    


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


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    
           Debugging options specific to **pmlogger** are as follows:
           ┌────────┬───────────────────────────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl0** │ control request PDUs to and from pmlc(1)              │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl1** │ credentials exchange                                  │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl2** │ alarm (timing) loop diagnostics, callback work and    │
           │        │ record control mode messages                          │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl3** │ signal callbacks and exit logging                     │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl4** │ record timestamps in _logfile_ as milestones are        │
           │        │ reached                                               │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl5** │ PDU stats after _conffile_ file processed               │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl6** │ building the metadata cache from _conffile_ to boost    │
           │        │ start-up performance, _pass0_() work                    │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl7** │ suppress building of the metadata cache, _pass0_()      │
           │        │ becomes a no-op                                       │
           └────────┴───────────────────────────────────────────────────────┘
    


* * *