|
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 | CLASS POLICY FILE | OPTIONS | PCP ENVIRONMENT | SEE ALSO | COLOPHON |
|
|
|
PMLOGCTL(1) General Commands Manual PMLOGCTL(1)
pmlogctl - manage and control Performance Co-Pilot archivers
pmlogctl [-afmNV?] [-C check_args] [-c class] [-i ident] [-p
policy] command [host ...]
pmlogctl may be used to manage non-primary instances of the
Performance Co-Pilot (PCP) archiver pmlogger(1). This would be
most relevant in a PCP archiver ``farm'' where many pmlogger(1)
instances would be creating archives of performance data collected
from pmcd(1) on many remote hosts.
The primary pmlogger(1) instance is closely linked to the local
pmcd(1) process and as a consequence shares the same control
infrastructure, namely systemd(1) or the PCP init(1) ``rc
scripts''. This is why the primary pmlogger(1) instance cannot be
managed with pmlogctl.
For brevity in the description below, the term ``instance'' means
a pmlogger(1) instance.
All instances managed by pmlogctl, pmlogger_check(1) and
pmlogger_daily(1) abide by the following rules:
1. Each instance is fetching performance data from a single
pmcd(1) (i.e. one host), but each pmcd(1) may be providing
performance data to zero, one or more pmlogger(1) processes
running on one or more hosts.
2. On the local host, each pmlogger(1) instance must be specified
once in a pmlogger_check(1) control file and pmlogger(1)
creates archives in a unique directory, named in the 4th
parameter of the associated control file entry (see the
CONFIGURATION section of pmlogger_check(1)).
3. Each instance belongs to exactly one class, optionally named
using a $class=... assignment in the associated control file.
The special default class is reserved for all instances that do
not have an associated $class=... assignment. For reporting
purposes (refer to the summary command below), the primary
pmlogger(1) instance is automatically assigned to the special
primary class.
Each pmlogctl execution manages one or more instances updating the
associated control files and then running pmlogger_check(1) to
effect the desired change.
The host arguments are usually valid host names. For all commands
except create and cond-create (described below) the host arguments
may also be egrep(1) regular expressions that match the whole of a
valid host name, so the pattern used is actually ^host$. For
example foo.* (matches all host names beginning with ``foo'') or
.*foo (matches all host names ending with ``foo'') or
.*[fF][oO][oO].* (matches all host names containing ``foo'' in
upper, lower or mixed case).
The combination of a class from the optional -c option (or
default) and the host arguments to each command identifies a
target of set instances to which the command operation should be
applied.
The -i option may be used with the create or cond-create commands
to override the instance identity that is specified in the ident
section of the class policy file (see the CLASS POLICY FILE
section below). Since the identifier must be unique across all
instances and all classes, it only makes sense to use this option
when there is a single host argument.
Given the tasks that pmlogctl is undertaking it usually must be
run as ``root'', the exceptions being the status command or when
the -N option is specified.
command is one of the following:
check
Check the status of all currently configured pmlogger
instances and restart any that have failed. If the -m flag is
given on systemd(1) platforms, also migrate matching (and new)
processes to the pmlogger_farm service.
create
Create new instances in the class classname (default by
default) for the host hosts. The name of the class is used to
identify a class policy file (see the CLASS POLICY FILE
section below) which provides a template for each new control
file with %h replaced by host and %i replaced by the
instance's (unique) identifier from the ident section of the
class policy file or ident from the -i option.
The -p option may be used to identify a class policy file
other than the one found in the standard place, i.e.
$PCP_SYSCONF_DIR/pmlogger/class.d/classname.
At least one host must be specified for the create command.
cond-create
Similar to create but the instance will only be created if one
of the conditions in the create section of associated class
policy file(s) evaluates to true.
If a -c option is specified, then only the class classname
will be considered, otherwise all classes will be considered.
In the latter case, if none of the conditions in any of the
classes evaluates to true, the the special pmfind class is
used (this is the ``default'' class for the cond-create
command when all else fails).
If more than one class evaluates to true then a composite
pmlogger(1) configuration file is created and the instance is
also assigned to the special pmfind class. The composite
configuration file may contain a mix of explicit configuration
clauses and the more general conditional configuration clauses
as understood by the pmlogconf(1) tool.
start
Start the target set of instances.
If the target set intentionally contains more than one
instance, then the -a option should be used (this is designed
to reduce the risk of accidentally starting a potentially
large number of pmlogger(1) processes).
If an instance in the target set is already started, no change
is made (see the restart command to force new instances to be
launched).
stop
Stop the target set of instances.
If the target set intentionally contains more than one
instance, then the -a option should be used (this is designed
to reduce the risk of accidentally stopping a potentially
large number of pmlogger(1) processes).
If an instance in the target set is already stopped, no change
is made but a warning is issued.
restart
Stop and then start the target set of instances.
If the target set intentionally contains more than one
instance, then the -a option should be used (this is designed
to reduce the risk of accidentally stopping and starting a
potentially large number of pmlogger(1) processes).
If an instance in the target set is already stopped, a warning
is issued before the instance is started.
status
Report the status of the target set of instances. If there is
no -c option specified and no host arguments, i.e. the target
set is empty, then all instances will be reported.
destroy
Destroy the target set of instances. At the end of this
operation the associated pmlogger(1) processes will have been
stopped and the relevant control file information removed.
If the target set intentionally contains more than one
instance, then the -a option should be used (this is designed
to reduce the risk of accidentally terminating a potentially
large number of pmlogger(1) processes and removing their
pmlogger_check(1) configurations).
The policy file linked to the class of an instance to be
destroyed may contain a destroy section that may influence if
and how the destroy operation should be performed. This may
require a -p option to find the associated class policy file.
The class policy checking can be by-passed using the -f
(force) command line option.
A class policy file contains a number of sections, each section
begins with a line that simply starts with the name of the section
followed enclosed by ``['' and ``]''.
Lines beginning with a hash (#) are treated as comments and
ignored. Blank or empty lines are also ignored.
The typical location of the policy file for the class foo is
$PCP_SYSCONF_DIR/pmlogger/class.d/foo.
[class]
The optional class name section names the class. If it is
missing, the name of the policy file (stripped of any
directory prefix) is used as the name of the class.
[ident]
The ident section specifies the template to be used for the
instance identifier to be given to each member of the class.
This identifier needs to be unique across all instances and
all classes, and it needs to be a valid file name in the local
filesystem, so would normally contain the class name and the
macro %h, e.g. foo-%h. The macro is replaced by the host when
each instance is created.
[control]
The control section consists of one or more lines of template
text that will be used to create the control file for each
instance. This must at least include the pmlogger_check(1)
control line to specify how to start the associated
pmlogger(1) process; this line contains fields separated by
white space as follows:
1. the hostname, usually the macro %h
2. n to indicate this is a non-primary instance
3. the ``socks'' flag, typically n
4. the directory in which the pmlogger(1) archives will be
created; this needs to be unique and is usually specified
using the pmlogger_check(1) macro PCP_ARCHIVE_DIR as the
start of the path, followed by the instance identifier,
usually the macro %i, e.g. PCP_ARCHIVE_DIR/%i
5. additional parameters to pmlogger(1) which probably
include at least a -c option to provide a configuration
file that describes which metrics should be logged for
instances of this class, which may be the same for all
instances in this class, or it may include the %i macro to
use a different configuration file for each instance.
Note that if this configuration file does not exist, it
will be created using pmlogconf(1) the first time
pmlogger_check(1) is run.
Before the control line there should be a line that defines
the version of the control line that follows, i.e.
$version=1.1
If this is missing, pmlogctl will assume the version is 1.1
and insert the line when the instance is created.
pmlogctl will also add the class name during creation. e.g.
$class=foo
Within a control line template, a simple form of parametric
substitution is supported. The ENV(spec) macro is replaced by
text using environment variables as follows:
• If spec is of the form var then the value of $var from the
environment is used. If $var is not defined or has the
value of an empty string, this is an error.
• If spec is of the form var:default then if $var from the
environment is defined and is not an empty string the
value of $var is used, otherwise the value default is
used. The substitution is simple, so any whitespace
between the : and the ) is included in default, and
default cannot contain a ).
As an example
# unset PMPROXY_PORT; PMPROXY_HOST=foobar.com pmlogctl create
...
with a policy class control template line that includes
http://ENV(PMPROXY_HOST):ENV(PMPROXY_PORT:44322)
will generate a control line that includes
http://foobar.com:44322
[create]
The create section defines the conditions that must be met
before an instance will be created with the cond-create
command. The intent is to allow different decisions to be
made when a new host running pmcd(1) is discovered, e.g. by
pmfind(1).
Each non-blank line in the create section is a condition of
the form function(arg), where function is one of the
following:
exists
arg is the name of a performance metric and exits
evaluates to true if that metric exists in the Performance
Metrics Name Space (PMNS) on the remote host
values
arg is the name of a performance metric in the remote PMNS
and values evaluates to true if some instance of that
metric has a value on the remote host
condition
arg is a derived metric expression in the format supported
by pmRegisterDerived(3), and condition evaluates to true
if the value of that expression on the remote host is
greater than zero
hostname
arg is a regular expression in the style of egrep(1) and
hostname evaluates to true if the remote host name matches
arg
[destroy]
The destroy section defines the policy to be applied when an
instance is destroyed.
The intent is to allow different decisions to be made when
discovery service, e.g. pmfind(1), notices that a host
associated with an instance is no longer present. But in the
current version this is not implemented and the destroy
section syntax and semantics is not yet defined.
A sample class policy file is as follows:
# policy file for the foo class
[class]
foo
[ident]
foo-%h
[control]
$version=1.1
%h n n PCP_ARCHIVE_DIR/%i -c foo-metrics.config
[create]
# matches all hosts
hostname(.*)
[destroy]
# still to be defined
The available command line options are:
-a, --all
Apply action to all matching instances. By default only one
instance definition is expected and acted upon.
-c class, --class=class
Set the name of the class for which pmlogger(1) instances
belong to as class.
-C check_args, --checkargs=check_args
check_args are additional command line arguments for
pmlogger_check(1) when it is called. This is most useful for
options like -V. Multiple -C options may be used and the
various check_args options will be accumulated and all passed
to pmlogger_check(1).
-f, --force
Force action if possible.
-i ident, --ident=ident
Override instance identifier with ident. This option applies
only for the commands create and cond-create.
-N, --showme
Runs pmlogctl in a ``show me'' or ``dry run'' mode where the
intent of the command is shown, but no changes are made.
-m, --migrate
When used with the create or check commands on systemd(1)
platforms, also migrate new or existing non-primary pmlogger
processes to the pmlogger_farm service. This is normally
done automatically by the pmlogger_farm_check service, which
is timer driven (so there may be a few minutes delay before
automatic migration is initiated).
-p policy, --policy=policy
Use policy as the class policy file. Defaults to
$PCP_SYSCONF_DIR/pmlogger/class.d/<class>.
-V, --verbose
Enable verbose mode. Using this option twice increases
verbosity. Verbose output is written to stderr.
-?, --help
Display usage message and exit.
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).
egrep(1), init(1), PCPIntro(1), pmcd(1), pmlc(1), pmlogconf(1),
pmlogger(1), pmlogger_check(1), pmlogger_daily(1), systemd(1),
PMAPI(3), pmDerivedRegister(3) and pcp.conf(5).
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 [email protected]. 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
[email protected]
Performance Co-Pilot PCP PMLOGCTL(1)
Pages that refer to this page: pmlogger_check(1), pmlogger_daily(1), pmlogger.control(5)
|
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. |
|