PMMGR(1) General Commands Manual PMMGR(1)
NAME
pmmgr - pcp daemon manager
SYNOPSIS
pmmgr [-v] [-c config-directory] [-p polling-interval]
DESCRIPTION
pmmgr 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
archives/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 dae-
mons should be run with. pmmgr uses a small number of files in a configuration directory, instead of lines in a text file. The individual
files carry zero or more lines of 100% pure configuration text, and no comments. (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
specified 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 metrics/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 hostname(2). If they don't, you should add other pcp metric specifications 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 persistent, 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.interface.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 specifications, as described on the PCPintro(1) man page. Each poll
interval, pmmgr will attempt to make a brief pmNewContext connection 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 pre-
sumed 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 addi-
tional space-separated options for the pmie daemon. (pmmgr already adds -h, -f, -r, -l, and perhaps -c.) The default is to main-
tain 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 written-to by pmlogger.) The file may contain a time interval specification 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 pmlogextract
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 daemon for each targeted pmcd. This file contains one line of addi-
tional 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 generate a configuration file for each target pmcd. The file contains
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
BUGS
PCP 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 configura-
tion file, as described in pcp.conf(5).
SEE ALSO
PCPIntro(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)