# pmieconf

## 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
           _attribute_ s.
    
           The generic specification of a pmieconf-rules object is thus:
    
               _type identifier_ [ _attribute_ = _value_ ]* ;
    
           The set of valid _type_ s 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 _attribute_ s 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
    


* * *