Provided by: pcp_6.3.1-1_amd64 
NAME
pmlc - configure active Performance Co-Pilot pmlogger(s) interactively
SYNOPSIS
pmlc [-eiPz?] [-h host] [-n pmnsfile] [-p port] [-Z timezone] [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(7). 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.
COMMANDS
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 archive and open a new volume.
Closed volumes may be compressed and/or moved to a remote system, remote storage or
off-line storage, e.g. as part of a regular archive management procedure to control
the size of the physical archive files on the system where pmlogger is running.
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
archive.
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(7) 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.
disconnect
Disconnect pmlc from the current pmlogger instance, if any.
sleep delay
Pause pmlc for delay milliseconds. This may be helpful in scripted uses of pmlc to
allow the current pmlogger instance to make progress on recent requests before
interrogating the status.
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 logged (not in the archive); na, in the archive 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
archive. 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 archive 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 archive 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 archive specific instances of a metric
when all instances of a metric are already being logged is refused by pmlogger.
OPTIONS
The available command line options are:
-e, --echo
Echo all command input on standard output.
-h host, --host=host
Connect pmlogger on host, rather than on the default localhost.
-i, --interactive
Force interactive behavior.
-n pmnsfile, --namespace=pmnsfile
Load an alternative Performance Metrics Name Space (PMNS(5)) from the file pmnsfile.
-p port, --port=port
Connect to the primary pmlogger on TCP/IP port port.
-P, --primary
Connect to the primary pmlogger.
-z, --logzone
Use local time of the pmlogger as the reporting timezone.
-Z timezone, --timezone=timezone
Use timezone for the date and time. Timezone is in the format of the environment
variable TZ as described in environ(7).
-?, --help
Display usage message and exit.
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 │
│disconnect │ Any │
│log advisory ... │ advisory │
│log mandatory ... │ mandatory │
│new volume │ mandatory │
└──────────────────┴───────────────────────────────────────┘
CAVEATS
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 archive 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 archive a metric once, it places the
current value(s) of the metric into the archive as soon as it can, regardless of whether
the metric is already in the archive. This may be used to force values into the archive.
When a request to archive 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 archive. 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.
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.
ENVIRONMENT
If the PMLOGGER_REQUEST_TIMEOUT environment variable is not set or set to 0 (zero), then
pmlc will block until a connection is established with pmlogger(1) on the requested port.
If PMLOGGER_REQUEST_TIMEOUT is set to a value greater than zero, then pmlc will fail with
an error after that many seconds if a connection isn't established. This may be used by
administrative scripts such as pmlogger_daily(1) to poll pmlogger when is starting up
until it is ready and listening on it's control port.
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), pmlogdump(1), pmlogger(1), pcp.conf(5), pcp.env(5), PMNS(5) and
environ(7).