NAME¶
pmlogconf - create/edit a pmlogger configuration file
SYNOPSIS¶
$PCP_BINADM_DIR/pmlogconf [
-cqrv] [
-d groupsdir] [
-h hostname]
configfile
DESCRIPTION¶
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
add a message and timestamp indicating this fact. 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.
SETUP GROUP FILES¶
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 the -r (reprobe) 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.
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
and no instance specification is allowed) 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:).
EXAMPLE¶
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 ]
MIGRATION¶
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.
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).
SEE ALSO¶
pmcd(1),
pmlogger(1),
pcp.conf(5) and
pcp.env(5).