pmlogger.control - control files for Performance Co-Pilot archive logging
Historical archive logging 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.
- •
- 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
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 archive logs
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.
- $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.
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).
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).