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  [-afNV?]   [-c  classname]  [-i ident] [-p policyfile] command
10       [host ...]
11

DESCRIPTION

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
19       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
24       For  brevity  in  the  description below, the term ``instance'' means a
25       pmie(1) instance.
26
27       All instances managed by pmiectl, pmie_check(1) and pmie_daily(1) abide
28       by the following rules:
29
30       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
34       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
39       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
42          associated $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
46       Each pmiectl execution manages one or more instances updating the asso‐
47       ciated control files and  then  running  pmie_check(1)  to  effect  the
48       desired change.
49
50       The  host  arguments  are  usually  valid host names.  For all commands
51       except 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
58       The combination of a classname from the optional -c option (or default)
59       and the host arguments to each  command  identifies  a  target  of  set
60       instances to which the command operation should be applied.
61
62       The  -N option runs pmiectl in ``show me'' mode where the intent of the
63       command is shown, but no changes are made.
64
65       The -i option may be used with the create or  cond-create  commands  to
66       over-ride  the instance identity that is specified in the ident section
67       of the class policy file (see the CLASS  POLICY  FILE  section  below).
68       Since  the  identifier  must  be  unique  across  all instances and all
69       classes, it only makes sense to use this option when there is a  single
70       host argument.
71
72       The  -V option generally increases the verbosity of the output.  A sec‐
73       ond -V makes pmiectl very chatty.
74
75       Given the tasks that pmiectl is undertaking it usually must  be  run  a
76       ``root'', the exceptions being the status command or when the -N option
77       is specified.
78

COMMANDS

80       command is one of the following:
81
82       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
90           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_ETC_DIR/pcp/pmie/class.d/classname.
93
94           At least one host must be specified for the create command.
95
96       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
101           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
105           ``default'' class for the cond-create command when all else fails).
106
107           If  more  than  one class evalutes 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
114       start
115           Start the target set of instances.
116
117           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
122           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
126       stop
127           Stop the target set of instances.
128
129           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
134           If an instance in the target set is already stopped, no  change  is
135           made but a warning is issued.
136
137       restart
138           Stop and then start the target set of instances.
139
140           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
145           If an instance in the target set is already stopped, a  warning  is
146           issued before the instance is started.
147
148       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
153       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
158           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
163           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
165           destroy operation should be  performed.   This  may  require  a  -p
166           option to find the associated class policy file.
167
168           The  class  policy  checking  can be by-passed using the -f (force)
169           command line option.
170

CLASS POLICY FILE

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
176       Lines beginning with a hash (#) are treated as  comments  and  ignored.
177       Blank or empty lines are also ignored.
178
179       The  typical  location  of  the  policy  file  for  the  class  foo  is
180       $PCP_ETC_DIR/pcp/pmie/class.d/foo.
181
182       [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
187       [ident]
188           The ident section  specifies  the  template  to  be  used  for  the
189           instance  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
196       [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
212               describes 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
219           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
223           insert the line when the instance is created.
224
225           pmiectl will also add the class name during creation. e.g.
226           $class=foo
227
228       [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
231           intent  is  to allow different decisions to be made when a new host
232           running pmcd(1) is discovered, e.g. by pmfind(1).
233
234           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
237           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
242           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
247           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
253           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
257       [destroy]
258           The  destroy  section  defines  the  policy  to  be applied when an
259           instance is destroyed.
260
261           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
267       A sample class policy file is as follows:
268
269           # policy file for the foo class
270           [class]
271           foo
272           [ident]
273           foo-%h
274
275           [control]
276           $version=1.1
277           %h n n PCP_LOG_DIR/pmie/%i/pmie.log -c foo-metrics.config
278
279           [create]
280           # matches all hosts
281           hostname(.*)
282
283           [destroy]
284           # still to be defined
285

DIAGNOSTICS

287       Most error or warning messages are self-explanatory.
288

PCP ENVIRONMENT

290       Environment variables with the prefix PCP_ are used to parameterize the
291       file  and  directory names used by PCP.  On each installation, the file
292       /etc/pcp.conf contains the  local  values  for  these  variables.   The
293       $PCP_CONF  variable may be used to specify an alternative configuration
294       file, as described in pcp.conf(5).
295

SEE ALSO

297       egrep(1),  init(1),   PCPIntro(1),   pmcd(1),   pmieconf(1),   pmie(1),
298       pmie_check(1),  pmie_daily(1),  systemd(1),  PMAPI(3),  pmDerivedRegis‐
299       ter(3) and pcp.conf(5).
300
301
302
303Performance Co-Pilot                  PCP                           PMIECTL(1)
Impressum