Provided by: pcp_3.5.11_i386 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).