NAME
pmlc - configure active Performance Co-Pilot pmlogger(s)
interactively
SYNOPSIS
pmlc [-e] [-h host] [-i] [-n pmnsfile] [-P] [-p port] [-Z
timezone] [-z] [pid]
DESCRIPTION
pmlc may be used to change those metrics and instances
which a pmlogger(1) writes to a Performance Co-Pilot
archive (see PCPIntro(1)), the frequency with which the
metrics are collected and whether the logging is manda
tory, advisory, on or off. It also reports the current
logging status of metrics and instances. pmlc may be used
to control pmlogger instances on remote hosts as well as
those on the local host.
Normally pmlc operates on the distributed Performance Met
rics Name Space (PMNS), however if the -n option is speci
fied an alternative local PMNS is loaded from the file
pmnsfile.
If the -P option is specified, pmlc will attempt to start
with a connection to the primary pmlogger on the local
host. If the -p option is specified, then pmlc will
attempt to start with a connection to the pmlogger on this
TCP/IP port. Alternatively, if pid is specified, a con
nection to the pmlogger instance with that process id will
be attempted on startup. The -h option may only be used
if -P, -p port or a pid is also specified. In that case
pmlc will initially connect to the specified (remote)
pmlogger instance on host rather than the local host. If
the connection to the specified pmlogger instance cannot
be established, pmlc will start with no connection. These
options typically allow the same file of pmlc commands to
be directed to multiple pmlogger instances by varying the
command line arguments. Note that -P, -p port, pid and -h
are used only when making an initial connection to a
pmlogger instance. They are not used as defaults if sub
sequent connections are made interactively (see the con
nect command below).
By default, pmlc reports the time of day according to the
local timezone on the system where pmlc is run. The -Z
option changes the timezone to timezone in the format of
the environment variable TZ as described in environ(5).
The -z option changes the timezone to the timezone of the
pmlogger instance from which information is being
obtained. Only one of -z or -Z may be specified.
If standard input is from a tty, pmlc is interactive, with
behavior, and is typically used in conjunction with -e to
echo all command input on standard output.
The following commands may be used:
show [ loggers ] [ @host ]
Displays the process identities of all pmlogger
instances running on the local host (or host, if spec
ified). The primary pmlogger pid is parenthesized
because it can be referred to as "primary" as well as
by its pid.
connect pid [ @host ]
connect primary [ @host ]
Connects pmlc to the specified pmlogger process. Any
existing connection to a pmlogger instance is closed
first. Each pmlogger instance will accept at most one
connection at a time, so if the connection is success
fully established, your pmlc will be the only one con
trolling the pmlogger instance it is connected to.
new volume
This command works only while a connection to a pmlog
ger instance is established. It tells the pmlogger to
close the current volume of the log and open a new
volume. Closed volumes may be archived, e.g. as part
of a regular log management procedure to control the
size of the physical log files.
status
This command works only while a connection to a pmlog
ger instance is established. It prints information
about the state of the pmlogger instance and its asso
ciated log.
timezone local | logger | "timezone"
This command sets the time zone used when times are
printed. local means use the time zone of the machine
that pmlc is running on. logger means use the time
zone of the machine where the pmlogger instance is
running. Alternatively an explicit timezone enclosed
in quotes may be supplied (refer to TZ in environ(5)
for details). The default time zone is local unless
one of the -z or -Z options has been supplied on the
command line.
flush
This command works only while a connection to a pmlog
ger instance is established, and requests the pmlogger
instance to flush to disk all buffers associated with
the current archive. For old-timers, sync is a syn
onym for flush.
Displays a summary of the available commands.
h and ? are synonyms for help.
quit
Exits from pmlc.
The remaining commands query and change the logging state
of metrics and instances. They will work only if pmlc has
a connection to a pmlogger instance. Metrics may be spec
ified as fully qualified names (e.g. hinv.ncpu) or sub
trees of the PMNS (e.g. hinv) which are expanded to
include all metrics in the subtree (e.g. hinv.ncpu,
hinv.cpuclock, etc.). Lists of metrics may be specified
by enclosing them in braces with spaces or a comma between
metrics (e.g. {hinv.ncpu hinv.ndisk}). Subtrees of met
rics may be included in such lists.
Each individual metric specification may be further quali
fied with a space or comma separated list of instances in
square brackets (e.g. kernel.all.load["1 minute", "5
minute"]). External instance names or numeric internal
instance identifiers or both may be used in the same list
(e.g. sample.colour.[red,1,"blue"]). If an instance qual
ification is applied to a subtree of the PMNS all of the
metrics in the subtree must have the same instance domain.
Instance qualifications may not be applied to entire lists
of metrics but may appear inside such lists.
If no instances are specified for a metric, all instances
are used. All instances means all instances available at
the time the pmlogger instance in question fetches the
metrics for logging. If an instance domain changes over
time this is not always the same as the set of instances
displayed by pmlc, which can only display the currently
available instances. To prevent unintentional errors,
only the instances that are currently available to pmlc
may appear in instance specifications.
query metriclist
The current logging state of each metric (and
instances, where applicable) in metriclist is dis
played. This includes the logging state (e.g. on,
maybe, off) and the logging interval for each metric
(and instance) requested. The following abbreviations
pertaining to metrics (and instances) may appear in
the output: adv, advisory; mand, mandatory; nl, not in
the log; na, in the log but not currently available
from its Performance Metrics Domain Agent (PMDA).
Where appropriate, an instance name will appear last
on a line preceded by its numeric internal instance
identifier.
This form of the log command turns on logging for the
metrics (and any instances) in metriclist. interval
specifies how often the specified metrics/instances
should be logged. once indicates that the met
rics/instances should appear at most once in the log.
More often one would use the optional keyword every
followed by a positive number and one of millisecond
(or msec), second (or sec), minute (or min), hour or
their plurals.
Note that the keyword default which may be used for
the default interval in a pmlogger(1) configuration
file cannot be used in pmlc.
Internal limitations require the interval to be less
than (approximately) 74 hours. An interval value of
zero is a synonym for once.
[ log ] mandatory off metriclist
This tells the pmlogger instance not to log any of the
metrics/instances in metriclist.
[ log ] mandatory maybe metriclist
This tells the pmlogger instance to honor any subse
quent advisory logging requests for the met
rics/instances in metriclist. If the current logging
state of the metrics/instances is mandatory (either on
or off) the new state will be set to maybe (effec
tively advisory off). If the current state of the
metrics/instances is already advisory (either on or
off) the state(s) for the metrics/instances will
remain as they are.
[ log ] advisory on interval metriclist
[ log ] advisory off metriclist
Advisory logging is only applicable if the last log
ging state specified for a metric/instance was "manda
tory maybe" (which permits subsequent advisory logging
control) or if the logging state is already advisory.
These two statements turn advisory logging on or off
(respectively) for the specified metrics/instances.
The interpretation for interval is as above for the
mandatory case.
There is no continuation character required for commands
that span lines.
The word at may be used interchangeably with @.
A request to log all instances of a metric will supersede
any prior request to log either all or specific instances
of a metric (if the request specifies a permissible tran
sition in the logging state). A request to log specific
instances of a metric when all instances of a metric are
already being logged is refused by pmlogger.
Environment variables with the prefix PCP_ are used to
parameterize the file and directory names used by PCP. On
each installation, the file /etc/pcp.conf contains the
local values for these variables. The $PCP_CONF variable
may be used to specify an alternative configuration file,
as described in pcp.conf(4).
SEE ALSO
PCPIntro(1), pmcd(1), pmdumplog(1), pmlogger(1),
pcp.conf(4), pcp.env(4) and environ(5).
DIAGNOSTICS
Most error or warning messages are self-explanatory. A
message of the form
Warning: unable to change logging state for...
followed by a list of metrics (and possibly instances)
indicates that pmlogger refused the request for the met
rics (and instances) that appear. Any metrics (and
instances) that were specified but do not appear in the
message have had their logging state updated successfully
(no news is good news). Usually this warning results from
requesting advisory logging when a mandatory control is
already in place, or requesting logging for specific
instances when all instances are already being logged.
CAVEAT
If all instances of a metric are being logged and a
request is made to log specific instances of the metric
with the same state and frequency, the request may appear
to succeed, even though pmlogger has refused the request.
This is not normally a problem, as the required informa
tion will still be placed into the log by pmlogger.
However in the case where the metric is to be logged once,
the outcome is not what might be expected. When pmlogger
receives a request to log a metric once, it places the
current value(s) of the metric into the log as soon as it
can, regardless of whether the metric is already in the
log. This may be used to force values into the log. When
a request to log specific instances of a metric arrives
and is refused because all instances of the metric are
already being logged, pmlogger does not place values for
the instances requested into the log. It returns the cur
rent logging state for each instance requested to pmlc.
The requested and returned states are identical, so pmlc
doesn't raise an error as it should.
To ensure that only certain instances of a metric are
being logged, one should always turn off logging for all
instances of the metric prior to turning on logging for
the specific instances required.
Man(1) output converted with
man2html