1PMIECTL(1) General Commands Manual PMIECTL(1)
2
6 pmiectl - manage and control Performance Co-Pilot inference engines
7
9 pmiectl [-afNV?] [-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 create
76 Create new instances in the class classname (default by default)
77 for the host hosts. The name of the class is used to identify a
78 class policy file (see the CLASS POLICY FILE section below) which
79 provides a template for each new control file with %h replaced by
80 host and %i replaced by the instance's (unique) identifier from the
81 ident section of the class policy file or ident from the -i option.
82 The -p option may be used to identify a class policy file other
84 than the one found in the standard place, i.e.
85 $PCP_SYSCONF_DIR/pmie/class.d/classname.
86 At least one host must be specified for the create command.
88 cond-create
90 Similar to create but the instance will only be created if one of
91 the conditions in the create section of associated class policy
92 file(s) evaluates to true.
93 If a -c option is specified, then only the class classname will be
95 considered, otherwise all classes will be considered. In the lat‐
96 ter case, if none of the conditions in any of the classes evaluates
97 to true, the the special pmfind class is used (this is the ``de‐
98 fault'' class for the cond-create command when all else fails).
99 If more than one class evalutes to true then a composite pmie(1)
101 configuration file is created and the instance is also assigned to
102 the special pmfind class. The composite configuration file may
103 contain a mix of explicit configuration clauses and the more gen‐
104 eral conditional configuration clauses as understood by the
105 pmieconf(1) tool.
106 start
108 Start the target set of instances.
109 If the target set intentionally contains more than one instance,
111 then the -a option should be used (this is designed to reduce the
112 risk of accidentally starting a potentially large number of pmie(1)
113 processes).
114 If an instance in the target set is already started, no change is
116 made (see the restart command to force new instances to be
117 launched).
118 stop
120 Stop the target set of instances.
121 If the target set intentionally contains more than one instance,
123 then the -a option should be used (this is designed to reduce the
124 risk of accidentally stopping a potentially large number of pmie(1)
125 processes).
126 If an instance in the target set is already stopped, no change is
128 made but a warning is issued.
129 restart
131 Stop and then start the target set of instances.
132 If the target set intentionally contains more than one instance,
134 then the -a option should be used (this is designed to reduce the
135 risk of accidentally stopping and starting a potentially large num‐
136 ber of pmie(1) processes).
137 If an instance in the target set is already stopped, a warning is
139 issued before the instance is started.
140 status
142 Report the status of the target set of instances. If there is no
143 -c option specified and no host arguments, i.e. the target set is
144 empty, then all instances will be reported.
145 destroy
147 Destroy the target set of instances. At the end of this operation
148 the associated pmie(1) processes will have been stopped and the
149 relevant control file information removed.
150 If the target set intentionally contains more than one instance,
152 then the -a option should be used (this is designed to reduce the
153 risk of accidentally terminating a potentially large number of
154 pmie(1) processes and removing their pmie_check(1) configurations).
155 The policy file linked to the class of an instance to be destroyed
157 may contain a destroy section that may influence if and how the de‐
158 stroy operation should be performed. This may require a -p option
159 to find the associated class policy file.
160 The class policy checking can be by-passed using the -f (force)
162 command line option.
163
165 A class policy file contains a number of sections, each section begins
166 with a line that simply starts with the name of the section followed
167 enclosed by ``['' and ``]''.
168 Lines beginning with a hash (#) are treated as comments and ignored.
170 Blank or empty lines are also ignored.
171 The typical location of the policy file for the class foo is
173 $PCP_SYSCONF_DIR/pmie/class.d/foo.
174 [class]
176 The optional class name section names the class. If it is missing,
177 the name of the policy file (stripped of any directory prefix) is
178 used as the name of the class.
179 [ident]
181 The ident section specifies the template to be used for the in‐
182 stance identifier to be given to each member of the class. This
183 identifier needs to be unique across all instances and all classes,
184 and it needs to be a valid file name in the local filesystem, so
185 would normally contain the class name and the macro %h, e.g.
186 foo-%h. The macro is replaced by the host when each instance is
187 created.
188 [control]
190 The control section consists of one or more lines of template text
191 that will be used to create the control file for each instance.
192 This must at least include the pmie_check(1) control line to spec‐
193 ify how to start the associated pmie(1) process; this line contains
194 fields separated by white space as follows:
195 1. the hostname, usually the macro %h
196 2. n to indicate this is a non-primary instance
197 3. the ``socks'' flag, typically n
198 4. the pathname used by pmie(1) for the log file; this needs to be
199 unique and is usually specified using the pmie_check(1) macro
200 PCP_LOG_DIR as the start of the path, followed by pmie, and
201 then the instance's unique directory %i, e.g.
202 PCP_LOG_DIR/pmie/%i/pmie.log
203 5. additional parameters to pmie(1) which probably include at
204 least a -c option to provide a configuration file that de‐
205 scribes which rules should be evaluated for instances of this
206 class, which may be the same for all instances in this class,
207 or it may include the %i macro to use a different configuration
208 file for each instance. Note that if this configuration file
209 does not exist, it will be created using pmieconf(1) the first
210 time pmie_check(1) is run.
211 Before the control line there should be a line that defines the
213 version of the control line that follows, i.e.
214 $version=1.1
215 If this is missing, pmiectl will assume the version is 1.1 and in‐
216 sert the line when the instance is created.
217 pmiectl will also add the class name during creation. e.g.
219 $class=foo
220 [create]
222 The create section defines the conditions that must be met before
223 an instance will be created with the cond-create command. The in‐
224 tent is to allow different decisions to be made when a new host
225 running pmcd(1) is discovered, e.g. by pmfind(1).
226 Each non-blank line in the create section is a condition of the
228 form function(arg), where function is one of the following:
229 exists
231 arg is the name of a performance metric and exits evaluates to
232 true if that metric exists in the Performance Metrics Name
233 Space (PMNS) on the remote host
234 values
236 arg is the name of a performance metric in the remote PMNS and
237 values evaluates to true if some instance of that metric has a
238 value on the remote host
239 condition
241 arg is a derived metric expression in the format supported by
242 pmRegisterDerived(3), and condition evaluates to true if the
243 value of that expression on the remote host is greater than
244 zero
245 hostname
247 arg is a regular expression in the style of egrep(1) and host‐
248 name evaluates to true if the remote host name matches arg
249 [destroy]
251 The destroy section defines the policy to be applied when an in‐
252 stance is destroyed.
253 The intent is to allow different decisions to be made when discov‐
255 ery service, e.g. pmfind(1), notices that a host associated with
256 an instance is no longer present. But in the current version this
257 is not implemented and the destroy section syntax and semantics is
258 not yet defined.
259 A sample class policy file is as follows:
261 # policy file for the foo class
263 [class]
264 foo
265 [ident]
266 foo-%h
267 [control]
269 $version=1.1
270 %h n n PCP_LOG_DIR/pmie/%i/pmie.log -c foo-metrics.config
271 [create]
273 # matches all hosts
274 hostname(.*)
275 [destroy]
277 # still to be defined
278
280 The available command line options are:
281 -a, --all
283 Apply action to all matching instances. By default only one in‐
284 stance definition is expected and acted upon.
285 -c class, --class=class
287 Set the name of the class for which pmie(1) instances belong to as
288 class.
289 -f, --force
291 Force action if possible.
292 -i ident, --ident=ident
294 Override instance identifier with ident. This option applies only
295 for the commands create and cond-create.
296 -N, --showme
298 Runs pmiectl in a ``show me'' or ``dry run'' mode where the intent
299 of the command is shown, but no changes are made.
300 -p policy, --policy=policy
302 Use policy as the class policy file. Defaults to
303 $PCP_SYSCONF_DIR/pmie/class.d/<class>.
304 -V, --verbose
306 Enable verbose mode. Using this option twice increases verbosity.
307 -?, --help
309 Display usage message and exit.
310
312 Environment variables with the prefix PCP_ are used to parameterize the
313 file and directory names used by PCP. On each installation, the file
314 /etc/pcp.conf contains the local values for these variables. The
315 $PCP_CONF variable may be used to specify an alternative configuration
316 file, as described in pcp.conf(5).
317
319 egrep(1), init(1), PCPIntro(1), pmcd(1), pmieconf(1), pmie(1),
320 pmie_check(1), pmie_daily(1), systemd(1), PMAPI(3), pmDerivedRegis‐
321 ter(3) and pcp.conf(5).
322Performance Co-Pilot PCP PMIECTL(1)