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 :
operationlist ;'' and ``disallow hostlist : operationlist
;''.
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).
