--- name: "pmlogger.control" section: "5" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmlogger.control" --- # pmlogger.control(5) control files for Performance Co-Pilot archiving ## NAME **pmlogger.control** - control files for Performance Co-Pilot archiving ## DESCRIPTION Historical archiving of performance data for Performance Co-Pilot (see [**PCPIntro**(1)](/PCPIntro/1.md)) uses [**pmlogger**(1)](/pmlogger/1.md) and one or more instances of **pmlogger** may be managed by [**pmlogger\_check**(1)](/pmlogger_check/1.md) and [**pmlogger\_daily**(1)](/pmlogger_daily/1.md). [**pmlogger\_check**(1)](/pmlogger_check/1.md) may be run at any time of the day and is intended to check that the desired set of **pmlogger** processes are running. If not, it (re-)starts any missing logger processes. By default, [**pmlogger\_check**(1)](/pmlogger_check/1.md) also calls [**pmlogger\_daily**(1)](/pmlogger_daily/1.md) with a **-K** option to execute any required archive compression tasks. [**pmlogger\_daily**(1)](/pmlogger_daily/1.md) is intended to be run once per day, preferably in the early morning, as soon after midnight as practicable. Its task is to aggregate, rotate and perform general housekeeping for one or more sets of PCP archives. Both [**pmlogger\_check**(1)](/pmlogger_check/1.md) and [**pmlogger\_daily**(1)](/pmlogger_daily/1.md) operate on a family of shared control files, namely the *$PCP\_PMLOGGERCONTROL\_PATH* file and files within the *$PCP\_PMLOGGERCONTROL\_PATH.d* directory. These files must not be writable by any user other than root. The control file(s) should be customized according to the following rules that define for the current version (1.1) of the control file format. - 1\. Lines beginning with a \`\`#'' are comments. A special case is lines beginning \`\`#!#''; these are control lines for a **pmlogger** that has been stopped using [**pmlogctl**(1)](/pmlogctl/1.md). - 2\. Lines beginning with a \`\`$'' are assumed to be assignments to environment variables in the style of [**sh**(1)](/sh/1.md), and all text following the \`\`$'' will be **eval**'ed by the script reading the control file, and the corresponding variable exported into the environment. This is particularly useful to set and export variables into the environment of the administrative scripts, e.g.\ ``` $ PMCD_CONNECT_TIMEOUT=20 ``` If the value to the right of the \`\`='' contains any white space, then the value should be enclosed in double (") or single (') quotes. As the lines in each control file are processed in order, it is important that any environment variables should be set **before** a control line that specifies a **pmlogger** instance that might expect to use those environment variables, e.g. to control compression or culling of archives by [**pmlogger\_daily**(1)](/pmlogger_daily/1.md). - 3\. There should be a version line in the control file of the form:\ ``` $version=1.1 ``` But since the only version currently supported is 1.1, this declaration provides no additional value beyond documentation. - 4\. Fields within a line of the control file(s) are usually separated by one or more spaces or tabs (although refer to the description of the *directory* field below for some important exceptions). - 5\. There should be one line in the control file(s) for each **pmlogger** instance with at least 4 fields of the form:\ ``` host primary socks directory args ... ``` - 6\. The *host* field is the name of the host that is the source of the performance metrics for this **pmlogger** instance. The reserved word **LOCALHOSTNAME** will be replaced by **local:** (so connection to [**pmcd**(1)](/pmcd/1.md) on the local host). - 7\. The *primary* field indicates if this is a primary **pmlogger** instance (**y**) or not (**n**). Since the primary logger must run on the local host, and there may be at most one primary logger for a particular host, this field can be **y** for at most one **pmlogger** instance, in which case the host name must be the name of the local host (or **LOCALHOSTNAME**). - 8\. The *socks* field indicates if this **pmlogger** instance needs to be started under the control of [**pmsocks**(1)](/pmsocks/1.md) to connect to a [**pmcd**(1)](/pmcd/1.md) through a firewall (**y** or **n**). - 9\. The *directory* field is a directory name. All archive files associated with this **pmlogger** instance will be created in this directory, and this will be the current directory for the execution of any programs required to maintain those archives. A useful convention is that primary logger archives for the local host with hostname *myhost* are maintained in the directory *$PCP\_ARCHIVE\_DIR/myhost* (this is where the default **pmlogger** start-up script in *$PCP\_RC\_DIR/pmlogger* will create the archives), while archives for the remote host *mumble* are maintained in *$PCP\_ARCHIVE\_DIR/mumble*. - 10\. The *directory* field may contain embedded shell syntax that will be evaluated by [**sh**(1)](/sh/1.md) to produce the real directory name to be used. The allowed constructs are: - • Any text (including white space) enclosed with **$(** and **)** will be interpreted as a shell command. - • Any text (including white space) enclosed with **\`** and **\`** (back quotes) will be interpreted as a shell command. - • Within a single line only one style of embedded shell command is allowed, so either **$(**...**)** or **\`**...**\`**, but not both. - • An initial double quote (") followed by arbitrary text (including white space, but excluding an embedded double quote) and a final double quote. - • An initial single quote (') followed by arbitrary text (including white space, but excluding an embedded single quote) and a final single quote. - • Any word containing a **$** (assumed to introduce an environment variable name). - 11\. In the *directory* field, the reserved word **LOCALHOSTNAME** will be replaced by the name of the local host. Similarly the reserved words **PCP\_ARCHIVE\_DIR** and **PCP\_LOG\_DIR** appearing anywhere in the *directory* field will be replaced by the values of the corresponding environment variables. - 12\. If the *directory* field (after any shell substitution) begins with \`\`+'' then this indicates that [**pmlogger**(1)](/pmlogger/1.md) will be executed with a **-R** option in *args* to \`\`push'' the archive to a remote [**pmproxy**(1)](/pmproxy/1.md) server. In this case, no archive files are stored locally, but *directory* (after the leading \`\`+'' is stripped) is used as the directory in which the log file from the local **pmlogger (1)** will be stored and possibly the location for the [**pmlogger**(1)](/pmlogger/1.md) configuration file (see the example below). - 13\. The optional *args* field and any remaining fields are interpreted as arguments to be passed to [**pmlogger**(1)](/pmlogger/1.md). Most typically this would be at least the **-c** option to specify the metrics to be logged and the logging frequencies, and/or **-R** in the case of a \`\`push'' archive. The following sample control lines specify a primary logger on the local host (*bozo*), non-primary loggers to collect and log performance metrics from the hosts *wobbly*, *boing* and the local host (i.e. *bozo*) and a logger pushing archives to the remote [**pmproxy**(1)](/pmproxy/1.md) on the host *grunt*. ``` $version=1.1 bozo y n $PCP_ARCHIVE_DIR/bozo -c config.default wobbly n n "/store/wobbly/$(date +%Y)" -c ./wobbly.config boing n n $PCP_ARCHIVE_DIR/boing -c ./pmlogger.config LOCALHOSTNAME n n /cluster/LOCALHOSTNAME -c ./precious.config LOCALHOSTNAME n n +PCP_ARCHIVE_DIR/remote -R http://grunt:44322 \ -c ./remote.config ``` ## SCHEDULED EXECUTION The periodic execution of [**pmlogger\_check**(1)](/pmlogger_check/1.md) and [**pmlogger\_daily**(1)](/pmlogger_daily/1.md) is controlled by either [**systemd**(1)](/systemd/1.md) or [**cron**(8)](/cron/8.md). Typical [**crontab**(5)](/crontab/5.md) entries are provided in *$PCP\_SYSCONF\_DIR/pmlogger/crontab* (unless installed by default in */etc/cron.d* already) and shown below. ``` # daily processing of archives 14 0 * * * $PCP_BINADM_DIR/pmlogger_daily # every 30 minutes, check pmlogger instances are running 25,55 * * * * $PCP_BINADM_DIR/pmlogger_check ``` When using [**systemd**(1)](/systemd/1.md) on Linux, no **crontab** entries are needed as the timer mechanism provided by **systemd** is used instead to achieve the same period execution as the crontab example above. ## FILES - *$PCP\_PMLOGGERCONTROL\_PATH* the PCP logger control file. For a new installation this file contains no [**pmlogger**(1)](/pmlogger/1.md) control lines (the real control files are all in the *$PCP\_PMLOGGERCONTROL\_PATH.d* directory), but this file is still processed to support any legacy configurations therein from earlier PCP releases.\ **Warning**: this file must not be writable by any user other than root. - *$PCP\_PMLOGGERCONTROL\_PATH.d* optional directory containing additional PCP logger control files, with one or more per **pmlogger** specification per file.\ **Warning**: the files herein must not be writable by any user other than root. - *$PCP\_SYSCONF\_DIR/pmlogger/crontab* sample crontab for automated script execution by $PCP\_USER (or root). Exists only if the platform does not support the /etc/cron.d mechanism. ## 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)](/pcp.conf/5.md). ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmlogctl**(1)](/pmlogctl/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pmlogger\_check**(1)](/pmlogger_check/1.md), [**pmlogger\_daily**(1)](/pmlogger_daily/1.md), [**pmlogger\_daily\_report**(1)](/pmlogger_daily_report/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**pmsocks**(1)](/pmsocks/1.md), [**systemd**(1)](/systemd/1.md) and [**cron**(8)](/cron/8.md).