PMMGR(1)PMMGR(1)NAMEpmmgr - pcp daemon manager
SYNOPSISpmmgr [-v] [-c config-directory] [-p polling-interval]
DESCRIPTIONpmmgr manages a collection of PCP daemons for a set of discovered local
and remote hosts running the Performance Metrics Collection Daemon
(PMCD), according to zero or more configuration directories. It keeps
a matching set of pmlogger and/or pmie daemons running, and their ar‐
chives/logs merged/rotated. It supplants the older pmlogger_* and
pmie_* check/daily management shell scripts.
pmmgr is largely self-configuring and perseveres despite most run-time
errors. pmmgr runs in the foreground until interrupted. When sig‐
naled, it will stop its running daemons before exiting.
A description of the command line options specific to pmmgr follows:
-c directory adds a given configuration directory to pmmgr. pmmgr
can supervise multiple different configurations at the same time.
Errors in the configuration may be noted to standard error, but
pmmgr will fill in missing information with built-in defaults.
The default directory is $PCP_SYSCONF_DIR/pmmgr
-p polling-interval sets the host-discovery polling interval to the
given number of seconds. The default is 60.
-v adds more verbose tracing to standard error.
CONFIGURATION
A pmmgr configuration identifies which hosts should be monitored, which
daemons should be maintained for them, and what options those daemons
should be run with. pmmgr uses a small number of files in a configura‐
tion directory, instead of lines in a text file. The individual files
carry zero or more lines of 100% pure configuration text, and no com‐
ments. (If desired, a configuration may be commented upon with any
other file, such as a free-form README.)
TARGET SELECTION
This set of configuration files identifies where pmmgr should search
for pmcd instances, how to uniquely identify them, and where state such
as log files should be kept for each. Ideally, a persistent & unique
host-id string is computed for each potential target pmcd from speci‐
fied metric values. This host-id is also used as a subdirectory name
for locating daemon data.
hostid-metrics
This file contains one or more lines of metric specifications in
the format accepted by pmParseMetricSpec. Metrics without
instance specifiers mean all instances of that metric. These
are used to generate the unique host-id string for each pmcd
server that pmmgr discovers. Upon discovery, all the met‐
rics/instances named are queried, string values fetched, and
normalized/concatenated into a single hyphenated printable
string. The default is the single metric pmcd.hostname, which
is sufficient if all the hosts discovered have unique host‐
name(2). If they don't, you should add other pcp metric speci‐
fications to set them apart at your site. The more you add, the
longer the host-id string, but the more likely that accidental
duplication is prevented.
However, it may be desirable for a host-id to also be persis‐
tent, so that if the target host goes offline and later returns,
the new host-id matches the previous one, because then old and
new histories can be joined. This argues against using metrics
whose values vary from boot to boot.
Some candidate metrics to consider: network.interface.hw_addr,
network.interface.inet_addr["eth0"], network.inter‐
face.ipv6_addr, kernel.uname.nodename
log-directory
This file contains the path of a directory beneath which the
per-host-id subdirectories are to be created by pmmgr. If it is
not a full path, it is implicitly relative to the configuration
directory itself. The default is $PCP_LOG_DIR/pmmgr/.
target-host
This file contains one or more lines containing pmcd host speci‐
fications, as described on the PCPintro(1) man page. Each poll
interval, pmmgr will attempt to make a brief pmNewContext con‐
nection to the host to check liveness. It is not a problem if
more than one specification for the same host is listed, because
the host-id processing eliminates duplicates, and chooses an
arbitrary specification among them. The default is to target
pmcd at local:.
target-discovery
This file contains one or more lines containing specifications
for the pmDiscoverServices PMAPI call, each of which may map
onto a fluctuating set of local or remote pmcd servers. Each
poll interval, pmmgr will attempt to rerun discovery with all of
the given specifications. Again it is not a problem if more
than one specification matches the same actual pmcd. The
default value is to do no discovery. Consider including avahi
to rely on pmcd self-announcements on the local network.
log-subdirectory-gc
This file may contain a time interval specification as per the
PCPintro man page. All subdirectories of the log-directory are
presumed to contain data for pmmgr-monitored servers. Those
that have not been touched (in the stat/mtime sense) in at least
that long, and not associated with a currently monitored target,
are deleted entirely. This value should be longer than the
longest interval that pmmgr normally recreates archives (such as
due to pmmgr restarts, and pmlogmerge intervals). The default
value is 90days.
PMLOGGER CONFIGURATION
This group of configuration options controls a pmlogger daemon for each
host. This may include generating its configuration, and managing its
archives.
pmlogger
If and only if this file exists, pmmgr will maintain a pmlogger
daemon for each targeted host. This file contains one line of
additional space-separated options for the pmie daemon. (pmmgr
already adds -h, -f, -r, -l, and perhaps -c.) The default is to
maintain no pmlogger (and no other configuration in this section
is processed).
pmlogconf
If and only if this file exists, pmmgr will run pmlogconf to
generate a configuration file for each target pmcd. The file
contains one line of space-separated additional options for the
pmlogconf program. pmlogconf's generated output file will be
stored under the log-directory/hostid subdirectory. (pmmgr
already adds -c, -r, and -h.) The default is no pmlogconf, so
instead, the pmlogger file above should probably contain a -c
option, to specify a fixed pmlogger configuration.
pmlogmerge
If and only if this file exists, pmmgr will run pmlogextract to
periodically merge together all preexisting log archives for
each target pmcd into one. (When pmlogger is started, it always
creates a new archive, so in the steady state, there will be one
merged archive from history, and one current archive being writ‐
ten-to by pmlogger.) The file may contain a time interval spec‐
ification as per the PCPintro man page, representing the period
at which pmlogger should be temporarily stopped, and archives
merged. The default is 24hours.
pmlogmerge-retain
If this file exists, pmmgr will set the relative starting time
for retaining old archived data. It will be passed to pmlogex‐
tract as a negative parameter to -S. It is interpreted as a
request that data older than the given interval should be thrown
away. The default is 14days.
PMIE CONFIGURATION
This group of configuration options controls a pmie daemon for each
host. This may include generating a custom configuration.
pmie If and only if this file exists, pmmgr will maintain a pmie dae‐
mon for each targeted pmcd. This file contains one line of
additional space-separated options for the pmie daemon. (pmmgr
already adds -h, -f, -l, and perhaps -c.) The default is to
maintain no pmie (and no other configuration in this section is
processed).
pmieconf
If and only if this file exists, pmmgr will run pmieconf to gen‐
erate a configuration file for each target pmcd. The file con‐
tains one line of space-separated additional options for the
pmieconf program. pmieconf's generated output file will be
stored under the log-directory/hostid subdirectory. (pmmgr
already adds -F, -c, and -f.) The default is no pmieconf, so
instead, the pmie file above should probably contain a -c
option, to specify a fixed pmie configuration.
FILES
$PCP_SYSCONFIG_DIR/pmmgr/
default configuration directory
$PCP_LOG_DIR/pmmgr/
default logging directory
BUGSPCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parametrize 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 ALSOPCPIntro(1), pmcd(1), pmlogconf(1), pmlogger(1), pmieconf(1), pmie(1),
pmlogreduce(1), pcp.conf(5) and pcp.env(5).
Performance Co-Pilot PCP PMMGR(1)
