# pmlogconf

## NAME



           **pmlogconf** - create/edit a pmlogger configuration file
    


## SYNOPSIS



           **pmlogconf**[**-cqrvV?**]  [**-d** _groupsdir_] [**-D** _debug_] [**-g** _grouptag_] [**-h**
           _host_] [**-s** _groupfile_] _configfile_
    


## DESCRIPTION



           **pmlogconf** may be used to create and modify a generic configuration
           file for the PCP archiver, pmlogger(1).
    
           If _configfile_ does not exist, **pmlogconf** will create a generic
           configuration file with a default set of enabled metrics and
           logging intervals.
    
           Once created, _configfile_ may be used with the **-c** option to
           pmlogger(1) to select performance metrics and specify logging
           intervals for a PCP archive.
    
           If _configfile_ does exist, **pmlogconf** will prompt for input from the
           user to enable or disable groups of related performance metrics
           and to control the logging interval for each enabled group.
    
           Group selection requires a simple **y**(yes) or **n**(no) response to
           the prompt **Log this group?**.
    
           Other responses at this point may be used to select additional
           control functions as follows:
    
           **m** Report the names of the metrics in the current group.
    
           **q** Finish with group selection (quit) and make no further
                     changes to this group or any subsequent group.
    
           **/**_pattern_  Make no change to this group but search for a group
                     containing _pattern_ in the description of the group or
                     the names of the associated metrics.
    
           A logging interval is specified by responding to the **Logging**
           **interval?** prompt with the keywords **once** or **default** or a valid
           pmlogger(1) interval specification of the form ``**every** _N_
           _timeunits_ '' or simply ``_N timeunits ''_ (the **every** is optional)
           where _N_ is an unsigned integer and _timeunits_ is one of the
           keywords **msec** , **millisecond** , **sec** , **second** , **min** , **minute** , **hour** or the
           plural form of one of the keywords.
    
           When run from automated logging setup processes, the **-c** option is
           used to indicate that _pmlogconf_ is in auto-create mode and no
           interactive dialog takes place.  The output _configfile_ has an
           additional comment message and timestamp indicating this fact, so
           that it can be identified and subsequently updated using **-c** again.
           This option is not appropriate for interactive use of the tool.
    
           The **-q** option suppresses the logging interval dialog and preserves
           the current interval from _configfile_.
    
           More verbose output may be enabled with the **-v** option.
    


## SETUP GROUP FILES



           When an initial _configfile_ is created, the default specifications
           come from a set of group files below the _groupsdir_ specified with
           the **-d** option (the default _groupsdir_ is
           **$PCP_VAR_DIR/config/pmlogconf** which is most commonly correct, so
           the **-d** option is rarely used in practice).
    
           The directory structure below _groupsdir_ is arbitrary as all
           regular files will be found by recursive descent and considered,
           so add-on products and PMDA developers can easily extend the
           available defaults to **pmlogconf** by adding new directories and/or
           group files below _groupsdir_.
    
           These group files are processed in the following ways:
    
           •  When a new _configfile_ is created, all group files are
              processed.
    
           •  Whenever **pmlogconf** is run with an existing _configfile_ ,
              _groupsdir_ is traversed to see if any new groups have been
              defined and should be considered for inclusion in _configfile_.
    
           •  When **pmlogconf** processes a group in _configfile_ that is enabled,
              the list of metrics associated with the group is taken from the
              group file (and replaces any previous list of metrics
              associated with this group in _configfile_).
    
           •  When either the **-r**(reprobe) or the **-c**(auto-create) command
              line option is specified, every group (not just newly
              discovered ones) is reprocessed to see if it should be
              considered for inclusion in _configfile_.
    
           •  If a group is found in _configfile_ but the corresponding group
              does not exist below _groupsdir_ (as would be the case when a
              group is made obsolete by a PCP upgrade) then the handling of
              the group depends on the mode in which _pmlogconf_ is being run.
              With **-c** the corresponding group is culled from _configfile_ ,
              otherwise the corresponding group is unchanged in _configfile_.
              In either case a warning is issued.
    
           Each group file is structured as follows:
    
           •  The first line must contain **#pmlogconf-setup 2.0**
    
           •  Other lines beginning with **#** are treated as comments.
    
           •  Blank lines are ignored.
    
           •  One or more lines starting with the keyword **ident** are used to
              provide the human-readable description of the group.
    
           •  Non-blank lines beginning with white space define metrics to be
              associated with this group, one per line.  Each metric
              specification follows the rules for a pmlogger(1)
              configuration, namely either the name of a non-leaf node in the
              PMNS (implying all descendent names in the PMNS), or the name
              of a leaf node in the PMNS optionally followed by one or more
              instance names enclosed by ``['' and ``]''.
    
           •  A control line starting with one of the keywords **probe** or **force**
              must be present.
    
           •  An optional logging interval control line begins with the
              keyword **delta** followed by one of the pmlogger(1) interval
              specification described above.
    
           •  **probe** control lines have the format:
                          **probe** _metric_ [_condition_ [_state_rule_] ]
              where _metric_ is the name of a PCP metric (must be a leaf node
              in the PMNS, no instance specification is allowed, and it must
              not be a derived metric) and the optional _condition_ is the
              keyword **exists**(true if _metric_ exists, i.e. is defined in the
              PMNS) or the keyword **values**(true if _metric_ exists in the PMNS
              and has one or more current values) or an expression of the
              form
                                          _op val_
              where _op_ is one of the **awk**(1) operators (**==** , **!=** , **>** , **> =**, **<** , **< =**,
              **~**(regular expression match) or **!~**(negated regular expression
              match)) and _val_ is a value (arbitrary sequence of characters,
              excluding a space) and the _condition_ is true if there is some
              instance of _metric_ that makes the expression true.
    
              If the _condition_ is missing, the default is **exists**.
    
              When an explicit _condition_ is provided, there may also be an
              optional _state_rule_ of the form
                                **?**_true_state_ **:**_false_state_
              where _true_state_ (applies if _condition_ is true) and _false_state_
              (applies if _condition_ is false) are both taken from the
              keywords **include**(include and enable the group and the
              associated metrics in _configfile_), **available**(include and
              disable the group in _configfile_ - a user action of **y** as
              described above is needed to enable the group and add the
              associated metrics into _configfile_) or **exclude**(the group is
              not considered for inclusion in _configfile_).
    
              The default _state_rule_ is
                                   **? available : exclude**
    
           •  **force** control lines begin with the keyword **force** followed by
              one of the states defined above, so one of the actions **include** ,
              **exclude** or **available** is applied unconditionally to the group.
    
           Probing is only done when a new group is being added to _configfile_
           or when the **-r** command line option is specified.  The evaluation
           of the probing conditions is done by contacting pmcd(1) on
           _hostname_ (defaults to local:).
    


## OPTIONS



           The available command line options are:
    
           **-c** Enable non-interactive, auto-create mode.
    
           **-d** _groupsdir_ , **--groups** =_groupsdir_
                Specify the path to the _groupsdir_ directory.
    
           **-g** _grouptag_ , **--group** =_grouptag_
                Query logging state for the specific logging group named
                _grouptag_.
    
           **-h** _host_ , **--host** =_host_
                Performance metrics source is pmcd(1) on _host_ , rather than on
                the default localhost.
    
           **-q** , **--quiet**
                Quiet mode, suppress logging interval dialog.
    
           **-r** , **--reprobe**
                Reconsider every group for inclusion in the _configfile_.
    
           **-s** _groupfile_ , **--setup** =_groupfile_
                Report the default logging state for the one logging group in
                _groupfile_.  This is equivalent output to that produced by the
                retired **pmlogconf-setup** shell script from earlier versions of
                PCP.
    
           **-v** , **--verbose**
                Enable verbose mode.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-?** , **--help**
                Display usage message and exit.
    


## EXAMPLE



           The following group file demonstrates all of the supported
           syntactic elements.
    
           #pmlogconf-setup 2.0
           ident   Example group file
           ident   ... more description
           delta   1 minute
           probe   sample.secret.foo.one values ? include : exclude
                   sample.secret.foo.one
                   sample.secret.foo.bar   # non-leaf in the PMNS
                   sample.colour [ red green ]
    


## MIGRATION



           The current version of **pmlogconf**(2.0) supports a slightly
           different format for _configfile_ compared to earlier versions.  If
           an old version _configfile_ is presented to **pmlogconf** it will be
           converted to the new format.
    


## 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).
    
           **pmlogconf** overrides any **$PCP_DERIVED_CONFIG** environment variable
           to an empty string, for performance reasons.
    
           **pmlogconf** honours the **$PMCD_WAIT_TIMEOUT** environment variable when
           probing and creating new **pmlogger** configuration files.  It uses a
           default timeout value of 10 seconds for this, in the absence of an
           environment setting.
    


## DEBUGGING OPTIONS



           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



           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 **pmlogconf** are as follows:
           ┌────────┬─────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼─────────────────────────┤
           │ **appl0** │ group file operations   │
           ├────────┼─────────────────────────┤
           │ **appl1** │ metric probe operations │
           └────────┴─────────────────────────┘
    


* * *