|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OPTIONS | ACCESS CONTROL | CAVEATS | DIAGNOSTICS | ENVIRONMENT | PCP ENVIRONMENT | DEBUGGING OPTIONS | SEE ALSO | COLOPHON |
|
|
|
PMLC(1) General Commands Manual PMLC(1)
pmlc - configure active Performance Co-Pilot pmlogger(s)
interactively
pmlc [-eiPz?] [-D debug] [-h host] [-n pmnsfile] [-p port] [-Z
timezone] [pid]
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.
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.
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.
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 │
└───────────────────┴───────────────────────────────────────┘
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.
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.
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.
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).
The -D or --debug option enables the output of additional
diagnostics on stderr to help triage problems, although the
information is sometimes cryptic and primarily intended to provide
guidance for developers rather end-users. debug is a comma
separated list of debugging options; use pmdbg(1) with the -l
option to obtain a list of the available debugging options and
their meaning.
Debugging options specific to pmlc are as follows:
┌────────┬───────────────────────────────────────────────────────┐
│ Option │ Description │
├────────┼───────────────────────────────────────────────────────┤
│ appl0 │ dump metrics and instances received │
├────────┼───────────────────────────────────────────────────────┤
│ appl1 │ dump state after each command is parsed │
└────────┴───────────────────────────────────────────────────────┘
PCPIntro(1), pmcd(1), pmlogdump(1), pmlogger(1), pcp.conf(5),
pcp.env(5), PMNS(5) and environ(7).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at
⟨http://www.pcp.io/⟩. If you have a bug report for this manual
page, send it to pcp@groups.io. This page was obtained from the
project's upstream Git repository
⟨https://github.com/performancecopilot/pcp.git⟩ on 2025-08-11.
(At that time, the date of the most recent commit that was found
in the repository was 2025-08-11.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
Performance Co-Pilot PCP PMLC(1)
Pages that refer to this page: pcpintro(1), pmlogctl(1), pmlogextract(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1), pmlogreduce(1), pmsnap(1), __pmconnectlogger(3), __pmcontrollog(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|