pmlogconf - create/edit a pmlogger configuration file
pmlogconf [
-cqrvV?] [
-d groupsdir] [
-g
grouptag] [
-h host] [
-s groupfile]
configfile
pmlogconf may be used to create and modify a generic configuration file
for the PCP archive logger,
pmlogger(1).
If
configfile does not exist,
pmlogconf will create a generic
configuration file with a default set of enabled metrics and logging
intervals.
Once created,
configfile may be used with the
-c option to
pmlogger(1) to select performance metrics and specify logging intervals
for a PCP archive.
If
configfile does exist,
pmlogconf will prompt for input from the
user to enable or disable groups of related performance metrics and to control
the logging interval for each enabled group.
Group selection requires a simple
y (yes) or
n (no) response to
the prompt
Log this group?.
Other responses at this point may be used to select additional control functions
as follows:
- m
- Report the names of the metrics in the current group.
- q
- Finish with group selection (quit) and make no further
changes to this group or any subsequent group.
-
/pattern
- Make no change to this group but search for a group
containing pattern in the description of the group or the names of
the associated metrics.
A logging interval is specified by responding to the
Logging interval?
prompt with the keywords
once or
default or a valid
pmlogger(1) interval specification of the form ``
every N
timeunits'' or simply ``
N timeunits '' (the
every is
optional) where
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
keywords.
When run from automated logging setup processes, the
-c option is used to
indicate that
pmlogconf is in auto-create mode and no interactive
dialog takes place. The output
configfile has an additional comment
message and timestamp indicating this fact, so that it can be identified and
subsequently updated using
-c again. This option is not appropriate for
interactive use of the tool.
The
-q option suppresses the logging interval dialog and preserves the
current interval from
configfile.
More verbose output may be enabled with the
-v option.
When an initial
configfile is created, the default specifications come
from a set of group files below the
groupsdir specified with the
-d option (the default
groupsdir is
$PCP_VAR_DIR/config/pmlogconf which is most commonly correct, so the
-d option is rarely used in practice).
The directory structure below
groupsdir is arbitrary as all regular files
will be found by recursive descent and considered, so add-on products and PMDA
developers can easily extend the available defaults to
pmlogconf by
adding new directories and/or group files below
groupsdir.
These group files are processed in the following ways:
- •
- When a new configfile is created, all group files
are processed.
- •
- Whenever pmlogconf is run with an existing
configfile, groupsdir is traversed to see if any new groups
have been defined and should be considered for inclusion in
configfile.
- •
- When pmlogconf processes a group in
configfile that is enabled, the list of metrics associated with the
group is taken from the group file (and replaces any previous list of
metrics associated with this group in configfile).
- •
- When either the -r (reprobe) or the -c
(auto-create) command line option is specified, every group (not just
newly discovered ones) is reprocessed to see if it should be considered
for inclusion in configfile.
- •
- If a group is found in configfile but the
corresponding group does not exist below groupsdir (as would be the
case when a group is made obsolete by a PCP upgrade) then the handling of
the group depends on the mode in which pmlogconf is being run. With
-c the corresponding group is culled from configfile,
otherwise the corresponding group is unchanged in configfile. In
either case a warning is issued.
Each group file is structured as follows:
- •
- The first line must contain #pmlogconf-setup
2.0
- •
- Other lines beginning with # are treated as
comments.
- •
- Blank lines are ignored.
- •
- One or more lines starting with the keyword ident
are used to provide the human-readable description of the group.
- •
- Non-blank lines beginning with white space define metrics
to be associated with this group, one per line. Each metric specification
follows the rules for a pmlogger(1) configuration, namely either
the name of a non-leaf node in the PMNS (implying all descendent names in
the PMNS), or the name of a leaf node in the PMNS optionally followed by
one or more instance names enclosed by ``['' and ``]''.
- •
- A control line starting with one of the keywords
probe or force must be present.
- •
- An optional logging interval control line begins with the
keyword delta followed by one of the pmlogger(1) interval
specification described above.
- •
-
probe control lines have the format:
probe metric [
condition [
state_rule] ]
where
metric is the name of a PCP metric (must be a leaf node in the
PMNS, no instance specification is allowed, and it must not be a derived
metric) and the optional
condition is the keyword
exists (true
if
metric exists, i.e. is defined in the PMNS) or the keyword
values (true if
metric exists in the PMNS and has one or more
current values) or an expression of the form
op val
where
op is one of the
awk(1) operators (
==,
!=,
>,
>=,
<,
<=,
~ (regular
expression match) or
!~ (negated regular expression match)) and
val is a value (arbitrary sequence of characters, excluding a space)
and the
condition is true if there is some instance of
metric
that makes the expression true.
If the
condition is missing, the default is
exists.
When an explicit
condition is provided, there may also be an optional
state_rule of the form
? true_state : false_state
where
true_state (applies if
condition is true) and
false_state (applies if
condition is false) are both taken from
the keywords
include (include and enable the group and the associated
metrics in
configfile),
available (include and disable the group
in
configfile - a user action of
y as described above is needed
to enable the group and add the associated metrics into
configfile) or
exclude (the group is not considered for inclusion in
configfile).
The default
state_rule is
? available : exclude
- •
-
force control lines begin with the keyword
force followed by one of the states defined above, so one of the
actions include, exclude or available is applied
unconditionally to the group.
Probing is only done when a new group is being added to
configfile or
when the
-r command line option is specified. The evaluation of the
probing conditions is done by contacting
pmcd(1) on
hostname
(defaults to local:).
The available command line options are:
- -c
- Enable non-interactive, auto-create mode.
-
-d groupdir,
--groups=groupdir
- Specify the path to the groupsdir directory.
-
-g grouptag,
--group=grouptag
- Query logging state for the specific logging group named
grouptag.
-
-h host, --host=host
- Performance metrics source is pmcd(1) on
host, rather than on the default localhost.
-
-q, --quiet
- Quiet mode, suppress logging interval dialog.
-
-r, --reprobe
- Reconsider every group for inclusion in the
configfile.
-
-s groupfile,
--setup=groupfile
- Report the default logging state for the one logging group
in groupfile. This is equivalent output to that produced by the
retired pmlogconf-setup shell script from earlier versions of
PCP.
-
-v, --verbose
- Enable verbose mode.
-
-V, --version
- Display version number and exit.
-
-?, --help
- Display usage message and exit.
The following group file demonstrates all of the supported syntactic elements.
#pmlogconf-setup 2.0
ident Example group file
ident ... more description
delta 1 minute
probe sample.secret.foo.one values ? include : exclude
sample.secret.foo.one
sample.secret.foo.bar # non-leaf in the PMNS
sample.colour [ red green ]
The current version of
pmlogconf (2.0) supports a slightly different
format for
configfile compared to earlier versions. If an old version
configfile is presented to
pmlogconf it will be converted to the
new format.
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).
pmlogconf overrides any
$PCP_DERIVED_CONFIG environment variable
to an empty string, for performance reasons.
pmlogconf honours the
$PMCD_WAIT_TIMEOUT environment variable when
probing and creating new
pmlogger configuration files. It uses a
default timeout value of 10 seconds for this, in the absence of an environment
setting.
pmcd(1),
pmlogger(1),
pcp.conf(5) and
pcp.env(5).