1PMIECONF(5) File Formats Manual PMIECONF(5)
2PMIECONF(5) File Formats Manual PMIECONF(5)
10
16 pmieconf - generalized pmie rules and customizations
17
19 The pmieconf file formats are used by the pmieconf(1) tool as a way to
20 generalize pmie(1) rule sets such that they can be easily configured
21 for different systems and different environments. There are two com‐
22 pletely different (although closely related) file formats discussed
23 here, namely ``pmieconf-rules'' and ``pmieconf-pmie''.
24 The directory $PCP_VAR_DIR/config/pmieconf contains information about
26 all the default system pmie generalized rules and variables, including
27 default values for all variables. These files are in the pmieconf-
28 rules format. Although new pmieconf-rules files can be added, the
29 files in this directory should never be changed. Instead, use the
30 pmieconf utility to change variable values in the pmie configuration
31 file.
32 The pmieconf-pmie format allows site specific customizations of the
34 rules contained in pmieconf-rules files and their associated variables.
35 The pmieconf-pmie format is generated by pmieconf and should not be
36 edited by hand. This generated file is in the pmie format, with some
37 additional information held at the head of the file - thus, the
38 pmieconf-pmie format is a superset of the pmie file format (extended to
39 hold customizations to the generalized rules, but also containing the
40 actual performance rules for pmie to evaluate) which can also be parsed
41 by pmie (all extensions are hidden within comments, and are thus mean‐
42 ingless to pmie itself).
43 The file $PCP_VAR_DIR/config/pmieconf/config.pmie contains local system
45 settings for pmieconf configurable variables. The variable settings in
46 this file replace the default values specified in $PCP_VAR_DIR/con‐
47 fig/pmieconf/*/*.
48
50 All rule customization lines in a valid pmieconf-pmie specification are
51 prefixed by ``//'' and are located at the head of the file - this
52 allows files containing a pmieconf-pmie specification to be success‐
53 fully parsed by pmie. A pmieconf-pmie must always have the first line
54 in the form:
55 // pmieconf-pmie version pmieconf_path
57 The version specifies which version of the pmieconf-pmie syntax should
59 be used to parse this file. Currently the only supported version is 1.
60 The pmieconf_path specifies the path to the pmieconf-rules files which
61 were used, by pmieconf, to generate this file. This is discussed in
62 the pmieconf(1) man page (see the -r option).
63 The remainder of the specification consists of one line entries for
65 each of the modified variables. The syntax for each line is:
66 // rule_version rule_name rule_variable = value
68 The rule_version and rule_name are used to identify the rule with which
70 to associate the customization. These are followed by the rule_vari‐
71 able name (i.e. the variable of rule rule_name which has been changed)
72 for which the new value is to be used.
73 A pmieconf-pmie specification must be terminated with the ``end'' key‐
75 word. This is used by pmieconf to distinguish where the customizations
76 ends, and the actual pmie rule component begins.
77
79 The following example is a valid pmieconf-pmie format file, as gener‐
80 ated by pmieconf. In order to make changes by hand which are preserved
81 by pmieconf, see the comments contained in the generated file (below)
82 as to where such changes should be made.
83 // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf
85 // 1 memory.exhausted delta = "4 minutes"
86 // 1 memory.exhausted enabled = yes
87 // 1 memory.exhausted pcplog_action = yes
88 // end
89 //
90 // --- START GENERATED SECTION (do not change this section) ---
91 // generated by pmieconf on: [DATESTAMP]
92 //
93 // 1 memory.exhausted
95 delta = 4 minutes;
96 some_host (
97 ( avg_sample (swap.pagesout @0..9 ) ) > 0 &&
98 30 %_sample swap.pagesout >= 5
99 ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \
100 " %vpgsout/s@%h";
101 // --- END GENERATED SECTION (changes below will be preserved) ---
103 To see how this all works, you can generate this file as follows:
106 # cat - | pmieconf -f /tmp/pmieconf.out \
108 -r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global
109 modify memory.exhausted delta "4 minutes"
110 modify memory.exhausted enabled yes
111 modify memory.exhausted pcplog_action yes
112 ^D
113 #
114 Then verify that the generated file is a valid pmie configuration file
116 using:
117 # pmie -C /tmp/pmieconf.out
119 This parses the file, and then exits after reporting any syntax errors.
121 Now replace -C with -v (above), and watch pmie do its work!
122
124 A pmieconf-rules specification consists of a number of separate data
125 objects which together form a complete rule specification (note that a
126 specification may span multiple files and even multiple subdirecto‐
127 ries). Each object must have an identifier string and a data type,
128 followed by an (optional) list of attributes.
129 The generic specification of a pmieconf-rules object is thus:
131 type identifier [ attribute = value ]* ;
133 The set of valid types is: "rule" (rule definition), "string" (arbi‐
135 trary, double-quote enclosed string), "double", "integer", "unsigned",
136 "percent" (real number between 0 and 100), "hostlist" (space separated
137 list of host names), "instlist" (space separated list of metric
138 instance names), and the four pmie action types, namely "print",
139 "shell", "alarm", and "syslog".
140 Rule names use the ``.'' character to introduce the concept of a rule
142 group, e.g. "memory.exhausted" associates this rule with the "memory"
143 group. pmieconf can operate at either the level of rule groups or
144 individual rules. The group name "global" is reserved and may not be
145 used with any rule.
146 Usually when an object is created it is associated with the current
148 rule. However, if an object's name is preceded by the reserved group
149 name "global", then that object is visible to all rules.
150 The set of valid attributes is: "help" (descriptive text about this
152 object), "modify" (value is yes/no, flags whether pmieconf should allow
153 changes), "enabled" (value is yes/no, flags whether this is on or off -
154 only meaningful for rules and actions), "display" (yes/no - flags
155 whether pmieconf should show this object), "default" (value determined
156 by type, and is the default value for this object), and specific to
157 objects of rule type are the "version", "predicate", and "enumerate"
158 attributes. "version" and "predicate" are fairly self explanatory
159 ("predicate" must equate to a valid pmie rule when expanded), but "enu‐
160 merate" requires further discussion.
161 The "enumerate" clause is useful when you wish to generate multiple,
163 similar pmie rules from a single predicate. This is most useful for
164 rule definitions wishing to use the "some_inst" clause in the pmie lan‐
165 guage across multiple hosts. For a rule to use these together, it must
166 be certain that the instance list is the same on all of the monitored
167 hosts. This is rarely true, so the "enumerate" attribute allows us to
168 generate multiple rules, expanded over variables of either type
169 "instlist" or "hostlist". These variables make up the value for the
170 "enumerate" attribute - which is a space-separated list of "instlist"
171 or "hostlist" variable names.
172 Objects can be incorporated into other object definitions using the
174 $identifier$ syntax. See the example later for more insight into how
175 this is useful.
176 When pmieconf is generating the pmie configuration file, it looks at
178 each enabled rule with N enabled actions (where N > 0) and expands the
179 string:
180 // "version" identifier
182 delta = $delta$;
183 "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;
184 The delta, threshold, and action variables are defined globally (using
186 the "global" keyword) for all rules, but can, of course, be changed at
187 the level of an individual rule or rule group.
188
190 The following is an example of a single pmieconf-rules specification,
191 showing a number of different aspects of the language discussed above.
192 The example defines a rule ("memory.exhausted") and a string ("rule").
193 rule memory.exhausted
195 default = "$rule$"
196 predicate =
197 "some_host (
198 ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 &&
199 $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$
200 )"
201 enabled = yes
202 version = 1
203 help =
204 "The system is swapping modified pages out of main memory to the
205 swap partitions, and has been doing this on at least pct of the
206 last 10 evaluations of this rule.
207 There appears to be insufficient main memory to meet the resident
208 demands of the current workload.";
209 string rule
211 default = "Severe demand for real memory"
212 modify = no
213 display = no;
214 Note that for the above rule to be complete, "threshold" and "pct"
216 would also need to be defined - for the full expression of this rule,
217 refer to $PCP_VAR_DIR/config/pmieconf/memory/exhausted.
218
220 $PCP_VAR_DIR/config/pmieconf/*/*
221 generalized system resource monitoring rules
222 $PCP_VAR_DIR/config/pmieconf/config.pmie
223 default super-user settings for system resource monitoring
224 rules
225 $HOME/.pcp/pmie/config.pmie
226 default user settings for system resource monitoring rules
227
229 pmie(1) and pmieconf(1).
230Performance Co-Pilot PCP PMIECONF(5)