---

   pmdaopenmetrics    ( 1 )

---

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.