Provided by: pcp_6.0.3-1_amd64 bug

NAME

       pmlogctl - manage and control Performance Co-Pilot archive loggers

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

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

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

SEE ALSO

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