# pmlogctl

## NAME



           **pmlogctl** - manage and control Performance Co-Pilot archivers
    


## SYNOPSIS



           **pmlogctl**[**-afmNV?**]  [**-C** _check_args_] [**-c** _class_] [**-i** _ident_] [**-p**
           _policy_] _command_ [_host ..._]
    


## DESCRIPTION



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


## COMMANDS



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


## CLASS POLICY FILE



           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
    


## OPTIONS



           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.
    


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


* * *