Ubuntu Manpage: pmlogconf - create/edit a pmlogger configuration file

NAME

       pmlogconf - create/edit a pmlogger configuration file

SYNOPSIS

       pmlogconf [-cqrvV?]  [-d groupsdir] [-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.