1PMMGR(1) General Commands Manual PMMGR(1)
2
6 pmmgr - pcp daemon manager
7
9 pmmgr [-v] [-c config-directory] [-p polling-interval] [-l log-file]
10
13 pmmgr manages a collection of PCP daemons for a set of discovered local
14 and remote hosts running the Performance Metrics Collection Daemon
15 (PMCD), according to zero or more configuration directories. It keeps
16 a matching set of pmlogger and/or pmie daemons running, and their ar‐
17 chives/logs merged/rotated. It supplants the older pmlogger_* and
18 pmie_* check/daily management shell scripts.
19 pmmgr is largely self-configuring and perseveres despite most run-time
21 errors. pmmgr runs in the foreground until interrupted. When sig‐
22 naled, it will stop its running daemons before exiting.
23 A description of the command line options specific to pmmgr follows:
25 -c directory adds a given configuration directory to pmmgr. pmmgr
27 can supervise multiple different configurations at the same time.
28 Errors in the configuration may be noted to standard error, but
29 pmmgr will fill in missing information with built-in defaults.
30 The default directory is $PCP_SYSCONF_DIR/pmmgr
31 -p polling-interval sets the host-discovery polling interval to the
33 given number of seconds. The default is 60. Daemons for a par‐
34 ticular target host will be restarted no more frequently than this
35 interval.
36 -l log-file redirects standard output & error to the given log file,
38 which is created anew
39 -v adds more verbose tracing to standard output.
41
44 A pmmgr configuration identifies which hosts should be monitored, which
45 daemons should be maintained for them, and what options those daemons
46 should be run with. pmmgr uses a small number of files in a configura‐
47 tion directory, instead of lines in a text file. The individual files
48 carry zero or more lines of 100% pure configuration text, and no com‐
49 ments. (If desired, a configuration may be commented upon with any
50 other file, such as a free-form README.)
51 TARGET SELECTION
54 This set of configuration files identifies where pmmgr should search
55 for pmcd instances, how to uniquely identify them, and where state such
56 as log files should be kept for each. Ideally, a persistent & unique
57 host-id string is computed for each potential target pmcd from speci‐
58 fied metric values. This host-id is also used as a subdirectory name
59 for locating daemon data.
60 hostid-metrics
63 This file contains one or more lines of metric specifications in
64 the format accepted by pmParseMetricSpec. Metrics without
65 instance specifiers mean all instances of that metric. These
66 are used to generate the unique host-id string for each pmcd
67 server that pmmgr discovers. Upon discovery, all the met‐
68 rics/instances named are queried, string values fetched, and
69 normalized/concatenated into a single hyphenated printable
70 string. The default is the single metric pmcd.hostname, which
71 is sufficient if all the hosts discovered have unique host‐
72 name(2). If they don't, you should add other pcp metric speci‐
73 fications to set them apart at your site. The more you add, the
74 longer the host-id string, but the more likely that accidental
75 duplication is prevented.
76 However, it may be desirable for a host-id to also be persis‐
78 tent, so that if the target host goes offline and later returns,
79 the new host-id matches the previous one, because then old and
80 new histories can be joined. This argues against using metrics
81 whose values vary from boot to boot.
82 Some candidate metrics to consider: network.interface.hw_addr,
84 network.interface.inet_addr["eth0"], network.inter‐
85 face.ipv6_addr, kernel.uname.nodename
86 log-directory
89 This file contains the path of a directory beneath which the
90 per-host-id subdirectories are to be created by pmmgr. If it is
91 not a full path, it is implicitly relative to the configuration
92 directory itself. The default is $PCP_LOG_DIR/pmmgr/.
93 target-host
96 This file contains one or more lines containing pmcd host speci‐
97 fications, as described on the PCPintro(1) man page. Each poll
98 interval, pmmgr will attempt to make a brief pmNewContext con‐
99 nection to the host to check liveness. It is not a problem if
100 more than one specification for the same host is listed, because
101 the host-id processing eliminates duplicates, and chooses an
102 arbitrary specification among them. The default is to target
103 pmcd at local:.
104 target-discovery
107 This file contains one or more lines containing specifications
108 for the pmDiscoverServices PMAPI call, each of which may map
109 onto a fluctuating set of local or remote pmcd servers. Each
110 poll interval, pmmgr will attempt to rerun discovery with all of
111 the given specifications. Again it is not a problem if more
112 than one specification matches the same actual pmcd: one con‐
113 firmed access path is arbitrarily selected. The default is to
114 do no discovery. Consider including avahi,timeout=5 to rely in
115 pmcd self-announcements on the local network (searching for up
116 to five seconds each time).
117 subtarget-containers
120 If this file exists, pmmgr will scan each host that is found for
121 running containers. For each running container, it will create
122 independent subtargets for running pmlogger instances. The
123 host-id string for these subtargets is the host's host-id
124 string, followed by a double-hyphen, then the full unique con‐
125 tainer instance-name string. (Temporarily, pmie instances are
126 not attempted for these subtargets, due to PCP bug PR1105.)
127 log-subdirectory-gc
130 This file may contain a time interval specification as per the
131 PCPintro man page. All subdirectories of the log-directory are
132 presumed to contain data for pmmgr-monitored servers. Those
133 that have not been touched (in the stat/mtime sense) in at least
134 that long, and not associated with a currently monitored target,
135 are deleted entirely. This value should be longer than the
136 longest interval that pmmgr normally recreates archives (such as
137 due to pmmgr restarts, and pmlogmerge intervals). The default
138 value is 90days.
139 PMLOGGER CONFIGURATION
142 This group of configuration options controls a pmlogger daemon for each
143 host. This may include generating its configuration, and managing its
144 archives.
145 pmlogger
148 If and only if this file exists, pmmgr will maintain a pmlogger
149 daemon for each targeted host. This file contains one line of
150 additional space-separated options for the pmie daemon. (pmmgr
151 already adds -h, -f, -r, -l, and perhaps -c.) The default is to
152 maintain no pmlogger (and no other configuration in this section
153 is processed).
154 pmlogconf
157 If and only if this file exists, pmmgr will run pmlogconf to
158 generate a configuration file for each target pmcd. The file
159 contains one line of space-separated additional options for the
160 pmlogconf program. pmlogconf's generated output file will be
161 stored under the log-directory/hostid subdirectory. (pmmgr
162 already adds -c, -r, and -h.) The default is no pmlogconf, so
163 instead, the pmlogger file above should probably contain a -c
164 option, to specify a fixed pmlogger configuration.
165 ARCHIVE LOG MANAGEMENT
168 Default pmlogger configurations can collect tens of megabytes of data
169 per day (possibly split into multiple archives), per target host. If
170 your disk space is less than infinite, or archive-splitting unwieldy,
171 this should be managed. In the default, unmanaged case, the system
172 administrator is responsible for managing the individual archive-*
173 files from the per-host logging subdirectories. pmmgr offers several
174 other options, each representing different performance / usability
175 tradeoffs.
176 ARCHIVE LOG MANAGEMENT - pmlogmerge
179 This style of archive log management regularly creates a single merged
180 archive from prior archives for each target host, in effect lopping off
181 old data and appending the new. A single merged archive can be rela‐
182 tively large (defaults to approximately 100-400 MB per host), and puts
183 a corresponding I/O load on storage, but is most convenient for a
184 detailed long-timeframe analysis. Once pmlogger is restarted, it
185 always creates a new archive, so in the steady state, there will be one
186 merged archive of recent history, and one current archive being writ‐
187 ten-to by pmlogger.
188 pmlogmerge
191 If this file exists, pmmgr will run pmlogextract to periodically
192 merge together preexisting log archives for each target pmcd
193 into a single large one. Then, the preexisting log archives are
194 deleted (including any prior merged ones). This configuration
195 file may contain a time interval specification as per the PCPin‐
196 tro man page, representing the period after which pmlogger
197 should be temporarily stopped, and archives merged. It repre‐
198 sents the maximum amount of time that the merged archive lags
199 the present time. The default is 24hours.
200 pmlogmerge-granular
203 If this file exists, pmmgr will merge only a subset of preexist‐
204 ing log archives into the new one, instead of all of them, so as
205 to approximate a granular, aligned set of merged archives. The
206 subset chosen corresponds to the previous time interval speci‐
207 fied by the pmlogmerge control file. The default is no granu‐
208 larity.
209 pmlogmerge-rewrite
212 If this file exists, pmmgr will run pmlogrewrite -i (plus any
213 other options listed in this file) on each input archive before
214 merging it. This will naturally require more disk I/O. The
215 default is no rewriting.
216 pmlogmerge-retain
219 pmmgr reduces/deletes any original-resolution archives after a
220 time period specified by this file, as measured by the file
221 mtime. The period will also be passed to pmlogextract as a neg‐
222 ative parameter to -S. The default is 14days. To store ar‐
223 chives indefinitely, set this to a large quantity like
224 "99999weeks".
225 pmlogreduce
228 If this file exists, then prior to removing archives that expire
229 past the pmlogmerge-retain period, they are processed with pmlo‐
230 greduce to create reduced archives (named reduced-*). If the
231 file contains space-separated options, they are passed onto
232 pmlogreduce. (By default, pmlogreduce downsamples to a 600-sec‐
233 ond interval.)
234 pmlogreduce-retain
237 If this file exists, then reduced archives (identified by the
238 reduced-* pattern) are deleted after a time period specified by
239 this file, as measured from the file mtime. Since this time is
240 likely that of the pmlogreduce run, the total retention time
241 will be approximately the pmlogmerge-retain time plus the pmlo‐
242 greduce-retain time. The default is 90days. To store reduced
243 archives indefinitely, set this to a large quantity like
244 "99999weeks".
245 PMIE CONFIGURATION
248 This group of configuration options controls a pmie daemon for each
249 host. This may include generating a custom configuration.
250 pmie If and only if this file exists, pmmgr will maintain a pmie dae‐
253 mon for each targeted pmcd. This file contains one line of
254 additional space-separated options for the pmie daemon. (pmmgr
255 already adds -h, -f, -l, and perhaps -c.) The default is to
256 maintain no pmie (and no other configuration in this section is
257 processed).
258 pmieconf
261 If and only if this file exists, pmmgr will run pmieconf to gen‐
262 erate a configuration file for each target pmcd. The file con‐
263 tains one line of space-separated additional options for the
264 pmieconf program. pmieconf's generated output file will be
265 stored under the log-directory/hostid subdirectory. (pmmgr
266 already adds -F, -c, and -f.) The default is no pmieconf, so
267 instead, the pmie file above should probably contain a -c
268 option, to specify a fixed pmie configuration.
269
272 $PCP_SYSCONFIG_DIR/pmmgr/
273 default configuration directory
274 $PCP_LOG_DIR/pmmgr/
275 default logging directory
276
280 Environment variables with the prefix PCP_ are used to parametrize the
281 file and directory names used by PCP. On each installation, the file
282 /etc/pcp.conf contains the local values for these variables. The
283 $PCP_CONF variable may be used to specify an alternative configuration
284 file, as described in pcp.conf(5).
285
289 PCPIntro(1), pmcd(1), pmlogconf(1), pmlogger(1), pmieconf(1), pmie(1),
290 pmlogreduce(1), pcp.conf(5) and pcp.env(5).
291Performance Co-Pilot PCP PMMGR(1)