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