1PMLC(1) General Commands Manual PMLC(1)
2
6 pmlc - configure active Performance Co-Pilot pmlogger(s) interactively
7
9 pmlc [-e] [-h host] [-i] [-n pmnsfile] [-P] [-p port] [-Z timezone]
10 [-z] [pid]
11
13 pmlc may be used to change those metrics and instances which a pmlog‐
14 ger(1) writes to a Performance Co-Pilot archive (see PCPIntro(1)), the
15 frequency with which the metrics are collected and whether the logging
16 is mandatory, advisory, on or off. It also reports the current logging
17 status of metrics and instances. pmlc may be used to control pmlogger
18 instances on remote hosts as well as those on the local host.
19 Normally pmlc operates on the distributed Performance Metrics Name
21 Space (PMNS), however if the -n option is specified an alternative
22 local PMNS is loaded from the file pmnsfile.
23 If the -P option is specified, pmlc will attempt to start with a con‐
25 nection to the primary pmlogger on the local host. If the -p option is
26 specified, then pmlc will attempt to start with a connection to the
27 pmlogger on this TCP/IP port. Alternatively, if pid is specified, a
28 connection to the pmlogger instance with that process id will be
29 attempted on startup. The -h option may only be used if -P, -p port or
30 a pid is also specified. In that case pmlc will initially connect to
31 the specified (remote) pmlogger instance on host rather than the local
32 host. If the connection to the specified pmlogger instance cannot be
33 established, pmlc will start with no connection. These options typi‐
34 cally allow the same file of pmlc commands to be directed to multiple
35 pmlogger instances by varying the command line arguments. Note that
36 -P, -p port, pid and -h are used only when making an initial connection
37 to a pmlogger instance. They are not used as defaults if subsequent
38 connections are made interactively (see the connect command below).
39 By default, pmlc reports the time of day according to the local time‐
41 zone on the system where pmlc is run. The -Z option changes the time‐
42 zone to timezone in the format of the environment variable TZ as
43 described in environ(5). The -z option changes the timezone to the
44 timezone of the pmlogger instance from which information is being
45 obtained. Only one of -z or -Z may be specified.
46 If standard input is from a tty, pmlc is interactive, with prompts.
48 The -i flag may be used to force interactive behavior, and is typically
49 used in conjunction with -e to echo all command input on standard out‐
50 put.
51 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
64 instance will accept at most one connection at a time, so if the
65 connection is successfully established, your pmlc will be the only
66 one 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
78 pmlogger 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(5) 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.
94 help
96 Displays a summary of the available commands.
97 h and ? are synonyms for help.
98 quit
100 Exits from pmlc.
101 The remaining commands query and change the logging state of metrics
103 and instances. They will work only if pmlc has a connection to a
104 pmlogger instance. Metrics may be specified as fully qualified names
105 (e.g. hinv.ncpu) or subtrees of the PMNS (e.g. hinv) which are expanded
106 to include all metrics in the subtree (e.g. hinv.ncpu, hinv.cpuclock,
107 etc.). Lists of metrics may be specified by enclosing them in braces
108 with spaces or a comma between metrics (e.g. {hinv.ncpu hinv.ndisk}).
109 Subtrees of metrics may be included in such lists.
110 Each individual metric specification may be further qualified with a
112 space or comma separated list of instances in square brackets (e.g.
113 kernel.all.load["1 minute", "5 minute"]). External instance names or
114 numeric internal instance identifiers or both may be used in the same
115 list (e.g. sample.colour.[red,1,"blue"]). If an instance qualification
116 is applied to a subtree of the PMNS all of the metrics in the subtree
117 must have the same instance domain. Instance qualifications may not be
118 applied to entire lists of metrics but may appear inside such lists.
119 If no instances are specified for a metric, all instances are used.
121 All instances means all instances available at the time the pmlogger
122 instance in question fetches the metrics for logging. If an instance
123 domain changes over time this is not always the same as the set of
124 instances displayed by pmlc, which can only display the currently
125 available instances. To prevent unintentional errors, only the
126 instances that are currently available to pmlc may appear in instance
127 specifications.
128 query metriclist
130 The current logging state of each metric (and instances, where
131 applicable) in metriclist is displayed. This includes the logging
132 state (e.g. on, maybe, off) and the logging interval for each met‐
133 ric (and instance) requested. The following abbreviations pertain‐
134 ing to metrics (and instances) may appear in the output: adv, advi‐
135 sory; mand, mandatory; nl, not in the log; na, in the log but not
136 currently available from its Performance Metrics Domain Agent
137 (PMDA). Where appropriate, an instance name will appear last on a
138 line preceded by its numeric internal instance identifier.
139 [ log ] mandatory on interval metriclist
141 This form of the log command turns on logging for the metrics (and
142 any instances) in metriclist. interval specifies how often the
143 specified metrics/instances should be logged. once indicates that
144 the metrics/instances should appear at most once in the log. More
145 often one would use the optional keyword every followed by a posi‐
146 tive number and one of millisecond (or msec), second (or sec),
147 minute (or min), hour or their plurals.
148 Note that the keyword default which may be used for the default
149 interval in a pmlogger(1) configuration file cannot be used in
150 pmlc.
151 Internal limitations require the interval to be less than (approxi‐
152 mately) 74 hours. An interval value of zero is a synonym for once.
153 [ log ] mandatory off metriclist
155 This tells the pmlogger instance not to log any of the met‐
156 rics/instances in metriclist.
157 [ log ] mandatory maybe metriclist
159 This tells the pmlogger instance to honor any subsequent advisory
160 logging requests for the metrics/instances in metriclist. If the
161 current logging state of the metrics/instances is mandatory (either
162 on or off) the new state will be set to maybe (effectively advisory
163 off). If the current state of the metrics/instances is already
164 advisory (either on or off) the state(s) for the metrics/instances
165 will remain as they are.
166 [ log ] advisory on interval metriclist
168 [ log ] advisory off metriclist
169 Advisory logging is only applicable if the last logging state spec‐
170 ified for a metric/instance was "mandatory maybe" (which permits
171 subsequent advisory logging control) or if the logging state is
172 already advisory. These two statements turn advisory logging on or
173 off (respectively) for the specified metrics/instances.
174 The interpretation for interval is as above for the mandatory case.
175 There is no continuation character required for commands that span
177 lines.
178 The word at may be used interchangeably with @.
180 A request to log all instances of a metric will supersede any prior
182 request to log either all or specific instances of a metric (if the
183 request specifies a permissible transition in the logging state). A
184 request to log specific instances of a metric when all instances of a
185 metric are already being logged is refused by pmlogger.
186
188 Environment variables with the prefix PCP_ are used to parameterize the
189 file and directory names used by PCP. On each installation, the file
190 /etc/pcp.conf contains the local values for these variables. The
191 $PCP_CONF variable may be used to specify an alternative configuration
192 file, as described in pcp.conf(4).
193
195 PCPIntro(1), pmcd(1), pmdumplog(1), pmlogger(1), pcp.conf(4),
196 pcp.env(4) and environ(5).
197
199 Most error or warning messages are self-explanatory. A message of the
200 form
201 Warning: unable to change logging state for...
202 followed by a list of metrics (and possibly instances) indicates that
203 pmlogger refused the request for the metrics (and instances) that
204 appear. Any metrics (and instances) that were specified but do not
205 appear in the message have had their logging state updated successfully
206 (no news is good news). Usually this warning results from requesting
207 advisory logging when a mandatory control is already in place, or
208 requesting logging for specific instances when all instances are
209 already being logged.
210
212 If all instances of a metric are being logged and a request is made to
213 log specific instances of the metric with the same state and frequency,
214 the request may appear to succeed, even though pmlogger has refused the
215 request. This is not normally a problem, as the required information
216 will still be placed into the log by pmlogger.
217 However in the case where the metric is to be logged once, the outcome
219 is not what might be expected. When pmlogger receives a request to log
220 a metric once, it places the current value(s) of the metric into the
221 log as soon as it can, regardless of whether the metric is already in
222 the log. This may be used to force values into the log. When a
223 request to log specific instances of a metric arrives and is refused
224 because all instances of the metric are already being logged, pmlogger
225 does not place values for the instances requested into the log. It
226 returns the current logging state for each instance requested to pmlc.
227 The requested and returned states are identical, so pmlc doesn't raise
228 an error as it should.
229 To ensure that only certain instances of a metric are being logged, one
231 should always turn off logging for all instances of the metric prior to
232 turning on logging for the specific instances required.
233Performance Co-Pilot SGI PMLC(1)