1PMIECTL(1) General Commands Manual PMIECTL(1)
2
6 pmiectl - manage and control Performance Co-Pilot inference engines
7
9 pmiectl [-afmNV?] [-C check_args] [-c class] [-i ident] [-p policy]
10 command [host ...]
11
13 pmiectl may be used to manage non-primary instances of the Performance
14 Co-Pilot (PCP) inference engine pmie(1). This would be most relevant
15 in a PCP inference engine ``farm'' where many pmie(1) instances would
16 be evaluating rules against the performance data collected from pmcd(1)
17 on many remote hosts.
18 The primary pmie(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 pmie(1) instance cannot be managed with pmiectl.
23 For brevity in the description below, the term ``instance'' means a
25 pmie(1) instance.
26 All instances managed by pmiectl, pmie_check(1) and pmie_daily(1) abide
28 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 pmie(1) processes running on one or more hosts.
33 2. On the local host, each pmie(1) instance must be specified once in a
35 pmie_check(1) control file and pmie(1) creates a unique log file,
36 named in the 4th parameter of the associated control file entry (see
37 the CONFIGURATION section of pmie_check(1)).
38 3. Each instance belongs to exactly one class, optionally named using a
40 $class=... assignment in the associated control file. The special
41 default class is reserved for all instances that do not have an as‐
42 sociated $class=... assignment. For reporting purposes (refer to
43 the summary command below), the primary pmie(1) instance is automat‐
44 ically assigned to the special primary class.
45 Each pmiectl execution manages one or more instances updating the asso‐
47 ciated control files and then running pmie_check(1) to effect the de‐
48 sired change.
49 The host arguments are usually valid host names. For all commands ex‐
51 cept create and cond-create (described below) the host arguments may
52 also be egrep(1) regular expressions that match the whole of a valid
53 host name, so the pattern used is actually ^host$. For example foo.*
54 (matches all host names beginning with ``foo'') or .*foo (matches all
55 host names ending with ``foo'') or .*[fF][oO][oO].* (matches all host
56 names containing ``foo'' in upper, lower or mixed case).
57 The combination of a class from the optional -c option (or default) and
59 the host arguments to each command identifies a target of set instances
60 to which the command operation should be applied.
61 The -i option may be used with the create or cond-create commands to
63 override the instance identity that is specified in the ident section
64 of the class policy file (see the CLASS POLICY FILE section below).
65 Since the identifier must be unique across all instances and all
66 classes, it only makes sense to use this option when there is a single
67 host argument.
68 Given the tasks that pmiectl is undertaking it usually must be run as
70 ``root'', the exceptions being the status command or when the -N option
71 is specified.
72
74 command is one of the following:
75 check
77 Check the status of all currently configured pmie instances and
78 restart any that have failed. If the -m flag is given on sys‐
79 temd(1) platforms, also migrate matching (and new) processes to the
80 pmie_farm service.
81 create
83 Create new instances in the class classname (default by default)
84 for the host hosts. The name of the class is used to identify a
85 class policy file (see the CLASS POLICY FILE section below) which
86 provides a template for each new control file with %h replaced by
87 host and %i replaced by the instance's (unique) identifier from the
88 ident section of the class policy file or ident from the -i option.
89 The -p option may be used to identify a class policy file other
91 than the one found in the standard place, i.e.
92 $PCP_SYSCONF_DIR/pmie/class.d/classname.
93 At least one host must be specified for the create command.
95 cond-create
97 Similar to create but the instance will only be created if one of
98 the conditions in the create section of associated class policy
99 file(s) evaluates to true.
100 If a -c option is specified, then only the class classname will be
102 considered, otherwise all classes will be considered. In the lat‐
103 ter case, if none of the conditions in any of the classes evaluates
104 to true, the the special pmfind class is used (this is the ``de‐
105 fault'' class for the cond-create command when all else fails).
106 If more than one class evaluates to true then a composite pmie(1)
108 configuration file is created and the instance is also assigned to
109 the special pmfind class. The composite configuration file may
110 contain a mix of explicit configuration clauses and the more gen‐
111 eral conditional configuration clauses as understood by the
112 pmieconf(1) tool.
113 start
115 Start the target set of instances.
116 If the target set intentionally contains more than one instance,
118 then the -a option should be used (this is designed to reduce the
119 risk of accidentally starting a potentially large number of pmie(1)
120 processes).
121 If an instance in the target set is already started, no change is
123 made (see the restart command to force new instances to be
124 launched).
125 stop
127 Stop the target set of instances.
128 If the target set intentionally contains more than one instance,
130 then the -a option should be used (this is designed to reduce the
131 risk of accidentally stopping a potentially large number of pmie(1)
132 processes).
133 If an instance in the target set is already stopped, no change is
135 made but a warning is issued.
136 restart
138 Stop and then start the target set of instances.
139 If the target set intentionally contains more than one instance,
141 then the -a option should be used (this is designed to reduce the
142 risk of accidentally stopping and starting a potentially large num‐
143 ber of pmie(1) processes).
144 If an instance in the target set is already stopped, a warning is
146 issued before the instance is started.
147 status
149 Report the status of the target set of instances. If there is no
150 -c option specified and no host arguments, i.e. the target set is
151 empty, then all instances will be reported.
152 destroy
154 Destroy the target set of instances. At the end of this operation
155 the associated pmie(1) processes will have been stopped and the
156 relevant control file information removed.
157 If the target set intentionally contains more than one instance,
159 then the -a option should be used (this is designed to reduce the
160 risk of accidentally terminating a potentially large number of
161 pmie(1) processes and removing their pmie_check(1) configurations).
162 The policy file linked to the class of an instance to be destroyed
164 may contain a destroy section that may influence if and how the de‐
165 stroy operation should be performed. This may require a -p option
166 to find the associated class policy file.
167 The class policy checking can be by-passed using the -f (force)
169 command line option.
170
172 A class policy file contains a number of sections, each section begins
173 with a line that simply starts with the name of the section followed
174 enclosed by ``['' and ``]''.
175 Lines beginning with a hash (#) are treated as comments and ignored.
177 Blank or empty lines are also ignored.
178 The typical location of the policy file for the class foo is
180 $PCP_SYSCONF_DIR/pmie/class.d/foo.
181 [class]
183 The optional class name section names the class. If it is missing,
184 the name of the policy file (stripped of any directory prefix) is
185 used as the name of the class.
186 [ident]
188 The ident section specifies the template to be used for the in‐
189 stance identifier to be given to each member of the class. This
190 identifier needs to be unique across all instances and all classes,
191 and it needs to be a valid file name in the local filesystem, so
192 would normally contain the class name and the macro %h, e.g.
193 foo-%h. The macro is replaced by the host when each instance is
194 created.
195 [control]
197 The control section consists of one or more lines of template text
198 that will be used to create the control file for each instance.
199 This must at least include the pmie_check(1) control line to spec‐
200 ify how to start the associated pmie(1) process; this line contains
201 fields separated by white space as follows:
202 1. the hostname, usually the macro %h
203 2. n to indicate this is a non-primary instance
204 3. the ``socks'' flag, typically n
205 4. the pathname used by pmie(1) for the log file; this needs to be
206 unique and is usually specified using the pmie_check(1) macro
207 PCP_LOG_DIR as the start of the path, followed by pmie, and
208 then the instance's unique directory %i, e.g.
209 PCP_LOG_DIR/pmie/%i/pmie.log
210 5. additional parameters to pmie(1) which probably include at
211 least a -c option to provide a configuration file that de‐
212 scribes which rules should be evaluated for instances of this
213 class, which may be the same for all instances in this class,
214 or it may include the %i macro to use a different configuration
215 file for each instance. Note that if this configuration file
216 does not exist, it will be created using pmieconf(1) the first
217 time pmie_check(1) is run.
218 Before the control line there should be a line that defines the
220 version of the control line that follows, i.e.
221 $version=1.1
222 If this is missing, pmiectl will assume the version is 1.1 and in‐
223 sert the line when the instance is created.
224 pmiectl will also add the class name during creation. e.g.
226 $class=foo
227 [create]
229 The create section defines the conditions that must be met before
230 an instance will be created with the cond-create command. The in‐
231 tent is to allow different decisions to be made when a new host
232 running pmcd(1) is discovered, e.g. by pmfind(1).
233 Each non-blank line in the create section is a condition of the
235 form function(arg), where function is one of the following:
236 exists
238 arg is the name of a performance metric and exits evaluates to
239 true if that metric exists in the Performance Metrics Name
240 Space (PMNS) on the remote host
241 values
243 arg is the name of a performance metric in the remote PMNS and
244 values evaluates to true if some instance of that metric has a
245 value on the remote host
246 condition
248 arg is a derived metric expression in the format supported by
249 pmRegisterDerived(3), and condition evaluates to true if the
250 value of that expression on the remote host is greater than
251 zero
252 hostname
254 arg is a regular expression in the style of egrep(1) and host‐
255 name evaluates to true if the remote host name matches arg
256 [destroy]
258 The destroy section defines the policy to be applied when an in‐
259 stance is destroyed.
260 The intent is to allow different decisions to be made when discov‐
262 ery service, e.g. pmfind(1), notices that a host associated with
263 an instance is no longer present. But in the current version this
264 is not implemented and the destroy section syntax and semantics is
265 not yet defined.
266 A sample class policy file is as follows:
268 # policy file for the foo class
270 [class]
271 foo
272 [ident]
273 foo-%h
274 [control]
276 $version=1.1
277 %h n n PCP_LOG_DIR/pmie/%i/pmie.log -c foo-metrics.config
278 [create]
280 # matches all hosts
281 hostname(.*)
282 [destroy]
284 # still to be defined
285
287 The available command line options are:
288 -a, --all
290 Apply action to all matching instances. By default only one in‐
291 stance definition is expected and acted upon.
292 -c class, --class=class
294 Set the name of the class for which pmie(1) instances belong to as
295 class.
296 -C check_args, --checkargs=check_args
298 check_args are additional command line arguments for pmie_check(1)
299 when it is called. This is most useful for options like -V. Mul‐
300 tiple -C options may be used and the various check_args options
301 will be accumulated and all passed to pmie_check(1).
302 -f, --force
304 Force action if possible.
305 -i ident, --ident=ident
307 Override instance identifier with ident. This option applies only
308 for the commands create and cond-create.
309 -N, --showme
311 Runs pmiectl in a ``show me'' or ``dry run'' mode where the intent
312 of the command is shown, but no changes are made.
313 -m, --migrate
315 When used with the create or check commands on systemd(1) plat‐
316 forms, also migrate new or existing non-primary pmie processes to
317 the pmie_farm service. This is normally done automatically by the
318 pmie_farm_check service, which is timer driven (so there may be a
319 few minutes delay before automatic migration is initiated).
320 -p policy, --policy=policy
322 Use policy as the class policy file. Defaults to
323 $PCP_SYSCONF_DIR/pmie/class.d/<class>.
324 -V, --verbose
326 Enable verbose mode. Using this option twice increases verbosity.
327 -?, --help
329 Display usage message and exit.
330
332 Environment variables with the prefix PCP_ are used to parameterize the
333 file and directory names used by PCP. On each installation, the file
334 /etc/pcp.conf contains the local values for these variables. The
335 $PCP_CONF variable may be used to specify an alternative configuration
336 file, as described in pcp.conf(5).
337
339 egrep(1), init(1), PCPIntro(1), pmcd(1), pmieconf(1), pmie(1),
340 pmie_check(1), pmie_daily(1), systemd(1), PMAPI(3), pmDerivedRegis‐
341 ter(3) and pcp.conf(5).
342Performance Co-Pilot PCP PMIECTL(1)