PMIECONF(5)							File Formats Manual						       PMIECONF(5)

PMIECONF(5)							File Formats Manual						       PMIECONF(5)

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 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, includ-
       ing 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  set-
       tings 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, to generate this  file.   This  is  dis-
       cussed 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	customiza-
       tions 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 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!

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, fol-
       lowed 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.

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
	   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.

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 monitoring rules

SEE ALSO

       pmie(1) and pmieconf(1).

Performance Co-Pilot							PCP							       PMIECONF(5)