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 mandatory, 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 Metrics Name
Space (PMNS), however if the -n option is specified 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
connection 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
subsequent connections are made interactively (see the connect 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 prompts.
The -i flag may be used to force interactive 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 specified). 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 successfully established, your pmlc will be the only
one controlling the pmlogger instance it is connected to.
new volume
This command works only while a connection to a pmlogger 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 pmlogger instance
is established. It prints information about the state of the
pmlogger instance and its associated 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 pmlogger 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 synonym for flush.
help
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 specified as fully qualified names
(e.g. hinv.ncpu) or subtrees 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 metrics may be included in such lists.
Each individual metric specification may be further qualified 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 qualification
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 displayed. 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.
[ log ] mandatory on interval metriclist
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 metrics/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 subsequent advisory
logging requests for the metrics/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 (effectively 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 logging state
specified for a metric/instance was "mandatory 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 transition 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.
PCP ENVIRONMENT
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 metrics (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 information
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 current 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.