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