pmlogctl(1) — Linux manual page


PMLOGCTL(1)              General Commands Manual             PMLOGCTL(1)

NAME         top

       pmlogctl - manage and control Performance Co-Pilot archive

SYNOPSIS         top

       pmlogctl [-afNV?]  [-c class] [-i ident] [-p policy] command
       [host ...]

DESCRIPTION         top

       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 archive logger ``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

       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.

COMMANDS         top

       command is one of the following:

           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.

           At least one host must be specified for the create command.

           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 evalutes 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 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 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.

           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.

           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 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

           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.

           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.

           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.
           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.

           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

           Each non-blank line in the create section is a condition of
           the form function(arg), where function is one of the

               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

               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

               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

               arg is a regular expression in the style of egrep(1) and
               hostname evaluates to true if the remote host name
               matches arg

           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

           %h n n PCP_ARCHIVE_DIR/%i -c foo-metrics.config

           # matches all hosts

           # still to be defined

OPTIONS         top

       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.

       -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.

       -p policy, --policy=policy
            Use policy as the class policy file.  Defaults to

       -V, --verbose
            Enable verbose mode.  Using this option twice increases

       -?, --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

SEE ALSO         top

       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).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual
       page, send it to  This page was obtained from the
       project's upstream Git repository
       ⟨⟩ on 2021-08-27.
       (At that time, the date of the most recent commit that was found
       in the repository was 2021-08-27.)  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

Performance Co-Pilot               PCP                       PMLOGCTL(1)

Pages that refer to this page: pmlogger_check(1)