openMetrics PMDA (OpenMetrics PMDA)
LABEL FILTERING
Label filtering uses similar FILTER: syntax and semantics as
metric filtering. FILTER: EXCLUDE LABEL regex will delete all
labels with label name matching regex from all metrics defined by
the configuration file. The same rules as for metric filters
apply for label filters too - an implicit rule: FILTER: INCLUDE
LABEL .* applies to all labels that do not match any earlier
label filter rule. FILTER: OPTIONAL LABEL regex specifies that
matching label names are to be included in the returned metric
labelsets (i.e. included), but are not to be used as part of the
the external instance names. All included labels that are not
optional (i.e. the intrinsic labels) will be concatenated
together and used for external instance naming. In addition,
non-intrinsic labels (i.e. labels tagged as OPTIONAL) will have
the PM_LABEL_OPTIONAL flag set in the labelsets returned by notes
callbacks. This flag affects how the labels are used in certain
clients. For further details, see pmLookupLabels(3) and related
man pages for further details. Note that external instance names
begin with the unique numeric internal instance identifier
followed by a space, so external instance names are always
unique.
Caution is needed with label filtering because by default, all
labels are used to construct the PCP instance name. By excluding
some labels (or changing them to optional), the instance names
will change. In addition, excluding all labels for a particular
metric changes that metric to be singular, i.e. have no instance
domain. By excluding some labels, different instances returned
by the URL or scripted configuration entry for the same metric
may become duplicates. When such duplicates occur, the last
duplicate instance returned by the end-point URL or script
prevails over any earlier instances. For these reasons, it is
recommended that label filtering rules be configured when the
configuration file is first defined, and not changed thereafter.
If a label filtering change is required, the configuration file
should be renamed, which effectively defines a new metric (or set
of peer metrics as returned by the URL or script), with the new
(or changed) instance naming.
Unrecognized keywords in configuration files are reported in the
PMDA log file but otherwise ignored.
