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 class] [-i ident] [-p policy] command [host ...]
10

DESCRIPTION

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

COMMANDS

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

CLASS POLICY FILE

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

OPTIONS

283       The available command line options are:
284
285       -a, --all
286            Apply action to all matching instances.  By default only  one  in‐
287            stance definition is expected and acted upon.
288
289       -c class, --class=class
290            Set  the  name of the class for which pmlogger(1) instances belong
291            to as class.
292
293       -f, --force
294            Force action if possible.
295
296       -i ident, --ident=ident
297            Override instance identifier with ident.  This option applies only
298            for the commands create and cond-create.
299
300       -N, --showme
301            Runs  pmlogctl  in a ``show me'' or ``dry run'' mode where the in‐
302            tent of the command is shown, but no changes are made.
303
304       -p policy, --policy=policy
305            Use   policy   as   the   class   policy   file.    Defaults    to
306            $PCP_SYSCONF_DIR/pmlogger/class.d/<class>.
307
308       -V, --verbose
309            Enable verbose mode.  Using this option twice increases verbosity.
310
311       -?, --help
312            Display usage message and exit.
313

PCP ENVIRONMENT

315       Environment variables with the prefix PCP_ are used to parameterize the
316       file and directory names used by PCP.  On each installation,  the  file
317       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
318       $PCP_CONF variable may be used to specify an alternative  configuration
319       file, as described in pcp.conf(5).
320

SEE ALSO

322       egrep(1),  init(1), PCPIntro(1), pmcd(1), pmlc(1), pmlogconf(1), pmlog‐
323       ger(1),  pmlogger_check(1),  pmlogger_daily(1),  systemd(1),  PMAPI(3),
324       pmDerivedRegister(3) and pcp.conf(5).
325
326
327
328Performance Co-Pilot                  PCP                          PMLOGCTL(1)
Impressum