1PMIECTL(1)                  General Commands Manual                 PMIECTL(1)
2
3
4

NAME

6       pmiectl - manage and control Performance Co-Pilot inference engines
7

SYNOPSIS

9       pmiectl [-afmNV?]  [-c class] [-i ident] [-p policy] command [host ...]
10

DESCRIPTION

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
18       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
23       For brevity in the description below, the  term  ``instance''  means  a
24       pmie(1) instance.
25
26       All instances managed by pmiectl, pmie_check(1) and pmie_daily(1) abide
27       by the following rules:
28
29       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
33       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
38       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
45       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
49       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
57       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
61       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
68       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

COMMANDS

73       command is one of the following:
74
75       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
81       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
89           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
93           At least one host must be specified for the create command.
94
95       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
100           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
106           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
113       start
114           Start the target set of instances.
115
116           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
121           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
125       stop
126           Stop the target set of instances.
127
128           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
133           If an instance in the target set is already stopped, no  change  is
134           made but a warning is issued.
135
136       restart
137           Stop and then start the target set of instances.
138
139           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
144           If an instance in the target set is already stopped, a  warning  is
145           issued before the instance is started.
146
147       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
152       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
157           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
162           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
167           The  class  policy  checking  can be by-passed using the -f (force)
168           command line option.
169

CLASS POLICY FILE

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
175       Lines beginning with a hash (#) are treated as  comments  and  ignored.
176       Blank or empty lines are also ignored.
177
178       The  typical  location  of  the  policy  file  for  the  class  foo  is
179       $PCP_SYSCONF_DIR/pmie/class.d/foo.
180
181       [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
186       [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
195       [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
218           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
224           pmiectl will also add the class name during creation. e.g.
225           $class=foo
226
227       [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
233           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
236           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
241           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
246           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
252           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
256       [destroy]
257           The  destroy  section  defines the policy to be applied when an in‐
258           stance is destroyed.
259
260           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
266       A sample class policy file is as follows:
267
268           # policy file for the foo class
269           [class]
270           foo
271           [ident]
272           foo-%h
273
274           [control]
275           $version=1.1
276           %h n n PCP_LOG_DIR/pmie/%i/pmie.log -c foo-metrics.config
277
278           [create]
279           # matches all hosts
280           hostname(.*)
281
282           [destroy]
283           # still to be defined
284

OPTIONS

286       The available command line options are:
287
288       -a, --all
289            Apply action to all matching instances.  By default only  one  in‐
290            stance definition is expected and acted upon.
291
292       -c class, --class=class
293            Set the name of the class for which pmie(1) instances belong to as
294            class.
295
296       -f, --force
297            Force action if possible.
298
299       -i ident, --ident=ident
300            Override instance identifier with ident.  This option applies only
301            for the commands create and cond-create.
302
303       -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
307       -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
314       -p policy, --policy=policy
315            Use   policy   as   the   class   policy   file.    Defaults    to
316            $PCP_SYSCONF_DIR/pmie/class.d/<class>.
317
318       -V, --verbose
319            Enable verbose mode.  Using this option twice increases verbosity.
320
321       -?, --help
322            Display usage message and exit.
323

PCP ENVIRONMENT

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

SEE ALSO

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).
335
336
337
338Performance Co-Pilot                  PCP                           PMIECTL(1)
Impressum