PMLOGCTL(1)

💅 PMLOGCTL — manage and control Performance Co-Pilot archivers

okay bestie, buckle up, because this is the manual page for pmlogctl(1) — a General Commands Manual situation, and she is long but she is also iconic. let's get into it ✨

✨ NAME ✨

pmlogctl — manage and control Performance Co-Pilot archivers 🎀

🌸 SYNOPSIS 🌸

pmlogctl [-afmNV?]  [-C check_args] [-c class] [-i ident] [-p policy]
command [host ...]

🦋 DESCRIPTION 🦋

so, pmlogctl is the girl who manages the non-primary instances of the Performance Co-Pilot (PCP) archiver pmlogger(1). 🫶 like, this is the tool for a PCP archiver "farm" where you've got a whole squad of pmlogger(1) instances out there making archives of performance data collected from pmcd(1) on a bunch of remote hosts. it's giving ✨*farm energy*✨

now, the primary pmlogger(1) instance? she's different. she's tightly linked to the local pmcd(1) process and therefore shares the same control infrastructure — namely systemd(1) or the PCP init(1) "rc scripts". and that is exactly why the primary pmlogger(1) instance cannot be managed with pmlogctl. she's got her own thing going on, and honestly, respect. 💅

for brevity in the description below, the term "instance" means a pmlogger(1) instance. periodt.

every instance managed by pmlogctl, pmlogger_check(1) and pmlogger_daily(1) abides by the following rules, no exceptions, no cap:

1. each instance is fetching performance data from a single pmcd(1) (i.e. one host), but each pmcd(1) may be providing performance data to zero, one or more pmlogger(1) processes running on one or more hosts. sharing is caring fr fr 🍓
2. on the local host, each pmlogger(1) instance must be specified once in a pmlogger_check(1) control file, and pmlogger(1) creates archives in a unique directory, named in the 4th parameter of the associated control file entry (go peek at the CONFIGURATION section of pmlogger_check(1) for the deets).
3. each instance belongs to exactly one class, optionally named using a $class=... assignment in the associated control file. the special default class is reserved for all instances that don't have an associated $class=... assignment. and for reporting purposes (refer to the summary command below 👀), the primary pmlogger(1) instance is automatically assigned to the special primary class. queen behavior, honestly. 👑

each pmlogctl execution manages one or more instances, updating the associated control files and then running pmlogger_check(1) to effect the desired change.

the host arguments are usually valid host names. for all commands except create and cond-create (described below), the host arguments may also be egrep(1) regular expressions that match the whole of a valid host name — so the pattern used is actually ^host$. for example:

• foo.* — matches all host names beginning with "foo"
• .*foo — matches all host names ending with "foo"
• .*[fF][oO][oO].* — matches all host names containing "foo" in upper, lower or mixed case 🔥

the combination of a class from the optional -c option (or default) and the host arguments to each command identifies a target set of instances to which the command operation should be applied.

the -i option may be used with the create or cond-create commands to override the instance identity that is specified in the ident section of the class policy file (see the CLASS POLICY FILE section below). since the identifier must be unique across all instances and all classes, it only makes sense to use this option when there is a single host argument. no multitasking on that one bestie 😭

given the tasks that pmlogctl is undertaking, it usually must be run as "root" — the exceptions being the status command, or when the -N option is specified. yes she's high maintenance, but she's worth it 💖

---

👑 COMMANDS 👑

command is one of the following:

• check — check the status of all currently configured pmlogger instances and restart any that have failed. if the -m flag is given on systemd(1) platforms, also migrate matching (and new) processes to the pmlogger_farm service. vibe check + glow up in one step ✨
• create — create new instances in the class classname (default by default) for the host hosts. the name of the class is used to identify a class policy file (see the CLASS POLICY FILE section below) which provides a template for each new control file, with %h replaced by host and %i replaced by the instance's (unique) identifier from the ident section of the class policy file, or ident from the -i option.

the -p option may be used to identify a class policy file other than the one found in the standard place, i.e. $PCP_SYSCONF_DIR/pmlogger/class.d/classname.

at least one host must be specified for the create command. don't come to the function empty-handed 🙈

• cond-create — similar to create, but the instance will only be created if one of the conditions in the create section of associated class policy file(s) evaluates to true. conditional queen 🎀

