PMLOGCONF(1)

📦
version 7.2.2 · 7 versions
, in arch rolling, fedora 43, fedora 44, ubuntu stonking

pmlogconf 💖 — the pmlogconf(1) girlies' guide

ok so bestie, welcome to pmlogconf, a General Commands Manual situation, and honestly? she's the one who makes your pmlogger configs happen. let's get into it 🎀

✨ NAME ✨

pmlogconf — create/edit a pmlogger configuration file 🫶

🌸 SYNOPSIS 🌸

pmlogconf [-cqrvV?]  [-d groupsdir] [-D debug] [-g grouptag] [-h host]
[-s groupfile] configfile

like. that's the whole vibe check right there. moving on 💅

💜 DESCRIPTION 💜

okay so pmlogconf is literally here to create and modify a generic configuration file for the PCP archiver, pmlogger(1). iconic behavior.

If configfile does not exist, pmlogconf will create a generic configuration file with a default set of enabled metrics and logging intervals. no cap, she just does it for you. ✨

Once it's created, configfile may be used with the -c option to pmlogger(1) to select performance metrics and specify logging intervals for a PCP archive. periodt.

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. it's giving interactive queen 👑

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. (not me asking "who are you" to a metric group 😭)
  • q — finish with group selection (quit) and make no further changes to this group or any subsequent group. she's done, she's leaving the group chat.
  • /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. yes bestie, plural forms count. we love inclusive grammar 💅

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.

🚨 okay heads up: this option is not appropriate for interactive use of the tool. fr fr, don't do it.

The -q option suppresses the logging interval dialog and preserves the current interval from configfile. quiet mode = main character who doesn't want to be perceived 🦋

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. like, she already knows where she's going. 💖

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. slay, extendable.

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. 👀 it's giving "we don't know her anymore".

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.
  • An optional derived metric control lines begin with the keyword define and have the format:
define name expr

where name is the name of a derived metric and expr is a derived metric expression. Refer to pmRegisterDerived(3) for the syntactic and semantic descriptions of name and expr. Once defined, name may be used as the metric in a subsequent probe control line, allowing the expression of more complex guards for conditional inclusion of metrics in configfile.

🌸 note that name needs to be unique across all group files and not collide with an existing name in the PMNS. So some suitable naming convention may need to be adopted when the group files are created. iykyk, pick a name and commit to it.
  • 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, other than one mentioned in a previous define control line) 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 when configfile already exists, 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. no debate, no conditions, she's decisive 💅

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:).

🎀 OPTIONS 🎀

The available command line options are:

  • -c — Enable non-interactive, auto-create mode.
  • -d groupsdir, --groups=groupsdir — 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.

🌈 EXAMPLES 🌈

The following group file demonstrates most 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 ]

In the following example (backslashes have been added for readability, the define clause is all on one line), the mumble metrics will be included in configfile if either the mumble.foo metric is known and has at least one instance (and value) or the mumble.bar metric is known and has at least one instance (and value):

#pmlogconf-setup 2.0
ident   Derived metric example with alternation
define  mumble.check = \
            (defined(mumble.foo) ? count(mumble.foo) : 0) + \
            (defined(mumble.bar) ? count(mumble.bar) : 0)
probe   mumble.check > 0 ? include : exclude
        mumble

The following example uses a derived metric to access one particular metric instance in a probe control line.

#pmlogconf-setup 2.0
ident   Derived metric example using a single metric instance
define  fumble_log = fumble.control[verbose_log]
probe   fumble_log > 0 ? include : exclude
        fumble.detailed

🦋 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. glow-up era ✨

ok bestie that's part 1, hold on, there's more coming 💖

🌈 PCP ENVIRONMENT 🌈

ok so PCP has its own lil env-var universe, and every single one of them starts with PCP_. they're what parameterize the file and directory names that PCP uses. 💅

on every installation, the file /etc/pcp.conf holds the local values for these variables. and if you wanna point at a different config file entirely, you can set $PCP_CONF to specify an alternative configuration file, as described in pcp.conf(5). 🎀

  • $PCP_DERIVED_CONFIG — bestie, pmlogconf overrides this one to an empty string. why? for performance reasons, and to prevent the inclusion of derived metrics in configfile. no cap, it just does. 🙈
  • $PMCD_WAIT_TIMEOUT — pmlogconf honours this when it's probing and creating new pmlogger configuration files. if there's no environment setting, it uses a default timeout value of 10 seconds for this. ⏱️

🐛 DEBUGGING OPTIONS 🐛

the -D or --debug option turns on extra diagnostics on stderr, to help triage problems. lowkey though, the info is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users — so if you're just vibing as a regular user, don't feel bad if it reads like a group chat you weren't added to. 😭

debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning. 📋

✨ the debugging options that are specific to pmlogconf ✨

  • appl0 — group file operations 🗂️
  • appl1 — metric probe operations 🔍
  • appl2 — verbose dumping of internal group data structures 🫠

👀 SEE ALSO 👀

go read these next, bestie, they're all part of the lore:

and that's the whole page!! 🎉 this was Performance Co-Pilot, from the PCP girlies, and the page is PMLOGCONF(1). go forth and configure your logging like the main character you are. periodt. 💖✨🦋👑

📦 where this page comes from