Provided by: pcp_6.3.0-1_amd64 
NAME
pmlogger.control - control files for Performance Co-Pilot archiving
DESCRIPTION
Historical archiving of performance data for Performance Co-Pilot (see PCPIntro(1)) uses pmlogger(1) and
one or more instances of pmlogger may be managed by pmlogger_check(1) and pmlogger_daily(1).
pmlogger_check(1) 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) also calls pmlogger_daily(1) with a -K option to execute any required archive
compression tasks.
pmlogger_daily(1) 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) and pmlogger_daily(1) 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).
2. Lines beginning with a ``$'' are assumed to be assignments to environment variables in the style of
sh(1), 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.
3. There must be a version line in the control file of the form:
$version=1.1
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 the name of 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) to connect to a pmcd(1) 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/pcp 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) 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.
12. The optional args field and any remaining fields are interpreted as arguments to be passed to
pmlogger(1). Most typically this would be at least the -c option to specify the metrics to be logged
and the logging frequencies.
The following sample control lines specify a primary logger on the local host (bozo), and non-primary
loggers to collect and log performance metrics from the hosts wobbly, boing and the local host (i.e.
bozo).
$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
SCHEDULED EXECUTION
The periodic execution of pmlogger_check(1) and pmlogger_daily(1) is controlled by either systemd(1) or
cron(8).
Typical crontab(5) 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) 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) 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).
SEE ALSO
PCPIntro(1), pmcd(1), pmlogctl(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1),
pmlogger_daily_report(1), pmsocks(1), systemd(1) and cron(8).
Performance Co-Pilot PCP PMLOGGER.CONTROL(5)