if a -c option is specified, then only the class classname will be considered, otherwise all classes will be considered. in the latter case, if none of the conditions in any of the classes evaluates to true, then the special pmfind class is used (this is the "default" class for the cond-create command when all else fails — she's the backup bestie who always shows up).

if more than one class evaluates to true then a composite pmlogger(1) configuration file is created and the instance is also assigned to the special pmfind class. the composite configuration file may contain a mix of explicit configuration clauses and the more general conditional configuration clauses as understood by the pmlogconf(1) tool.

• start — start the target set of instances. 🚀

if the target set intentionally contains more than one instance, then the -a option should be used — this is designed to reduce the risk of accidentally starting a potentially large number of pmlogger(1) processes. (we do not do accidental chaos in this house 💀)

if an instance in the target set is already started, no change is made (see the restart command to force new instances to be launched).

• stop — stop the target set of instances. 🛑

if the target set intentionally contains more than one instance, then the -a option should be used — this is designed to reduce the risk of accidentally stopping a potentially large number of pmlogger(1) processes.

if an instance in the target set is already stopped, no change is made but a warning is issued. noted. 📝

• restart — stop and then start the target set of instances. 🔄

if the target set intentionally contains more than one instance, then the -a option should be used — this is designed to reduce the risk of accidentally stopping and starting a potentially large number of pmlogger(1) processes.

if an instance in the target set is already stopped, a warning is issued before the instance is started.

• status — report the status of the target set of instances. if there is no -c option specified and no host arguments, i.e. the target set is empty, then all instances will be reported. spill the tea on everyone 🍵
• destroy — destroy the target set of instances. at the end of this operation the associated pmlogger(1) processes will have been stopped and the relevant control file information removed. 💀✨

if the target set intentionally contains more than one instance, then the -a option should be used — this is designed to reduce the risk of accidentally terminating a potentially large number of pmlogger(1) processes and removing their pmlogger_check(1) configurations. seriously bestie, use -a. 🙏

the policy file linked to the class of an instance to be destroyed may contain a destroy section that may influence if and how the destroy operation should be performed. this may require a -p option to find the associated class policy file.

the class policy checking can be by-passed using the -f (force) command line option. ⚠️ by-passed, like, skipping the line entirely — dramatic and powerful, use responsibly.

🎀 CLASS POLICY FILE 🎀

Okay bestie, this is the part where we talk about the policy file itself, and honestly? It's giving "structured and iconic." A class policy file is made of a bunch of sections, and every section kicks off with a line that just starts with the name of the section wrapped in [ and ]. Simple. Clean. We love.

Lines that start with a hash (#) are comments and get ignored. Blank or empty lines? Also ignored. No notes. 🫶

The typical hangout spot for the policy file of the class foo is:

$PCP_SYSCONF_DIR/pmlogger/class.d/foo

• [class] — this section is optional and it names the class. If you don't include it, the name of the policy file (with any directory prefix stripped off) becomes the name of the class. So it figures it out itself, main character energy 💅
• [ident] — this one sets the template used for the instance identifier handed to every member of the class. Heads up: this identifier has to be unique across all instances and all classes, and it also needs to be a valid file name on the local filesystem. So yeah, it'd normally contain the class name plus the macro %h, like foo-%h. That macro gets swapped out for the host when each instance is created. ✨
• [control] — this section is one or more lines of template text that get used to build the control file for each instance. It has to at least include the pmlogger_check(1) control line that says how to start the associated pmlogger(1) process. That line has fields separated by white space, like this:
  1. the hostname, usually the macro %h
  2. n to indicate this is a non-primary instance
  3. the ``socks'' flag, typically n
  4. the directory where the pmlogger(1) archives will be created; this needs to be unique and is usually written using the pmlogger_check(1) macro PCP_ARCHIVE_DIR as the start of the path, followed by the instance identifier, usually the macro %i, e.g. PCP_ARCHIVE_DIR/%i
  5. additional parameters to pmlogger(1), which probably include at least a -c option pointing at a configuration file that describes which metrics should be logged for instances of this class. That config can be the same for every instance in the class, or it can include the %i macro so each instance gets its own configuration file. Quick note: if that configuration file doesn't exist, it will be created using pmlogconf(1) the first time pmlogger_check(1) is run. 😌

Before the control line, there should be a line that defines the version of the control line that follows, i.e.

$version=1.1

If that's missing, pmlogctl will assume the version is 1.1 and insert the line when the instance is created.

pmlogctl will also add the class name during creation. e.g.

$class=foo

Inside a control line template, there's a simple form of parametric substitution supported. The ENV(spec) macro gets replaced by text using environment variables, like this:

• If spec is of the form var then the value of $var from the environment is used. If $var is not defined or has the value of an empty string, this is an error.
• If spec is of the form var:default then if $var from the environment is defined and is not an empty string the value of $var is used, otherwise the value default is used. The substitution is simple, so any whitespace between the : and the ) is included in default, and default cannot contain a ). (noted, don't do that 💀)

As an example, take

# unset PMPROXY_PORT; PMPROXY_HOST=foobar.com pmlogctl create ...

with a policy class control template line that includes

http://ENV(PMPROXY_HOST):ENV(PMPROXY_PORT:44322)

and it will generate a control line that includes

http://foobar.com:44322

see? ate that. 🔥

• [create] — this section defines the conditions that must be met before an instance will be created with the cond-create command. The whole intent here is to let different decisions be made when a new host running pmcd(1) gets discovered, e.g. by pmfind(1).

Every non-blank line in the create section is a condition of the form function(arg), where function is one of these:

• exists — arg is the name of a performance metric and exists evaluates to true if that metric exists in the Performance Metrics Name Space (PMNS) on the remote host
• values — arg is the name of a performance metric in the remote PMNS and values evaluates to true if some instance of that metric has a value on the remote host
• condition — arg is a derived metric expression in the format supported by pmRegisterDerived(3), and condition evaluates to true if the value of that expression on the remote host is greater than zero
• hostname — arg is a regular expression in the style of egrep(1) and hostname evaluates to true if the remote host name matches arg

• [destroy] — this section defines the policy to apply when an instance is destroyed. The intent is to let different decisions be made when a discovery service, e.g. pmfind(1), notices that a host associated with an instance is no longer present. But in the current version this is not implemented and the destroy section syntax and semantics is not yet defined. So like... don't come for it, it's a work in progress 🙈

A sample class policy file is as follows:

# policy file for the foo class
[class]
foo
[ident]
foo-%h

[control]
$version=1.1
%h n n PCP_ARCHIVE_DIR/%i -c foo-metrics.config

[create]
# matches all hosts
hostname(.*)

[destroy]
# still to be defined

---

✨ OPTIONS ✨

Here are all the command line options available to you, bestie. Pick your faves 💖

• -a, --all — apply the action to all matching instances. By default only one instance definition is expected and acted upon.
• -c class, --class=class — set the name of the class for which pmlogger(1) instances belong to as class.
• -C check_args, --checkargs=check_args — check_args are additional command line arguments for pmlogger_check(1) when it is called. This is most useful for options like -V. You can use multiple -C options and the various check_args options will be accumulated and all passed to pmlogger_check(1).
• -f, --force — force the action if possible. 💪
• -i ident, --ident=ident — override the instance identifier with ident. This option applies only for the commands create and cond-create.
• -N, --showme — runs pmlogctl in a show me'' or dry run'' mode where the intent of the command is shown, but no changes are made. perfect for when you're just window shopping 🛍️
• -m, --migrate — when used with the create or check commands on systemd(1) platforms, also migrate new or existing non-primary pmlogger processes to the pmlogger_farm service. This is normally done automatically by the pmlogger_farm_check service, which is timer driven (so there may be a few minutes delay before automatic migration is initiated). patience, babes ⏳
• -p policy, --policy=policy — use policy as the class policy file. Defaults to $PCP_SYSCONF_DIR/pmlogger/class.d/<class>.
• -V, --verbose — enable verbose mode. Using this option twice increases verbosity. Verbose output is written to stderr.
• -?, --help — display usage message and exit. the classic. 👑

---

🌈 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 👀

egrep(1), init(1), PCPIntro(1), pmcd(1), pmlc(1), pmlogconf(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1), systemd(1), PMAPI(3), pmDerivedRegister(3) and pcp.conf(5).

go read them, they're all besties with this one fr fr 🫶

---

and that's the whole page, babe 💖 this came out of the Performance Co-Pilot source, version PCP, and it's filed under PMLOGCTL(1) with its own little date stamp up top. slay, thanks for reading, mwah 🎀✨