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. In current versions of pmlogger(1)
all writes are unbuffered and aligned with the logical records in the
external files, so this command achieves nothing, but is retained for
backwards compatibility.
- 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.
ACCESS CONTROL¶
pmlc may have restricted access to and control over
pmlogger(1)
processes.
If a
pmlogger(1) is unable to export its control information to the local
pmcd(1), then that
pmlogger(1) cannot cannot be connected to nor
controlled by
pmlc. In practice, this means the
pmlogger(1)
process has to be owned by the user ``pcp'' and/or the group ``pcp''. If
pmlogger(1) is running on the host ``foo'' then use ``pminfo -f -h foo
pmcd.pmlogger'' to verify that the
pmlogger(1) of interest is known to
pmcd(1), alternatively
pmlogger(1) instances that are not
reported from the
pmlc show loggers @foo command are not known
to
pmcd(1) on the host ``foo''.
If
pmlogger(1) is launched with a configuration file that contains an
[access] section, then
pmlc will be unable to connect to that
pmlogger(1) unless the access controls allow
some access from
the host where
pmlc is being run. Minimally this requires the
enquire access to be permitted in the
pmlogger(1) access control
section.
If
pmlc is able to connect to the
pmlogger(1) of interest, then
the following table summarizes the permissions needed to perform different
pmlc commands:
pmlc command |
Required pmlogger access |
|
show loggers |
Any |
connect |
Any of enquire, advisory or mandatory |
status |
Any of enquire, advisory or mandatory |
query ... |
Any of enquire, advisory or mandatory |
log advisory ... |
advisory |
log mandatory ... |
mandatory |
new volume |
mandatory |
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(5).
SEE ALSO¶
PCPIntro(1),
pmcd(1),
pmdumplog(1),
pmlogger(1),
pcp.conf(5),
pcp.env(5) 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.