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 differ­
       ent 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 infor­
       mation 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 customiza­
       tions 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 addi­
       tional 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(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 pcplog_action yes
           ^D
           #

       Then  verify  that the generated file is a valid pmie con­
       figuration 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), "dou­
       ble",  "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  con­
       cept  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  pre­
       ceded  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 meaning­
       ful 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

       "version", "predicate", and "enumerate" attributes.  "ver­
       sion" and "predicate" are fairly self explanatory ("predi­
       cate" 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  multi­
       ple  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

           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/con­
       fig/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  moni­
                 toring rules


SEE ALSO

       pmie(1) and pmieconf(1).


Man(1) output converted with man2html