Provided by: pcp_5.0.3-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).