1PMLOGCTL(1) General Commands Manual PMLOGCTL(1)
2
6 pmlogctl - manage and control Performance Co-Pilot archivers
7
9 pmlogctl [-afmNV?] [-C check_args] [-c class] [-i ident] [-p policy]
10 command [host ...]
11
13 pmlogctl may be used to manage non-primary instances of the Performance
14 Co-Pilot (PCP) archiver pmlogger(1). This would be most relevant in a
15 PCP archiver ``farm'' where many pmlogger(1) instances would be creat‐
16 ing archives of performance data collected from pmcd(1) on many remote
17 hosts.
18 The primary pmlogger(1) instance is closely linked to the local pmcd(1)
20 process and as a consequence shares the same control infrastructure,
21 namely systemd(1) or the PCP init(1) ``rc scripts''. This is why the
22 primary pmlogger(1) instance cannot be managed with pmlogctl.
23 For brevity in the description below, the term ``instance'' means a pm‐
25 logger(1) instance.
26 All instances managed by pmlogctl, pmlogger_check(1) and pmlog‐
28 ger_daily(1) abide by the following rules:
29 1. Each instance is fetching performance data from a single pmcd(1)
31 (i.e. one host), but each pmcd(1) may be providing performance data
32 to zero, one or more pmlogger(1) processes running on one or more
33 hosts.
34 2. On the local host, each pmlogger(1) instance must be specified once
36 in a pmlogger_check(1) control file and pmlogger(1) creates archives
37 in a unique directory, named in the 4th parameter of the associated
38 control file entry (see the CONFIGURATION section of pmlog‐
39 ger_check(1)).
40 3. Each instance belongs to exactly one class, optionally named using a
42 $class=... assignment in the associated control file. The special
43 default class is reserved for all instances that do not have an as‐
44 sociated $class=... assignment. For reporting purposes (refer to
45 the summary command below), the primary pmlogger(1) instance is au‐
46 tomatically assigned to the special primary class.
47 Each pmlogctl execution manages one or more instances updating the as‐
49 sociated control files and then running pmlogger_check(1) to effect the
50 desired change.
51 The host arguments are usually valid host names. For all commands ex‐
53 cept create and cond-create (described below) the host arguments may
54 also be egrep(1) regular expressions that match the whole of a valid
55 host name, so the pattern used is actually ^host$. For example foo.*
56 (matches all host names beginning with ``foo'') or .*foo (matches all
57 host names ending with ``foo'') or .*[fF][oO][oO].* (matches all host
58 names containing ``foo'' in upper, lower or mixed case).
59 The combination of a class from the optional -c option (or default) and
61 the host arguments to each command identifies a target of set instances
62 to which the command operation should be applied.
63 The -i option may be used with the create or cond-create commands to
65 override the instance identity that is specified in the ident section
66 of the class policy file (see the CLASS POLICY FILE section below).
67 Since the identifier must be unique across all instances and all
68 classes, it only makes sense to use this option when there is a single
69 host argument.
70 Given the tasks that pmlogctl is undertaking it usually must be run as
72 ``root'', the exceptions being the status command or when the -N option
73 is specified.
74
76 command is one of the following:
77 check
79 Check the status of all currently configured pmlogger instances and
80 restart any that have failed. If the -m flag is given on sys‐
81 temd(1) platforms, also migrate matching (and new) processes to the
82 pmlogger_farm service.
83 create
85 Create new instances in the class classname (default by default)
86 for the host hosts. The name of the class is used to identify a
87 class policy file (see the CLASS POLICY FILE section below) which
88 provides a template for each new control file with %h replaced by
89 host and %i replaced by the instance's (unique) identifier from the
90 ident section of the class policy file or ident from the -i option.
91 The -p option may be used to identify a class policy file other
93 than the one found in the standard place, i.e. $PCP_SYSCONF_DIR/pm‐
94 logger/class.d/classname.
95 At least one host must be specified for the create command.
97 cond-create
99 Similar to create but the instance will only be created if one of
100 the conditions in the create section of associated class policy
101 file(s) evaluates to true.
102 If a -c option is specified, then only the class classname will be
104 considered, otherwise all classes will be considered. In the lat‐
105 ter case, if none of the conditions in any of the classes evaluates
106 to true, the the special pmfind class is used (this is the ``de‐
107 fault'' class for the cond-create command when all else fails).
108 If more than one class evaluates to true then a composite pmlog‐
110 ger(1) configuration file is created and the instance is also as‐
111 signed to the special pmfind class. The composite configuration
112 file may contain a mix of explicit configuration clauses and the
113 more general conditional configuration clauses as understood by the
114 pmlogconf(1) tool.
115 start
117 Start the target set of instances.
118 If the target set intentionally contains more than one instance,
120 then the -a option should be used (this is designed to reduce the
121 risk of accidentally starting a potentially large number of pmlog‐
122 ger(1) processes).
123 If an instance in the target set is already started, no change is
125 made (see the restart command to force new instances to be
126 launched).
127 stop
129 Stop the target set of instances.
130 If the target set intentionally contains more than one instance,
132 then the -a option should be used (this is designed to reduce the
133 risk of accidentally stopping a potentially large number of pmlog‐
134 ger(1) processes).
135 If an instance in the target set is already stopped, no change is
137 made but a warning is issued.
138 restart
140 Stop and then start the target set of instances.
141 If the target set intentionally contains more than one instance,
143 then the -a option should be used (this is designed to reduce the
144 risk of accidentally stopping and starting a potentially large num‐
145 ber of pmlogger(1) processes).
146 If an instance in the target set is already stopped, a warning is
148 issued before the instance is started.
149 status
151 Report the status of the target set of instances. If there is no
152 -c option specified and no host arguments, i.e. the target set is
153 empty, then all instances will be reported.
154 destroy
156 Destroy the target set of instances. At the end of this operation
157 the associated pmlogger(1) processes will have been stopped and the
158 relevant control file information removed.
159 If the target set intentionally contains more than one instance,
161 then the -a option should be used (this is designed to reduce the
162 risk of accidentally terminating a potentially large number of pm‐
163 logger(1) processes and removing their pmlogger_check(1) configura‐
164 tions).
165 The policy file linked to the class of an instance to be destroyed
167 may contain a destroy section that may influence if and how the de‐
168 stroy operation should be performed. This may require a -p option
169 to find the associated class policy file.
170 The class policy checking can be by-passed using the -f (force)
172 command line option.
173
175 A class policy file contains a number of sections, each section begins
176 with a line that simply starts with the name of the section followed
177 enclosed by ``['' and ``]''.
178 Lines beginning with a hash (#) are treated as comments and ignored.
180 Blank or empty lines are also ignored.
181 The typical location of the policy file for the class foo is
183 $PCP_SYSCONF_DIR/pmlogger/class.d/foo.
184 [class]
186 The optional class name section names the class. If it is missing,
187 the name of the policy file (stripped of any directory prefix) is
188 used as the name of the class.
189 [ident]
191 The ident section specifies the template to be used for the in‐
192 stance identifier to be given to each member of the class. This
193 identifier needs to be unique across all instances and all classes,
194 and it needs to be a valid file name in the local filesystem, so
195 would normally contain the class name and the macro %h, e.g.
196 foo-%h. The macro is replaced by the host when each instance is
197 created.
198 [control]
200 The control section consists of one or more lines of template text
201 that will be used to create the control file for each instance.
202 This must at least include the pmlogger_check(1) control line to
203 specify how to start the associated pmlogger(1) process; this line
204 contains fields separated by white space as follows:
205 1. the hostname, usually the macro %h
206 2. n to indicate this is a non-primary instance
207 3. the ``socks'' flag, typically n
208 4. the directory in which the pmlogger(1) archives will be cre‐
209 ated; this needs to be unique and is usually specified using
210 the pmlogger_check(1) macro PCP_ARCHIVE_DIR as the start of the
211 path, followed by the instance identifier, usually the macro
212 %i, e.g. PCP_ARCHIVE_DIR/%i
213 5. additional parameters to pmlogger(1) which probably include at
214 least a -c option to provide a configuration file that de‐
215 scribes which metrics should be logged for instances of this
216 class, which may be the same for all instances in this class,
217 or it may include the %i macro to use a different configuration
218 file for each instance. Note that if this configuration file
219 does not exist, it will be created using pmlogconf(1) the first
220 time pmlogger_check(1) is run.
221 Before the control line there should be a line that defines the
223 version of the control line that follows, i.e.
224 $version=1.1
225 If this is missing, pmlogctl will assume the version is 1.1 and in‐
226 sert the line when the instance is created.
227 pmlogctl will also add the class name during creation. e.g.
229 $class=foo
230 [create]
232 The create section defines the conditions that must be met before
233 an instance will be created with the cond-create command. The in‐
234 tent is to allow different decisions to be made when a new host
235 running pmcd(1) is discovered, e.g. by pmfind(1).
236 Each non-blank line in the create section is a condition of the
238 form function(arg), where function is one of the following:
239 exists
241 arg is the name of a performance metric and exits evaluates to
242 true if that metric exists in the Performance Metrics Name
243 Space (PMNS) on the remote host
244 values
246 arg is the name of a performance metric in the remote PMNS and
247 values evaluates to true if some instance of that metric has a
248 value on the remote host
249 condition
251 arg is a derived metric expression in the format supported by
252 pmRegisterDerived(3), and condition evaluates to true if the
253 value of that expression on the remote host is greater than
254 zero
255 hostname
257 arg is a regular expression in the style of egrep(1) and host‐
258 name evaluates to true if the remote host name matches arg
259 [destroy]
261 The destroy section defines the policy to be applied when an in‐
262 stance is destroyed.
263 The intent is to allow different decisions to be made when discov‐
265 ery service, e.g. pmfind(1), notices that a host associated with
266 an instance is no longer present. But in the current version this
267 is not implemented and the destroy section syntax and semantics is
268 not yet defined.
269 A sample class policy file is as follows:
271 # policy file for the foo class
273 [class]
274 foo
275 [ident]
276 foo-%h
277 [control]
279 $version=1.1
280 %h n n PCP_ARCHIVE_DIR/%i -c foo-metrics.config
281 [create]
283 # matches all hosts
284 hostname(.*)
285 [destroy]
287 # still to be defined
288
290 The available command line options are:
291 -a, --all
293 Apply action to all matching instances. By default only one in‐
294 stance definition is expected and acted upon.
295 -c class, --class=class
297 Set the name of the class for which pmlogger(1) instances belong
298 to as class.
299 -C check_args, --checkargs=check_args
301 check_args are additional command line arguments for pmlog‐
302 ger_check(1) when it is called. This is most useful for options
303 like -V. Multiple -C options may be used and the various
304 check_args options will be accumulated and all passed to pmlog‐
305 ger_check(1).
306 -f, --force
308 Force action if possible.
309 -i ident, --ident=ident
311 Override instance identifier with ident. This option applies only
312 for the commands create and cond-create.
313 -N, --showme
315 Runs pmlogctl in a ``show me'' or ``dry run'' mode where the in‐
316 tent of the command is shown, but no changes are made.
317 -m, --migrate
319 When used with the create or check commands on systemd(1) plat‐
320 forms, also migrate new or existing non-primary pmlogger processes
321 to the pmlogger_farm service. This is normally done automatically
322 by the pmlogger_farm_check service, which is timer driven (so
323 there may be a few minutes delay before automatic migration is
324 initiated).
325 -p policy, --policy=policy
327 Use policy as the class policy file. Defaults to
328 $PCP_SYSCONF_DIR/pmlogger/class.d/<class>.
329 -V, --verbose
331 Enable verbose mode. Using this option twice increases verbosity.
332 -?, --help
334 Display usage message and exit.
335
337 Environment variables with the prefix PCP_ are used to parameterize the
338 file and directory names used by PCP. On each installation, the file
339 /etc/pcp.conf contains the local values for these variables. The
340 $PCP_CONF variable may be used to specify an alternative configuration
341 file, as described in pcp.conf(5).
342
344 egrep(1), init(1), PCPIntro(1), pmcd(1), pmlc(1), pmlogconf(1), pmlog‐
345 ger(1), pmlogger_check(1), pmlogger_daily(1), systemd(1), PMAPI(3),
346 pmDerivedRegister(3) and pcp.conf(5).
347Performance Co-Pilot PCP PMLOGCTL(1)