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  [-afmNV?]   [-C check_args] [-c class] [-i ident] [-p policy]
10       command [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 pm‐
25       logger(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  as‐
44          sociated  $class=...   assignment.  For reporting purposes (refer to
45          the summary command below), the primary pmlogger(1) instance is  au‐
46          tomatically assigned to the special primary class.
47
48       Each  pmlogctl execution manages one or more instances updating the as‐
49       sociated control files and then running pmlogger_check(1) to effect the
50       desired change.
51
52       The  host arguments are usually valid host names.  For all commands ex‐
53       cept 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 class from the optional -c option (or default) and
61       the host arguments to each command identifies a target of set instances
62       to which the command operation should be applied.
63
64       The  -i  option  may be used with the create or cond-create commands to
65       override the instance identity that is specified in the  ident  section
66       of  the  class  policy  file (see the CLASS POLICY FILE section below).
67       Since the identifier must  be  unique  across  all  instances  and  all
68       classes,  it only makes sense to use this option when there is a single
69       host argument.
70
71       Given the tasks that pmlogctl is undertaking it usually must be run  as
72       ``root'', the exceptions being the status command or when the -N option
73       is specified.
74

COMMANDS

76       command is one of the following:
77
78       check
79           Check the status of all currently configured pmlogger instances and
80           restart  any  that  have  failed.   If the -m flag is given on sys‐
81           temd(1) platforms, also migrate matching (and new) processes to the
82           pmlogger_farm service.
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. $PCP_SYSCONF_DIR/pm‐
94           logger/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 ``de‐
107           fault'' class for the cond-create command when all else fails).
108
109           If more than one class evaluates to true then  a  composite  pmlog‐
110           ger(1)  configuration  file is created and the instance is also as‐
111           signed 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  pm‐
163           logger(1) processes and removing their pmlogger_check(1) configura‐
164           tions).
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 de‐
168           stroy operation should be performed.  This may require a -p  option
169           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_SYSCONF_DIR/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  in‐
192           stance  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 de‐
215               scribes 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 in‐
226           sert 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  in‐
234           tent  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 in‐
262           stance 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

OPTIONS

290       The available command line options are:
291
292       -a, --all
293            Apply action to all matching instances.  By default only  one  in‐
294            stance definition is expected and acted upon.
295
296       -c class, --class=class
297            Set  the  name of the class for which pmlogger(1) instances belong
298            to as class.
299
300       -C check_args, --checkargs=check_args
301            check_args  are  additional  command  line  arguments  for  pmlog‐
302            ger_check(1)  when  it is called.  This is most useful for options
303            like -V.   Multiple  -C  options  may  be  used  and  the  various
304            check_args  options  will  be accumulated and all passed to pmlog‐
305            ger_check(1).
306
307       -f, --force
308            Force action if possible.
309
310       -i ident, --ident=ident
311            Override instance identifier with ident.  This option applies only
312            for the commands create and cond-create.
313
314       -N, --showme
315            Runs  pmlogctl  in a ``show me'' or ``dry run'' mode where the in‐
316            tent of the command is shown, but no changes are made.
317
318       -m, --migrate
319            When used with the create or check commands  on  systemd(1)  plat‐
320            forms, also migrate new or existing non-primary pmlogger processes
321            to the pmlogger_farm service.  This is normally done automatically
322            by  the  pmlogger_farm_check  service,  which  is timer driven (so
323            there may be a few minutes delay  before  automatic  migration  is
324            initiated).
325
326       -p policy, --policy=policy
327            Use    policy   as   the   class   policy   file.    Defaults   to
328            $PCP_SYSCONF_DIR/pmlogger/class.d/<class>.
329
330       -V, --verbose
331            Enable verbose mode.  Using this option twice increases verbosity.
332
333       -?, --help
334            Display usage message and exit.
335

PCP ENVIRONMENT

337       Environment variables with the prefix PCP_ are used to parameterize the
338       file  and  directory names used by PCP.  On each installation, the file
339       /etc/pcp.conf contains the  local  values  for  these  variables.   The
340       $PCP_CONF  variable may be used to specify an alternative configuration
341       file, as described in pcp.conf(5).
342

SEE ALSO

344       egrep(1), init(1), PCPIntro(1), pmcd(1), pmlc(1), pmlogconf(1),  pmlog‐
345       ger(1),  pmlogger_check(1),  pmlogger_daily(1),  systemd(1),  PMAPI(3),
346       pmDerivedRegister(3) and pcp.conf(5).
347
348
349
350Performance Co-Pilot                  PCP                          PMLOGCTL(1)
Impressum