pmieconf - generalized pmie rules and customizations
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/*/*.
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.
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!
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.
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.
-
$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
pmie(1) and
pmieconf(1).