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 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.
// 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
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$ ;
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 .