NAME¶
pmmgr - pcp daemon manager
SYNOPSIS¶
pmmgr [
-v] [
-c config-directory] [
-p
polling-interval] [
-l log-file]
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 signaled, 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. Daemons for a particular
target host will be restarted no more frequently than this interval.
- -l
- log-file redirects standard output & error to the given log
file, which is created anew
- -v
- adds more verbose tracing to standard output.
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 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: one confirmed access path is arbitrarily selected. The
default is to do no discovery. Consider including
avahi,timeout=5 to rely in pmcd self-announcements on the local
network (searching for up to five seconds each time).
- 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.
ARCHIVE LOG MANAGEMENT¶
Default pmlogger configurations can collect tens of megabytes of data per day
(possibly split into multiple archives), per target host. If your disk space
is less than infinite, or archive-splitting unwieldy, this should be managed.
In the default, unmanaged case, the system administrator is responsible for
managing the individual
archive-* files from the per-host logging
subdirectories. pmmgr offers several other options, each representing
different performance / usability tradeoffs.
ARCHIVE LOG MANAGEMENT - pmlogmerge¶
This style of archive log management regularly creates a single merged archive
from prior archives for each target host, in effect lopping off old data and
appending the new. A single merged archive can be relatively large (defaults
to approximately 100-400 MB per host), and puts a corresponding I/O load on
storage, but is most convenient for a detailed long-timeframe analysis. Once
pmlogger is restarted, it always creates a new archive, so in the steady
state, there will be one merged archive of recent history, and one current
archive being written-to by pmlogger.
- pmlogmerge
- If this file exists, pmmgr will run pmlogextract to periodically
merge together preexisting log archives for each target pmcd into a single
large one. Then, the preexisting log archives are deleted (including any
prior merged ones). This configuration file may contain a time interval
specification as per the PCPintro man page, representing the period
after which pmlogger should be temporarily stopped, and archives merged.
It represents the maximum amount of time that the merged archive
lags the present time. The default is 24hours.
- pmlogmerge-granular
- If this file exists, pmmgr will merge only a subset of preexisting log
archives into the new one, instead of all of them, so as to approximate a
granular, aligned set of merged archives. The subset chosen corresponds to
the previous time interval specified by the pmlogmerge control
file. The default is no granularity.
- 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. In addition, unmerged
archive files left around, that are older than this, are deleted. (This
can happen if those archive files had errors that prevented their
merging.) The default is 14days.
- pmlogmerge-rewrite
- If this file exists, pmmgr will run pmlogrewrite -i (plus any other
options listed in this file) on each input archive before merging it. This
will naturally require more disk I/O. The default is no rewriting.
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 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
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 configuration
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).