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 archive and open a new volume. Closed volumes may be com‐
72 pressed and/or moved to a remote system, remote storage or off-line
73 storage, e.g. as part of a regular archive management procedure to
74 control the size of the physical archive files on the system where
75 pmlogger is running.
76 status
78 This command works only while a connection to a pmlogger instance
79 is established. It prints information about the state of the pm‐
80 logger instance and its associated archive.
81 timezone local | logger | "timezone"
83 This command sets the time zone used when times are printed. local
84 means use the time zone of the machine that pmlc is running on.
85 logger means use the time zone of the machine where the pmlogger
86 instance is running. Alternatively an explicit timezone enclosed
87 in quotes may be supplied (refer to TZ in environ(7) for details).
88 The default time zone is local unless one of the -z or -Z options
89 has been supplied on the command line.
90 flush
92 This command works only while a connection to a pmlogger instance
93 is established, and requests the pmlogger instance to flush to disk
94 all buffers associated with the current archive. For old-timers,
95 sync is a synonym for flush. In current versions of pmlogger(1)
96 all writes are unbuffered and aligned with the logical records in
97 the external files, so this command achieves nothing, but is re‐
98 tained for backwards compatibility.
99 disconnect
101 Disconnect pmlc from the current pmlogger instance, if any.
102 sleep delay
104 Pause pmlc for delay milliseconds. This may be helpful in scripted
105 uses of pmlc to allow the current pmlogger instance to make
106 progress on recent requests before interrogating the status.
107 help
109 Displays a summary of the available commands.
110 h and ? are synonyms for help.
111 quit
113 Exits from pmlc.
114 The remaining commands query and change the logging state of metrics
116 and instances. They will work only if pmlc has a connection to a pm‐
117 logger instance. Metrics may be specified as fully qualified names
118 (e.g. hinv.ncpu) or subtrees of the PMNS (e.g. hinv) which are expanded
119 to include all metrics in the subtree (e.g. hinv.ncpu, hinv.cpuclock,
120 etc.). Lists of metrics may be specified by enclosing them in braces
121 with spaces or a comma between metrics (e.g. {hinv.ncpu hinv.ndisk}).
122 Subtrees of metrics may be included in such lists.
123 Each individual metric specification may be further qualified with a
125 space or comma separated list of instances in square brackets (e.g.
126 kernel.all.load["1 minute", "5 minute"]). External instance names or
127 numeric internal instance identifiers or both may be used in the same
128 list (e.g. sample.colour.[red,1,"blue"]). If an instance qualification
129 is applied to a subtree of the PMNS all of the metrics in the subtree
130 must have the same instance domain. Instance qualifications may not be
131 applied to entire lists of metrics but may appear inside such lists.
132 If no instances are specified for a metric, all instances are used.
134 All instances means all instances available at the time the pmlogger
135 instance in question fetches the metrics for logging. If an instance
136 domain changes over time this is not always the same as the set of in‐
137 stances displayed by pmlc, which can only display the currently avail‐
138 able instances. To prevent unintentional errors, only the instances
139 that are currently available to pmlc may appear in instance specifica‐
140 tions.
141 query metriclist
143 The current logging state of each metric (and instances, where ap‐
144 plicable) in metriclist is displayed. This includes the logging
145 state (e.g. on, maybe, off) and the logging interval for each met‐
146 ric (and instance) requested. The following abbreviations pertain‐
147 ing to metrics (and instances) may appear in the output: adv, advi‐
148 sory; mand, mandatory; nl, not logged (not in the archive); na, in
149 the archive but not currently available from its Performance Met‐
150 rics Domain Agent (PMDA). Where appropriate, an instance name will
151 appear last on a line preceded by its numeric internal instance
152 identifier.
153 [ log ] mandatory on interval metriclist
155 This form of the log command turns on logging for the metrics (and
156 any instances) in metriclist. interval specifies how often the
157 specified metrics/instances should be logged. once indicates that
158 the metrics/instances should appear at most once in the archive.
159 More often one would use the optional keyword every followed by a
160 positive number and one of millisecond (or msec), second (or sec),
161 minute (or min), hour or their plurals.
162 Note that the keyword default which may be used for the default in‐
163 terval in a pmlogger(1) configuration file cannot be used in pmlc.
164 Internal limitations require the interval to be less than (approxi‐
165 mately) 74 hours. An interval value of zero is a synonym for once.
166 [ log ] mandatory off metriclist
168 This tells the pmlogger instance not to archive any of the met‐
169 rics/instances in metriclist.
170 [ log ] mandatory maybe metriclist
172 This tells the pmlogger instance to honor any subsequent advisory
173 logging requests for the metrics/instances in metriclist. If the
174 current logging state of the metrics/instances is mandatory (either
175 on or off) the new state will be set to maybe (effectively advisory
176 off). If the current state of the metrics/instances is already ad‐
177 visory (either on or off) the state(s) for the metrics/instances
178 will remain as they are.
179 [ log ] advisory on interval metriclist
181 [ log ] advisory off metriclist
182 Advisory logging is only applicable if the last logging state spec‐
183 ified for a metric/instance was "mandatory maybe" (which permits
184 subsequent advisory logging control) or if the logging state is al‐
185 ready advisory. These two statements turn advisory logging on or
186 off (respectively) for the specified metrics/instances.
187 The interpretation for interval is as above for the mandatory case.
188 There is no continuation character required for commands that span
190 lines.
191 The word at may be used interchangeably with @.
193 A request to archive all instances of a metric will supersede any prior
195 request to log either all or specific instances of a metric (if the re‐
196 quest specifies a permissible transition in the logging state). A re‐
197 quest to archive specific instances of a metric when all instances of a
198 metric are already being logged is refused by pmlogger.
199
201 The available command line options are:
202 -e, --echo
204 Echo all command input on standard output.
205 -h host, --host=host
207 Connect pmlogger on host, rather than on the default localhost.
208 -i, --interactive
210 Force interactive behavior.
211 -n pmnsfile, --namespace=pmnsfile
213 Load an alternative Performance Metrics Name Space (PMNS(5)) from
214 the file pmnsfile.
215 -p port, --port=port
217 Connect to the primary pmlogger on TCP/IP port port.
218 -P, --primary
220 Connect to the primary pmlogger.
221 -z, --logzone
223 Use local time of the pmlogger as the reporting timezone.
224 -Z timezone, --timezone=timezone
226 Use timezone for the date and time. Timezone is in the format of
227 the environment variable TZ as described in environ(7).
228 -?, --help
230 Display usage message and exit.
231
233 pmlc may have restricted access to and control over pmlogger(1) pro‐
234 cesses.
235 If a pmlogger(1) is unable to export its control information to the lo‐
237 cal pmcd(1), then that pmlogger(1) cannot cannot be connected to nor
238 controlled by pmlc. In practice, this means the pmlogger(1) process
239 has to be owned by the user ``pcp'' and/or the group ``pcp''. If pm‐
240 logger(1) is running on the host ``foo'' then use ``pminfo -f -h foo
241 pmcd.pmlogger'' to verify that the pmlogger(1) of interest is known to
242 pmcd(1), alternatively pmlogger(1) instances that are not reported from
243 the pmlc show loggers @foo command are not known to pmcd(1) on the host
244 ``foo''.
245 If pmlogger(1) is launched with a configuration file that contains an
247 [access] section, then pmlc will be unable to connect to that pmlog‐
248 ger(1) unless the access controls allow some access from the host where
249 pmlc is being run. Minimally this requires the enquire access to be
250 permitted in the pmlogger(1) access control section.
251 If pmlc is able to connect to the pmlogger(1) of interest, then the
253 following table summarizes the permissions needed to perform different
254 pmlc commands:
255 ┌──────────────────┬───────────────────────────────────────┐
257 │ pmlc command │ Required pmlogger access │
258 ├──────────────────┼───────────────────────────────────────┤
259 │show loggers │ Any │
260 │connect │ Any of enquire, advisory or mandatory │
261 │status │ Any of enquire, advisory or mandatory │
262 │query ... │ Any of enquire, advisory or mandatory │
263 │disconnect │ Any │
264 │log advisory ... │ advisory │
265 │log mandatory ... │ mandatory │
266 │new volume │ mandatory │
267 └──────────────────┴───────────────────────────────────────┘
269 If all instances of a metric are being logged and a request is made to
270 log specific instances of the metric with the same state and frequency,
271 the request may appear to succeed, even though pmlogger has refused the
272 request. This is not normally a problem, as the required information
273 will still be placed into the archive by pmlogger.
274 However in the case where the metric is to be logged once, the outcome
276 is not what might be expected. When pmlogger receives a request to ar‐
277 chive a metric once, it places the current value(s) of the metric into
278 the archive as soon as it can, regardless of whether the metric is al‐
279 ready in the archive. This may be used to force values into the ar‐
280 chive. When a request to archive specific instances of a metric ar‐
281 rives and is refused because all instances of the metric are already
282 being logged, pmlogger does not place values for the instances re‐
283 quested into the archive. It returns the current logging state for
284 each instance requested to pmlc. The requested and returned states are
285 identical, so pmlc doesn't raise an error as it should.
286 To ensure that only certain instances of a metric are being logged, one
288 should always turn off logging for all instances of the metric prior to
289 turning on logging for the specific instances required.
290
292 Most error or warning messages are self-explanatory. A message of the
293 form
294 Warning: unable to change logging state for...
295 followed by a list of metrics (and possibly instances) indicates that
296 pmlogger refused the request for the metrics (and instances) that ap‐
297 pear. Any metrics (and instances) that were specified but do not ap‐
298 pear in the message have had their logging state updated successfully
299 (no news is good news). Usually this warning results from requesting
300 advisory logging when a mandatory control is already in place, or re‐
301 questing logging for specific instances when all instances are already
302 being logged.
303
305 If the PMLOGGER_REQUEST_TIMEOUT environment variable is not set or set
306 to 0 (zero), then pmlc will block until a connection is established
307 with pmlogger(1) on the requested port. If PMLOGGER_REQUEST_TIMEOUT is
308 set to a value greater than zero, then pmlc will fail with an error af‐
309 ter that many seconds if a connection isn't established. This may be
310 used by administrative scripts such as pmlogger_daily(1) to poll pmlog‐
311 ger when is starting up until it is ready and listening on it's control
312 port.
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 PCPIntro(1), pmcd(1), pmdumplog(1), pmlogger(1), pcp.conf(5),
323 pcp.env(5), PMNS(5) and environ(7).
324Performance Co-Pilot PCP PMLC(1)