bionic (5) pmieconf.5.gz

Provided by: pcp_4.0.1-1_amd64 bug

NAME

       pmieconf - generalized pmie rules and customizations

DESCRIPTION

       The  pmieconf file formats are used by the pmieconf(1) tool as a way to generalize pmie(1) rule sets such
       that they can be easily configured for different systems  and  different  environments.   There  are  two
       completely  different  (although  closely related) file formats discussed here, namely ``pmieconf-rules''
       and ``pmieconf-pmie''.

       The directory $PCP_VAR_DIR/config/pmieconf  contains  information  about  all  the  default  system  pmie
       generalized  rules  and  variables,  including  default values for all variables.  These files are in the
       pmieconf-rules format.  Although new pmieconf-rules files can be  added,  the  files  in  this  directory
       should  never  be  changed.   Instead,  use  the  pmieconf  utility to change variable values in the pmie
       configuration file.

       The pmieconf-pmie format allows site specific customizations of the  rules  contained  in  pmieconf-rules
       files  and  their associated variables.  The pmieconf-pmie format is generated by pmieconf and should not
       be edited by hand.  This generated file is in the pmie format, with some additional information  held  at
       the  head of the file - thus, the pmieconf-pmie format is a superset of the pmie file format (extended to
       hold customizations to the generalized rules, but also containing the actual performance rules  for  pmie
       to  evaluate)  which  can also be parsed by pmie (all extensions are hidden within comments, and are thus
       meaningless to pmie itself).

       The  file  $PCP_VAR_DIR/config/pmieconf/config.pmie  contains  local   system   settings   for   pmieconf
       configurable  variables.   The  variable  settings  in  this file replace the default values specified in
       $PCP_VAR_DIR/config/pmieconf/*/*.

PMIECONF-PMIE SYNTAX

       All rule customization lines in a valid pmieconf-pmie  specification  are  prefixed  by  ``//''  and  are
       located  at  the  head  of  the  file  - this allows files containing a pmieconf-pmie specification to be
       successfully parsed by pmie.  A pmieconf-pmie must always have the first line in the form:

           // pmieconf-pmie version pmieconf_path

       The version specifies which version of the pmieconf-pmie syntax  should  be  used  to  parse  this  file.
       Currently  the  only  supported version is 1.  The pmieconf_path specifies the path to the pmieconf-rules
       files which were used, by pmieconf, to generate this file.  This is discussed in the pmieconf(1) man page
       (see the -r option).

       The  remainder of the specification consists of one line entries for each of the modified variables.  The
       syntax for each line is:

           // rule_version rule_name rule_variable = value

       The rule_version and rule_name are used to identify the rule with which to associate  the  customization.
       These are followed by the rule_variable name (i.e. the variable of rule rule_name which has been changed)
       for which the new value is to be used.

       A pmieconf-pmie specification must be terminated with the ``end'' keyword.  This is used by  pmieconf  to
       distinguish where the customizations ends, and the actual pmie rule component begins.

PMIECONF-PMIE EXAMPLE

       The  following  example is a valid pmieconf-pmie format file, as generated by pmieconf.  In order to make
       changes by hand which are preserved by pmieconf, see the comments contained in the generated file (below)
       as to where such changes should be made.

           // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf
           // 1 memory.exhausted delta = "4 minutes"
           // 1 memory.exhausted enabled = yes
           // 1 memory.exhausted pcplog_action = yes
           // end
           //
           // --- START GENERATED SECTION (do not change this section) ---
           //     generated by pmieconf on:  [DATESTAMP]
           //

           // 1 memory.exhausted
           delta = 4 minutes;
           some_host (
               ( avg_sample (swap.pagesout @0..9 ) ) > 0 &&
               30 %_sample swap.pagesout >= 5
           ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \
                   " %vpgsout/s@%h";

           // --- END GENERATED SECTION (changes below will be preserved) ---

       To see how this all works, you can generate this file as follows:

           # cat - | pmieconf -f /tmp/pmieconf.out \
               -r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global
           modify memory.exhausted delta "4 minutes"
           modify memory.exhausted enabled yes
           modify memory.exhausted pcplog_action yes
           ^D
           #

       Then verify that the generated file is a valid pmie configuration file using:

           # pmie -C /tmp/pmieconf.out

       This  parses the file, and then exits after reporting any syntax errors.  Now replace -C with -v (above),
       and watch pmie do its work!

PMIECONF-RULES SYNTAX

       A pmieconf-rules specification consists of a number of  separate  data  objects  which  together  form  a
       complete  rule  specification  (note  that  a  specification  may  span  multiple files and even multiple
       subdirectories).  Each object must have an identifier string and a data type, followed by  an  (optional)
       list of attributes.

       The generic specification of a pmieconf-rules object is thus:

           type identifier [ attribute = value ]* ;

       The  set of valid types is: "rule" (rule definition), "string" (arbitrary, double-quote enclosed string),
       "double", "integer", "unsigned", "percent" (real number between 0 and 100), "hostlist"  (space  separated
       list of host names), "instlist" (space separated list of metric instance names), and the four pmie action
       types, namely "print", "shell", "alarm", and "syslog".

       Rule names use the ``.'' character to introduce the concept of  a  rule  group,  e.g.  "memory.exhausted"
       associates this rule with the "memory" group.  pmieconf can operate at either the level of rule groups or
       individual rules.  The group name "global" is reserved and may not be used with any rule.

       Usually when an object is created it is associated with the current rule.  However, if an  object's  name
       is preceded by the reserved group name "global", then that object is visible to all rules.

       The  set  of valid attributes is: "help" (descriptive text about this object), "modify" (value is yes/no,
       flags whether pmieconf should allow changes), "enabled" (value is yes/no, flags whether this is on or off
       -  only  meaningful  for  rules and actions), "display" (yes/no - flags whether pmieconf should show this
       object), "default" (value determined by type, and is the default value for this object), and specific  to
       objects  of  rule  type  are  the  "version",  "predicate",  and  "enumerate"  attributes.  "version" and
       "predicate" are fairly self explanatory ("predicate" must equate to a valid pmie rule when expanded), but
       "enumerate" requires further discussion.

       The  "enumerate"  clause  is  useful when you wish to generate multiple, similar pmie rules from a single
       predicate.  This is most useful for rule definitions wishing to use the "some_inst" clause  in  the  pmie
       language  across  multiple hosts.  For a rule to use these together, it must be certain that the instance
       list is the same on all of the monitored hosts.  This is rarely true, so the "enumerate" attribute allows
       us  to  generate  multiple rules, expanded over variables of either type "instlist" or "hostlist".  These
       variables make up the value for the "enumerate" attribute - which is a space-separated list of "instlist"
       or "hostlist" variable names.

       Objects can be incorporated into other object definitions using the $identifier$ syntax.  See the example
       later for more insight into how this is useful.

       When pmieconf is generating the pmie configuration file, it looks at each enabled  rule  with  N  enabled
       actions (where N > 0) and expands the string:

           // "version" identifier
           delta = $delta$;
           "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;

       The  delta,  threshold,  and  action  variables are defined globally (using the "global" keyword) for all
       rules, but can, of course, be changed at the level of an individual rule or rule group.

PMIECONF-RULES EXAMPLE

       The following is an example of a single pmieconf-rules  specification,  showing  a  number  of  different
       aspects  of  the  language discussed above.  The example defines a rule ("memory.exhausted") and a string
       ("rule").

           rule    memory.exhausted
                   default = "$rule$"
                   predicate =
           "some_host (
               ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 &&
               $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$
           )"
                   enabled = yes
                   version = 1
                   help    =
           "The system is swapping modified pages out of main memory to the
           swap partitions, and has been doing this on at least pct of the
           last 10 evaluations of this rule.
           There appears to be insufficient main memory to meet the resident
           demands of the current workload.";

           string  rule
                   default = "Severe demand for real memory"
                   modify  = no
                   display = no;

       Note that for the above rule to be complete, "threshold" and "pct" would also need to be  defined  -  for
       the full expression of this rule, refer to $PCP_VAR_DIR/config/pmieconf/memory/exhausted.

FILES

       $PCP_VAR_DIR/config/pmieconf/*/*
                 generalized system resource monitoring rules
       $PCP_VAR_DIR/config/pmieconf/config.pmie
                 default super-user settings for system resource monitoring rules
       $HOME/.pcp/pmie/config.pmie
                 default user settings for system resource monitoring rules

SEE ALSO

       pmie(1) and pmieconf(1).