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