diff options
Diffstat (limited to 'man/man5/pmieconf.5')
| -rw-r--r-- | man/man5/pmieconf.5 | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/man/man5/pmieconf.5 b/man/man5/pmieconf.5 new file mode 100644 index 0000000..5314463 --- /dev/null +++ b/man/man5/pmieconf.5 @@ -0,0 +1,308 @@ +'\"macro stdmacro +.ie \(.g \{\ +.\" ... groff (hack for khelpcenter, man2html, etc.) +.TH PMIECONF 5 "PCP" "Performance Co-Pilot" +\} +.el \{\ +.if \nX=0 .ds x} PMIECONF 5 "PCP" "Performance Co-Pilot" +.if \nX=1 .ds x} PMIECONF 5 "Performance Co-Pilot" +.if \nX=2 .ds x} PMIECONF 5 "" "\&" +.if \nX=3 .ds x} PMIECONF "" "" "\&" +.TH \*(x} +.rr X +\} +.SH NAME +pmieconf \- generalized pmie rules and customizations +.SH DESCRIPTION +The pmieconf file formats are used by the +.BR pmieconf (1) +tool as a way to generalize +.BR 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''. +.PP +The directory +.B $PCP_VAR_DIR/config/pmieconf +contains information about all the default system +.B 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 +.B pmieconf +utility to change variable values in the +.B pmie +configuration file. +.PP +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 +.B pmieconf +and should not be edited by hand. +This generated file is in the +.B pmie +format, with some additional information held at the head of the file \- thus, +the pmieconf-pmie format is a superset of the +.B pmie +file format (extended to hold customizations to the generalized rules, but +also containing the actual performance rules for +.B pmie +to evaluate) which can also be parsed by +.B pmie +(all extensions are hidden within comments, and are thus meaningless to +.B pmie +itself). +.PP +The file +.B $PCP_VAR_DIR/config/pmieconf/config.pmie +contains local system settings for +.B pmieconf +configurable variables. +The variable settings in this file replace the default values specified in +.BR $PCP_VAR_DIR/config/pmieconf/*/* . +.SH 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 +.BR pmie . +A pmieconf-pmie must always have the first line in the form: +.sp +.nf + // pmieconf-pmie \f2version\f1 \f2pmieconf_path\f1 +.fi +.sp +The +.I version +specifies which version of the pmieconf-pmie syntax should be used to +parse this file. +Currently the only supported version is 1. The +.I pmieconf_path +specifies the path to the pmieconf-rules files which were used, by +.BR pmieconf , +to generate this file. This is discussed in the +.BR pmieconf (1) +man page (see the +.B \-r +option). +.PP +The remainder of the specification consists of one line entries for each +of the modified variables. The syntax for each line is: +.sp +.nf + // \f2rule_version\f1 \f2rule_name\f1 \f2rule_variable\f1 = \f2value\f1 +.fi +.sp +The +.I rule_version +and +.I rule_name +are used to identify the rule with which to associate the customization. +These are followed by the +.I rule_variable +name (i.e. the variable of rule +.I rule_name +which has been changed) +for which the new +.I value +is to be used. +.PP +A pmieconf-pmie specification must be terminated with the ``end'' keyword. +This is used by +.B pmieconf +to distinguish where the customizations ends, and the actual +.B pmie +rule component begins. +.SH PMIECONF-PMIE EXAMPLE +The following example is a valid pmieconf-pmie format file, as generated by +.BR pmieconf . +In order to make changes by hand which are preserved by +.BR pmieconf , +see the comments contained in the generated file (below) as to where such +changes should be made. +.sp +.nf + // 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) --- +.fi +.sp +.PP +To see how this all works, you can generate this file as follows: +.sp +.nf + # 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 + # +.fi +.sp +Then verify that the generated file is a valid +.B pmie +configuration file using: +.sp +.nf + # pmie \-C /tmp/pmieconf.out +.fi +.sp +This parses the file, and then exits after reporting any syntax errors. +Now replace \-C with \-v (above), and watch +.B pmie +do its work! +.SH 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 +.I identifier +string and a data +.IR type , +followed by an (optional) list of +.IR attribute s. +.PP +The generic specification of a pmieconf-rules object is thus: +.sp +.nf + \f2type\f1 \f2identifier\f1 [ \f2attribute\f1 = \f2value\f1 ]* ; +.fi +.sp +The set of valid +.IR type s +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 +.B pmie +action types, namely +"print", "shell", "alarm", and "syslog". +.PP +Rule names use the ``.'' character to introduce the concept of a rule group, +e.g. "memory.exhausted" associates this rule with the "memory" group. +.B 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. +.PP +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. +.PP +The set of valid +.IR attribute s +is: "help" (descriptive text about this object), "modify" (\f2value\f1 is +yes/no, flags whether +.B pmieconf +should allow changes), "enabled" (\f2value\f1 is yes/no, flags whether this is +on or off - only meaningful for rules and actions), "display" (yes/no - flags +whether +.B pmieconf +should show this object), "default" (\f2value\f1 determined by \f2type\f1, 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 +.B pmie +rule when expanded), but "enumerate" requires further discussion. +.PP +The "enumerate" clause is useful when you wish to generate multiple, similar +.B pmie +rules from a single predicate. +This is most useful for rule definitions wishing to use the "some_inst" +clause in the +.B 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. +.PP +Objects can be incorporated into other object definitions using the +$\f2identifier\f1$ syntax. See the example later for more insight into +how this is useful. +.PP +When +.B pmieconf +is generating the +.B pmie +configuration file, it looks at each enabled rule with N enabled +actions (where N > 0) and expands the string: +.sp +.nf + // "version" \f2identifier\f1 + delta = $delta$; + "predicate" -> $threshold$ $action1$ & ... & $actionN$ ; +.fi +.sp +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. +.SH 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"). +.sp +.nf + 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; +.fi +.sp +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 +.IR $PCP_VAR_DIR/config/pmieconf/memory/exhausted . +.PP +.SH FILES +.PD 0 +.TP 10 +.IR $PCP_VAR_DIR/config/pmieconf/ */* +generalized system resource monitoring rules +.TP 10 +.I $PCP_VAR_DIR/config/pmieconf/config.pmie +default super-user settings for system resource monitoring rules +.TP 10 +.I $HOME/.pcp/pmie/config.pmie +default user settings for system resource monitoring rules +.PD +.SH SEE ALSO +.BR pmie (1) +and +.BR pmieconf (1). |