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

NAME

6       pmlogctl - manage and control Performance Co-Pilot archive loggers
7

SYNOPSIS

9       pmlogctl  [-afNV?]   [-c  classname] [-i ident] [-p policyfile] command
10       [host ...]
11

DESCRIPTION

13       pmlogctl may be used to manage non-primary instances of the Performance
14       Co-Pilot  (PCP) archiver pmlogger(1).  This would be most relevant in a
15       PCP archive logger ``farm'' where many pmlogger(1) instances  would  be
16       creating  archives  of  performance data collected from pmcd(1) on many
17       remote hosts.
18
19       The primary pmlogger(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 pmlogger(1) instance cannot be managed with pmlogctl.
23
24       For  brevity  in  the  description below, the term ``instance'' means a
25       pmlogger(1) instance.
26
27       All  instances  managed  by  pmlogctl,  pmlogger_check(1)  and   pmlog‐
28       ger_daily(1) abide 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 pmlogger(1) processes running on one or more
33          hosts.
34
35       2. On the local host, each pmlogger(1) instance must be specified  once
36          in a pmlogger_check(1) control file and pmlogger(1) creates archives
37          in a unique directory, named in the 4th parameter of the  associated
38          control   file  entry  (see  the  CONFIGURATION  section  of  pmlog‐
39          ger_check(1)).
40
41       3. Each instance belongs to exactly one class, optionally named using a
42          $class=...   assignment in the associated control file.  The special
43          default class is reserved for all instances  that  do  not  have  an
44          associated $class=...  assignment.  For reporting purposes (refer to
45          the summary command below),  the  primary  pmlogger(1)  instance  is
46          automatically assigned to the special primary class.
47
48       Each  pmlogctl  execution  manages  one  or more instances updating the
49       associated control files and then running pmlogger_check(1)  to  effect
50       the desired change.
51
52       The  host  arguments  are  usually  valid host names.  For all commands
53       except create and cond-create (described below) the host arguments  may
54       also  be  egrep(1)  regular expressions that match the whole of a valid
55       host name, so the pattern used is actually ^host$.  For  example  foo.*
56       (matches  all  host names beginning with ``foo'') or .*foo (matches all
57       host names ending with ``foo'') or .*[fF][oO][oO].*  (matches all  host
58       names containing ``foo'' in upper, lower or mixed case).
59
60       The combination of a classname from the optional -c option (or default)
61       and the host arguments to each  command  identifies  a  target  of  set
62       instances to which the command operation should be applied.
63
64       The -N option runs pmlogctl in ``show me'' mode where the intent of the
65       command is shown, but no changes are made.
66
67       The -i option may be used with the create or  cond-create  commands  to
68       over-ride  the instance identity that is specified in the ident section
69       of the class policy file (see the CLASS  POLICY  FILE  section  below).
70       Since  the  identifier  must  be  unique  across  all instances and all
71       classes, it only makes sense to use this option when there is a  single
72       host argument.
73
74       The  -V option generally increases the verbosity of the output.  A sec‐
75       ond -V makes pmlogctl very chatty.
76
77       Given the tasks that pmlogctl is undertaking it usually must be  run  a
78       ``root'', the exceptions being the status command or when the -N option
79       is specified.
80

COMMANDS

82       command is one of the following:
83
84       create
85           Create new instances in the class classname  (default  by  default)
86           for  the  host  hosts.  The name of the class is used to identify a
87           class policy file (see the CLASS POLICY FILE section  below)  which
88           provides  a  template for each new control file with %h replaced by
89           host and %i replaced by the instance's (unique) identifier from the
90           ident section of the class policy file or ident from the -i option.
91
92           The  -p  option  may  be used to identify a class policy file other
93           than   the   one   found    in    the    standard    place,    i.e.
94           $PCP_ETC_DIR/pcp/pmlogger/class.d/classname.
95
96           At least one host must be specified for the create command.
97
98       cond-create
99           Similar  to  create but the instance will only be created if one of
100           the conditions in the create section  of  associated  class  policy
101           file(s) evaluates to true.
102
103           If  a -c option is specified, then only the class classname will be
104           considered, otherwise all classes will be considered.  In the  lat‐
105           ter case, if none of the conditions in any of the classes evaluates
106           to true, the  the  special  pmfind  class  is  used  (this  is  the
107           ``default'' class for the cond-create command when all else fails).
108
109           If  more  than  one  class evalutes to true then a composite pmlog‐
110           ger(1) configuration file is  created  and  the  instance  is  also
111           assigned  to the special pmfind class.  The composite configuration
112           file may contain a mix of explicit configuration  clauses  and  the
113           more general conditional configuration clauses as understood by the
114           pmlogconf(1) tool.
115
116       start
117           Start the target set of instances.
118
119           If the target set intentionally contains more  than  one  instance,
120           then  the  -a option should be used (this is designed to reduce the
121           risk of accidentally starting a potentially large number of  pmlog‐
122           ger(1) processes).
123
124           If  an  instance in the target set is already started, no change is
125           made (see  the  restart  command  to  force  new  instances  to  be
126           launched).
127
128       stop
129           Stop the target set of instances.
130
131           If  the  target  set intentionally contains more than one instance,
132           then the -a option should be used (this is designed to  reduce  the
133           risk  of accidentally stopping a potentially large number of pmlog‐
134           ger(1) processes).
135
136           If an instance in the target set is already stopped, no  change  is
137           made but a warning is issued.
138
139       restart
140           Stop and then start the target set of instances.
141
142           If  the  target  set intentionally contains more than one instance,
143           then the -a option should be used (this is designed to  reduce  the
144           risk of accidentally stopping and starting a potentially large num‐
145           ber of pmlogger(1) processes).
146
147           If an instance in the target set is already stopped, a  warning  is
148           issued before the instance is started.
149
150       status
151           Report  the  status of the target set of instances.  If there is no
152           -c option specified and no host arguments, i.e. the target  set  is
153           empty, then all instances will be reported.
154
155       destroy
156           Destroy  the target set of instances.  At the end of this operation
157           the associated pmlogger(1) processes will have been stopped and the
158           relevant control file information removed.
159
160           If  the  target  set intentionally contains more than one instance,
161           then the -a option should be used (this is designed to  reduce  the
162           risk  of  accidentally  terminating  a  potentially large number of
163           pmlogger(1) processes and removing their pmlogger_check(1) configu‐
164           rations).
165
166           The  policy file linked to the class of an instance to be destroyed
167           may contain a destroy section that may influence  if  and  how  the
168           destroy  operation  should  be  performed.   This  may require a -p
169           option to find the associated class policy file.
170
171           The class policy checking can be by-passed  using  the  -f  (force)
172           command line option.
173

CLASS POLICY FILE

175       A  class policy file contains a number of sections, each section begins
176       with a line that simply starts with the name of  the  section  followed
177       enclosed by ``['' and ``]''.
178
179       Lines  beginning  with  a hash (#) are treated as comments and ignored.
180       Blank or empty lines are also ignored.
181
182       The  typical  location  of  the  policy  file  for  the  class  foo  is
183       $PCP_ETC_DIR/pcp/pmlogger/class.d/foo.
184
185       [class]
186           The optional class name section names the class.  If it is missing,
187           the name of the policy file (stripped of any directory  prefix)  is
188           used as the name of the class.
189
190       [ident]
191           The  ident  section  specifies  the  template  to  be  used for the
192           instance identifier to be given to each member of the class.   This
193           identifier needs to be unique across all instances and all classes,
194           and it needs to be a valid file name in the  local  filesystem,  so
195           would  normally  contain  the  class  name  and  the macro %h, e.g.
196           foo-%h.  The macro is replaced by the host when  each  instance  is
197           created.
198
199       [control]
200           The  control section consists of one or more lines of template text
201           that will be used to create the control  file  for  each  instance.
202           This  must  at  least include the pmlogger_check(1) control line to
203           specify how to start the associated pmlogger(1) process; this  line
204           contains fields separated by white space as follows:
205           1.  the hostname, usually the macro %h
206           2.  n to indicate this is a non-primary instance
207           3.  the ``socks'' flag, typically n
208           4.  the  directory  in  which the pmlogger(1) archives will be cre‐
209               ated; this needs to be unique and is  usually  specified  using
210               the pmlogger_check(1) macro PCP_ARCHIVE_DIR as the start of the
211               path, followed by the instance identifier,  usually  the  macro
212               %i, e.g. PCP_ARCHIVE_DIR/%i
213           5.  additional  parameters to pmlogger(1) which probably include at
214               least  a  -c  option  to  provide  a  configuration  file  that
215               describes  which metrics should be logged for instances of this
216               class, which may be the same for all instances in  this  class,
217               or it may include the %i macro to use a different configuration
218               file for each instance.  Note that if this  configuration  file
219               does not exist, it will be created using pmlogconf(1) the first
220               time pmlogger_check(1) is run.
221
222           Before the control line there should be a  line  that  defines  the
223           version of the control line that follows, i.e.
224           $version=1.1
225           If  this  is  missing,  pmlogctl will assume the version is 1.1 and
226           insert the line when the instance is created.
227
228           pmlogctl will also add the class name during creation. e.g.
229           $class=foo
230
231       [create]
232           The create section defines the conditions that must be  met  before
233           an  instance  will  be  created  with the cond-create command.  The
234           intent is to allow different decisions to be made when a  new  host
235           running pmcd(1) is discovered, e.g. by pmfind(1).
236
237           Each  non-blank  line  in  the create section is a condition of the
238           form function(arg), where function is one of the following:
239
240           exists
241               arg is the name of a performance metric and exits evaluates  to
242               true  if  that  metric  exists  in the Performance Metrics Name
243               Space (PMNS) on the remote host
244
245           values
246               arg is the name of a performance metric in the remote PMNS  and
247               values  evaluates to true if some instance of that metric has a
248               value on the remote host
249
250           condition
251               arg is a derived metric expression in the format  supported  by
252               pmRegisterDerived(3),  and  condition  evaluates to true if the
253               value of that expression on the remote  host  is  greater  than
254               zero
255
256           hostname
257               arg  is a regular expression in the style of egrep(1) and host‐
258               name evaluates to true if the remote host name matches arg
259
260       [destroy]
261           The destroy section defines  the  policy  to  be  applied  when  an
262           instance is destroyed.
263
264           The  intent is to allow different decisions to be made when discov‐
265           ery service, e.g.  pmfind(1), notices that a host  associated  with
266           an  instance is no longer present.  But in the current version this
267           is not implemented and the destroy section syntax and semantics  is
268           not yet defined.
269
270       A sample class policy file is as follows:
271
272           # policy file for the foo class
273           [class]
274           foo
275           [ident]
276           foo-%h
277
278           [control]
279           $version=1.1
280           %h n n PCP_ARCHIVE_DIR/%i -c foo-metrics.config
281
282           [create]
283           # matches all hosts
284           hostname(.*)
285
286           [destroy]
287           # still to be defined
288

DIAGNOSTICS

290       Most error or warning messages are self-explanatory.
291

PCP ENVIRONMENT

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

SEE ALSO

300       egrep(1),  init(1), PCPIntro(1), pmcd(1), pmlc(1), pmlogconf(1), pmlog‐
301       ger(1),  pmlogger_check(1),  pmlogger_daily(1),  systemd(1),  PMAPI(3),
302       pmDerivedRegister(3) and pcp.conf(5).
303
304
305
306Performance Co-Pilot                  PCP                          PMLOGCTL(1)
Impressum