1PMLOGCTL(1) General Commands Manual PMLOGCTL(1)
2
6 pmlogctl - manage and control Performance Co-Pilot archive loggers
7
9 pmlogctl [-afNV?] [-c class] [-i ident] [-p policy] command [host ...]
10
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 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 For brevity in the description below, the term ``instance'' means a pm‐
24 logger(1) instance.
25 All instances managed by pmlogctl, pmlogger_check(1) and pmlog‐
27 ger_daily(1) abide by the following rules:
28 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 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 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 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 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 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 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 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
75 command is one of the following:
76 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 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 At least one host must be specified for the create command.
90 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 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 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 start
110 Start the target set of instances.
111 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 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 stop
122 Stop the target set of instances.
123 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 If an instance in the target set is already stopped, no change is
130 made but a warning is issued.
131 restart
133 Stop and then start the target set of instances.
134 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 If an instance in the target set is already stopped, a warning is
141 issued before the instance is started.
142 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 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 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 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 The class policy checking can be by-passed using the -f (force)
165 command line option.
166
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 Lines beginning with a hash (#) are treated as comments and ignored.
173 Blank or empty lines are also ignored.
174 The typical location of the policy file for the class foo is
176 $PCP_SYSCONF_DIR/pmlogger/class.d/foo.
177 [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 [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 [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 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 pmlogctl will also add the class name during creation. e.g.
222 $class=foo
223 [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 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 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 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 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 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 [destroy]
254 The destroy section defines the policy to be applied when an in‐
255 stance is destroyed.
256 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 A sample class policy file is as follows:
264 # policy file for the foo class
266 [class]
267 foo
268 [ident]
269 foo-%h
270 [control]
272 $version=1.1
273 %h n n PCP_ARCHIVE_DIR/%i -c foo-metrics.config
274 [create]
276 # matches all hosts
277 hostname(.*)
278 [destroy]
280 # still to be defined
281
283 The available command line options are:
284 -a, --all
286 Apply action to all matching instances. By default only one in‐
287 stance definition is expected and acted upon.
288 -c class, --class=class
290 Set the name of the class for which pmlogger(1) instances belong
291 to as class.
292 -f, --force
294 Force action if possible.
295 -i ident, --ident=ident
297 Override instance identifier with ident. This option applies only
298 for the commands create and cond-create.
299 -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 -p policy, --policy=policy
305 Use policy as the class policy file. Defaults to
306 $PCP_SYSCONF_DIR/pmlogger/class.d/<class>.
307 -V, --verbose
309 Enable verbose mode. Using this option twice increases verbosity.
310 -?, --help
312 Display usage message and exit.
313
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
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).
325Performance Co-Pilot PCP PMLOGCTL(1)