NAME
pmrules - template file format for pmrules(1)
DESCRIPTION
pmrules(1) allows restricted editing of pmie(1) rules via
an intermediate representation known as a template. A
template is a parameterized description of a rule. The
template describes which parts of the rule a user may
change and also provides information for pmrules to do
some type checking.
A template file consists of a header, some optional global
parameters and a list of rule definitions each with
optional local parameters.
A line beginning with # is considered a comment. Strings
are delimited by double quotes (") and newlines within
strings are preserved.
Header
The header should look like this:
#!$PCP_BIN_DIR/pmrules
# pmrules 1.0
And be followed by a ruleset definition of the form
ruleset name help=helptext;
Where name is a string or an identifier (following the
standard C conventions) and helptext is a string contain
ing a description of what the rules described by this set
of templates are designed to do. This will appear at the
top of the help text in the Edit Global Parameters dialog
box in pmrules so it should be something that the user
editing the templates will understand. pmrules does not
do line breaking, so sensible use of newlines within the
helptext is encouraged.
Parameters
Parameter definitions (both global and local) have the
following form:
name value attrlist;
Where an name is an identifier (following the standard C
conventions), and attrlist consists of a list of whites
pace separated attribute=value pairs.
The following attributes are defined for parameters:
type Defines a type for the parameter. pmrules may be
as integers. For more complex types such as metric
instance lists, checking may not be possible (e.g.
if a host is down the set of valid instances is
unknown). Valid values for type are: string,
strong (a non-null string), double, int, unsigned,
% (a percentage), host, hostlist, inst (a single
valid instance of a performance metric), instlist
(a list of inst), script (an executable program or
shell script, as used in the action part of a pmie
rule), scriptlist (a list of script). If no type
is specified, the default is string.
display
Valid values are yes, display the parameter for the
user (the default) and no, hide the parameter.
modify Valid values are yes, allow the user to modify the
parameter (the default) and no, the parameter is a
constant.
default
Specifies a default (fallback) value for the param
eter.
metric The value is the name of a performance metric with
an associated instance domain (see PMAPI(3)) for
the parameter if it is of type inst or instlist.
help The value is a string describing the parameter.
This is the help text for the parameter displayed
by pmrules. pmrules does not do line breaking, so
sensible use of newlines within the help string is
encouraged.
Some parameters are reserved by the pmie rule generator
within pmrules(1). Use of parameters with the same name
for other purposes is unwise. Just as with normal parame
ters, a definition in a template will take precedence over
a global definition. The reserved parameters are:
actions
A list of semicolon separated shell commands to
invoke when a rule fires. Each shell command is
preceded by a y or n the a space to indicate
whether the command (action) is enabled or disabled
(respectively). If a shell command begins with a
slash (``/'') it is taken to be an absolute path
otherwise the shell command is expected to exist in
$PCP_VAR_DIR/config/pmie. Two special parameters
rule and host are defined for actions. rule is the
name of the rule that invoked the action and host
is the host for which the rule fired. It is normal
for a template to define an action and a
action which a pmrules user can modify to perform
arbitrary actions.
hosts The list of hosts for which a rule should be evalu
ated.
delta The frequency with which pmie should evaluate the
rule. If no delta is specified (either locally or
globally), pmie will use a default. The default
can be overridden on the pmie command line when it
is run.
holdoff
This is the hold off time pmie uses to prevent a
rule from firing too often.
Rule Definitions
A list of one or more rule definitions should appear.
Rule definitions have the following form:
rule name rule_attrs;
Any local parameter definitions for the rule should follow
immediately after it.
name should be a string or an identifier (following the
standard C conventions). It is best to choose a meaning
ful name, since the rule names are what the user sees when
browsing lists of templates, e.g. "main memory exhaustion"
rather then "nomem". rule_attrs consists of a list of
whitespace separated attribute=value pairs.
The following attributes are defined for rules:
enable Determines whether pmie will evaluate the rule
(yes, the default) or not (no).
cond A string containing the condition for the pmie
rule. Any references to parameters in the string
should be enclosed in $ signs, e.g. "... > $thresh
old$ ..." will substitute the threshold parameter
in the condition.
help This will appear at the top of the help text in the
Edit Template dialog box in pmrules so it should be
a general description of what the rule does. Don't
forget that parameters get their own help text.
FILES
$PCP_VAR_DIR/config/pmrules/*
template files supplied with the Performance Co-
Pilot (PCP) and its various add-on products.
scripts for standard pmie actions supplied with
the Performance Co-Pilot (PCP) and its various
add-on products.
SEE ALSO
pmie(1), pmrules(1) and PMAPI(3).
Man(1) output converted with
man2html