1PMLC(1) General Commands Manual PMLC(1)
2
6 pmlc - configure active Performance Co-Pilot pmlogger(s) interactively
7
9 pmlc [-eiPz?] [-h host] [-n pmnsfile] [-p port] [-Z timezone] [pid]
10
12 pmlc may be used to change those metrics and instances which a pmlog‐
13 ger(1) writes to a Performance Co-Pilot archive (see PCPIntro(1)), the
14 frequency with which the metrics are collected and whether the logging
15 is mandatory, advisory, on or off. It also reports the current logging
16 status of metrics and instances. pmlc may be used to control pmlogger
17 instances on remote hosts as well as those on the local host.
18 Normally pmlc operates on the distributed Performance Metrics Name
20 Space (PMNS), however if the -n option is specified an alternative lo‐
21 cal PMNS is loaded from the file pmnsfile.
22 If the -P option is specified, pmlc will attempt to start with a con‐
24 nection to the primary pmlogger on the local host. If the -p option is
25 specified, then pmlc will attempt to start with a connection to the pm‐
26 logger on this TCP/IP port. Alternatively, if pid is specified, a con‐
27 nection to the pmlogger instance with that process id will be attempted
28 on startup. The -h option may only be used if -P, -p port or a pid is
29 also specified. In that case pmlc will initially connect to the speci‐
30 fied (remote) pmlogger instance on host rather than the local host. If
31 the connection to the specified pmlogger instance cannot be estab‐
32 lished, pmlc will start with no connection. These options typically
33 allow the same file of pmlc commands to be directed to multiple pmlog‐
34 ger instances by varying the command line arguments. Note that -P, -p
35 port, pid and -h are used only when making an initial connection to a
36 pmlogger instance. They are not used as defaults if subsequent connec‐
37 tions are made interactively (see the connect command below).
38 By default, pmlc reports the time of day according to the local time‐
40 zone on the system where pmlc is run. The -Z option changes the time‐
41 zone to timezone in the format of the environment variable TZ as de‐
42 scribed in environ(7). The -z option changes the timezone to the time‐
43 zone of the pmlogger instance from which information is being obtained.
44 Only one of -z or -Z may be specified.
45 If standard input is from a tty, pmlc is interactive, with prompts.
47 The -i flag may be used to force interactive behavior, and is typically
48 used in conjunction with -e to echo all command input on standard out‐
49 put.
50
52 The following commands may be used:
53 show [ loggers ] [ @host ]
55 Displays the process identities of all pmlogger instances running
56 on the local host (or host, if specified). The primary pmlogger
57 pid is parenthesized because it can be referred to as "primary" as
58 well as by its pid.
59 connect pid [ @host ]
61 connect primary [ @host ]
62 Connects pmlc to the specified pmlogger process. Any existing con‐
63 nection to a pmlogger instance is closed first. Each pmlogger in‐
64 stance will accept at most one connection at a time, so if the con‐
65 nection is successfully established, your pmlc will be the only one
66 controlling the pmlogger instance it is connected to.
67 new volume
69 This command works only while a connection to a pmlogger instance
70 is established. It tells the pmlogger to close the current volume
71 of the log and open a new volume. Closed volumes may be archived,
72 e.g. as part of a regular log management procedure to control the
73 size of the physical log files.
74 status
76 This command works only while a connection to a pmlogger instance
77 is established. It prints information about the state of the pm‐
78 logger instance and its associated log.
79 timezone local | logger | "timezone"
81 This command sets the time zone used when times are printed. local
82 means use the time zone of the machine that pmlc is running on.
83 logger means use the time zone of the machine where the pmlogger
84 instance is running. Alternatively an explicit timezone enclosed
85 in quotes may be supplied (refer to TZ in environ(7) for details).
86 The default time zone is local unless one of the -z or -Z options
87 has been supplied on the command line.
88 flush
90 This command works only while a connection to a pmlogger instance
91 is established, and requests the pmlogger instance to flush to disk
92 all buffers associated with the current archive. For old-timers,
93 sync is a synonym for flush. In current versions of pmlogger(1)
94 all writes are unbuffered and aligned with the logical records in
95 the external files, so this command achieves nothing, but is re‐
96 tained for backwards compatibility.
97 disconnect
99 Disconnect pmlc from the current pmlogger instance, if any.
100 sleep delay
102 Pause pmlc for delay milliseconds. This may be helpful in scripted
103 uses of pmlc to allow the current pmlogger instance to make
104 progress on recent requests before interrogating the status.
105 help
107 Displays a summary of the available commands.
108 h and ? are synonyms for help.
109 quit
111 Exits from pmlc.
112 The remaining commands query and change the logging state of metrics
114 and instances. They will work only if pmlc has a connection to a pm‐
115 logger instance. Metrics may be specified as fully qualified names
116 (e.g. hinv.ncpu) or subtrees of the PMNS (e.g. hinv) which are expanded
117 to include all metrics in the subtree (e.g. hinv.ncpu, hinv.cpuclock,
118 etc.). Lists of metrics may be specified by enclosing them in braces
119 with spaces or a comma between metrics (e.g. {hinv.ncpu hinv.ndisk}).
120 Subtrees of metrics may be included in such lists.
121 Each individual metric specification may be further qualified with a
123 space or comma separated list of instances in square brackets (e.g.
124 kernel.all.load["1 minute", "5 minute"]). External instance names or
125 numeric internal instance identifiers or both may be used in the same
126 list (e.g. sample.colour.[red,1,"blue"]). If an instance qualification
127 is applied to a subtree of the PMNS all of the metrics in the subtree
128 must have the same instance domain. Instance qualifications may not be
129 applied to entire lists of metrics but may appear inside such lists.
130 If no instances are specified for a metric, all instances are used.
132 All instances means all instances available at the time the pmlogger
133 instance in question fetches the metrics for logging. If an instance
134 domain changes over time this is not always the same as the set of in‐
135 stances displayed by pmlc, which can only display the currently avail‐
136 able instances. To prevent unintentional errors, only the instances
137 that are currently available to pmlc may appear in instance specifica‐
138 tions.
139 query metriclist
141 The current logging state of each metric (and instances, where ap‐
142 plicable) in metriclist is displayed. This includes the logging
143 state (e.g. on, maybe, off) and the logging interval for each met‐
144 ric (and instance) requested. The following abbreviations pertain‐
145 ing to metrics (and instances) may appear in the output: adv, advi‐
146 sory; mand, mandatory; nl, not in the log; na, in the log but not
147 currently available from its Performance Metrics Domain Agent
148 (PMDA). Where appropriate, an instance name will appear last on a
149 line preceded by its numeric internal instance identifier.
150 [ log ] mandatory on interval metriclist
152 This form of the log command turns on logging for the metrics (and
153 any instances) in metriclist. interval specifies how often the
154 specified metrics/instances should be logged. once indicates that
155 the metrics/instances should appear at most once in the log. More
156 often one would use the optional keyword every followed by a posi‐
157 tive number and one of millisecond (or msec), second (or sec),
158 minute (or min), hour or their plurals.
159 Note that the keyword default which may be used for the default in‐
160 terval in a pmlogger(1) configuration file cannot be used in pmlc.
161 Internal limitations require the interval to be less than (approxi‐
162 mately) 74 hours. An interval value of zero is a synonym for once.
163 [ log ] mandatory off metriclist
165 This tells the pmlogger instance not to log any of the metrics/in‐
166 stances in metriclist.
167 [ log ] mandatory maybe metriclist
169 This tells the pmlogger instance to honor any subsequent advisory
170 logging requests for the metrics/instances in metriclist. If the
171 current logging state of the metrics/instances is mandatory (either
172 on or off) the new state will be set to maybe (effectively advisory
173 off). If the current state of the metrics/instances is already ad‐
174 visory (either on or off) the state(s) for the metrics/instances
175 will remain as they are.
176 [ log ] advisory on interval metriclist
178 [ log ] advisory off metriclist
179 Advisory logging is only applicable if the last logging state spec‐
180 ified for a metric/instance was "mandatory maybe" (which permits
181 subsequent advisory logging control) or if the logging state is al‐
182 ready advisory. These two statements turn advisory logging on or
183 off (respectively) for the specified metrics/instances.
184 The interpretation for interval is as above for the mandatory case.
185 There is no continuation character required for commands that span
187 lines.
188 The word at may be used interchangeably with @.
190 A request to log all instances of a metric will supersede any prior re‐
192 quest to log either all or specific instances of a metric (if the re‐
193 quest specifies a permissible transition in the logging state). A re‐
194 quest to log specific instances of a metric when all instances of a
195 metric are already being logged is refused by pmlogger.
196
198 The available command line options are:
199 -e, --echo
201 Echo all command input on standard output.
202 -h host, --host=host
204 Connect pmlogger on host, rather than on the default localhost.
205 -i, --interactive
207 Force interactive behavior.
208 -n pmnsfile, --namespace=pmnsfile
210 Load an alternative Performance Metrics Name Space (PMNS(5)) from
211 the file pmnsfile.
212 -p port, --port=port
214 Connect to the primary pmlogger on TCP/IP port port.
215 -P, --primary
217 Connect to the primary pmlogger.
218 -z, --logzone
220 Use local time of the pmlogger as the reporting timezone.
221 -Z timezone, --timezone=timezone
223 Use timezone for the date and time. Timezone is in the format of
224 the environment variable TZ as described in environ(7).
225 -?, --help
227 Display usage message and exit.
228
230 pmlc may have restricted access to and control over pmlogger(1) pro‐
231 cesses.
232 If a pmlogger(1) is unable to export its control information to the lo‐
234 cal pmcd(1), then that pmlogger(1) cannot cannot be connected to nor
235 controlled by pmlc. In practice, this means the pmlogger(1) process
236 has to be owned by the user ``pcp'' and/or the group ``pcp''. If pm‐
237 logger(1) is running on the host ``foo'' then use ``pminfo -f -h foo
238 pmcd.pmlogger'' to verify that the pmlogger(1) of interest is known to
239 pmcd(1), alternatively pmlogger(1) instances that are not reported from
240 the pmlc show loggers @foo command are not known to pmcd(1) on the host
241 ``foo''.
242 If pmlogger(1) is launched with a configuration file that contains an
244 [access] section, then pmlc will be unable to connect to that pmlog‐
245 ger(1) unless the access controls allow some access from the host where
246 pmlc is being run. Minimally this requires the enquire access to be
247 permitted in the pmlogger(1) access control section.
248 If pmlc is able to connect to the pmlogger(1) of interest, then the
250 following table summarizes the permissions needed to perform different
251 pmlc commands:
252 ┌──────────────────┬───────────────────────────────────────┐
254 │ pmlc command │ Required pmlogger access │
255 ├──────────────────┼───────────────────────────────────────┤
256 │show loggers │ Any │
257 │connect │ Any of enquire, advisory or mandatory │
258 │status │ Any of enquire, advisory or mandatory │
259 │query ... │ Any of enquire, advisory or mandatory │
260 │disconnect │ Any │
261 │log advisory ... │ advisory │
262 │log mandatory ... │ mandatory │
263 │new volume │ mandatory │
264 └──────────────────┴───────────────────────────────────────┘
266 If all instances of a metric are being logged and a request is made to
267 log specific instances of the metric with the same state and frequency,
268 the request may appear to succeed, even though pmlogger has refused the
269 request. This is not normally a problem, as the required information
270 will still be placed into the log by pmlogger.
271 However in the case where the metric is to be logged once, the outcome
273 is not what might be expected. When pmlogger receives a request to log
274 a metric once, it places the current value(s) of the metric into the
275 log as soon as it can, regardless of whether the metric is already in
276 the log. This may be used to force values into the log. When a re‐
277 quest to log specific instances of a metric arrives and is refused be‐
278 cause all instances of the metric are already being logged, pmlogger
279 does not place values for the instances requested into the log. It re‐
280 turns the current logging state for each instance requested to pmlc.
281 The requested and returned states are identical, so pmlc doesn't raise
282 an error as it should.
283 To ensure that only certain instances of a metric are being logged, one
285 should always turn off logging for all instances of the metric prior to
286 turning on logging for the specific instances required.
287
289 Most error or warning messages are self-explanatory. A message of the
290 form
291 Warning: unable to change logging state for...
292 followed by a list of metrics (and possibly instances) indicates that
293 pmlogger refused the request for the metrics (and instances) that ap‐
294 pear. Any metrics (and instances) that were specified but do not ap‐
295 pear in the message have had their logging state updated successfully
296 (no news is good news). Usually this warning results from requesting
297 advisory logging when a mandatory control is already in place, or re‐
298 questing logging for specific instances when all instances are already
299 being logged.
300
302 If the PMLOGGER_REQUEST_TIMEOUT environment variable is not set or set
303 to 0 (zero), then pmlc will block until a connection is established
304 with pmlogger(1) on the requested port. If PMLOGGER_REQUEST_TIMEOUT is
305 set to a value greater than zero, then pmlc will fail with an error af‐
306 ter that many seconds if a connection isn't established. This may be
307 used by administrative scripts such as pmlogger_daily(1) to poll pmlog‐
308 ger when is starting up until it is ready and listening on it's control
309 port.
310
312 Environment variables with the prefix PCP_ are used to parameterize the
313 file and directory names used by PCP. On each installation, the file
314 /etc/pcp.conf contains the local values for these variables. The
315 $PCP_CONF variable may be used to specify an alternative configuration
316 file, as described in pcp.conf(5).
317
319 PCPIntro(1), pmcd(1), pmdumplog(1), pmlogger(1), pcp.conf(5),
320 pcp.env(5), PMNS(5) and environ(7).
321Performance Co-Pilot PCP PMLC(1)