1PMIECONF(4)                Kernel Interfaces Manual                PMIECONF(4)
2
3
4
5
6
7
8
9PMIECONF(4)                Kernel Interfaces Manual                PMIECONF(4)
10
11
12
13
14

NAME

16       pmieconf - generalized pmie rules and customizations
17

DESCRIPTION

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
25       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
33       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
44       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

PMIECONF-PMIE SYNTAX

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
56           // pmieconf-pmie version pmieconf_path
57
58       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
64       The  remainder  of  the  specification consists of one line entries for
65       each of the modified variables.  The syntax for each line is:
66
67           // rule_version rule_name rule_variable = value
68
69       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
74       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

PMIECONF-PMIE EXAMPLE

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
84           // 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
94           // 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
102           // --- END GENERATED SECTION (changes below will be preserved) ---
103
104
105       To see how this all works, you can generate this file as follows:
106
107           # 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
115       Then verify that the generated file is a valid pmie configuration  file
116       using:
117
118           # pmie -C /tmp/pmieconf.out
119
120       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

PMIECONF-RULES SYNTAX

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
130       The generic specification of a pmieconf-rules object is thus:
131
132           type identifier [ attribute = value ]* ;
133
134       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
141       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
147       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
151       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
162       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
173       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
177       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
181           // "version" identifier
182           delta = $delta$;
183           "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;
184
185       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

PMIECONF-RULES EXAMPLE

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
194           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
210           string  rule
211                   default = "Severe demand for real memory"
212                   modify  = no
213                   display = no;
214
215       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

FILES

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

SEE ALSO

229       pmie(1) and pmieconf(1).
230
231
232
233Performance Co-Pilot                  SGI                          PMIECONF(4)
Impressum