1PMIECONF(5)                   File Formats Manual                  PMIECONF(5)
2
3
4

NAME

6       pmieconf - generalized pmie rules and customizations
7

DESCRIPTION

9       The  pmieconf file formats are used by the pmieconf(1) tool as a way to
10       generalize pmie(1) rule sets such that they can  be  easily  configured
11       for  different  systems and different environments.  There are two com‐
12       pletely different (although closely  related)  file  formats  discussed
13       here, namely ``pmieconf-rules'' and ``pmieconf-pmie''.
14
15       The  directory  $PCP_VAR_DIR/config/pmieconf contains information about
16       all the default system pmie generalized rules and variables,  including
17       default  values  for  all  variables.  These files are in the pmieconf-
18       rules format.  Although new pmieconf-rules  files  can  be  added,  the
19       files  in  this  directory  should  never be changed.  Instead, use the
20       pmieconf utility to change variable values in  the  pmie  configuration
21       file.
22
23       The  pmieconf-pmie  format  allows  site specific customizations of the
24       rules contained in pmieconf-rules files and their associated variables.
25       The  pmieconf-pmie  format  is  generated by pmieconf and should not be
26       edited by hand.  This generated file is in the pmie format,  with  some
27       additional  information  held  at  the  head  of  the  file - thus, the
28       pmieconf-pmie format is a superset of the pmie file format (extended to
29       hold  customizations  to the generalized rules, but also containing the
30       actual performance rules for pmie to evaluate) which can also be parsed
31       by  pmie (all extensions are hidden within comments, and are thus mean‐
32       ingless to pmie itself).
33
34       The file $PCP_VAR_DIR/config/pmieconf/config.pmie contains local system
35       settings for pmieconf configurable variables.  The variable settings in
36       this file replace the default  values  specified  in  $PCP_VAR_DIR/con‐
37       fig/pmieconf/*/*.
38

PMIECONF-PMIE SYNTAX

40       All rule customization lines in a valid pmieconf-pmie specification are
41       prefixed by ``//'' and are located at the  head  of  the  file  -  this
42       allows  files  containing  a pmieconf-pmie specification to be success‐
43       fully parsed by pmie.  A pmieconf-pmie must always have the first  line
44       in the form:
45
46           // pmieconf-pmie version pmieconf_path
47
48       The  version specifies which version of the pmieconf-pmie syntax should
49       be used to parse this file.  Currently the only supported version is 1.
50       The  pmieconf_path specifies the path to the pmieconf-rules files which
51       were used, by pmieconf, to generate this file.  This  is  discussed  in
52       the pmieconf(1) man page (see the -r option).
53
54       The  remainder  of  the  specification consists of one line entries for
55       each of the modified variables.  The syntax for each line is:
56
57           // rule_version rule_name rule_variable = value
58
59       The rule_version and rule_name are used to identify the rule with which
60       to  associate  the customization.  These are followed by the rule_vari‐
61       able name (i.e. the variable of rule rule_name which has been  changed)
62       for which the new value is to be used.
63
64       A  pmieconf-pmie specification must be terminated with the ``end'' key‐
65       word.  This is used by pmieconf to distinguish where the customizations
66       ends, and the actual pmie rule component begins.
67

PMIECONF-PMIE EXAMPLE

69       The  following  example is a valid pmieconf-pmie format file, as gener‐
70       ated by pmieconf.  In order to make changes by hand which are preserved
71       by  pmieconf,  see the comments contained in the generated file (below)
72       as to where such changes should be made.
73
74           // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf
75           // 1 memory.exhausted delta = "4 minutes"
76           // 1 memory.exhausted enabled = yes
77           // 1 memory.exhausted pcplog_action = yes
78           // end
79           //
80           // --- START GENERATED SECTION (do not change this section) ---
81           //     generated by pmieconf on:  [DATESTAMP]
82           //
83
84           // 1 memory.exhausted
85           delta = 4 minutes;
86           some_host (
87               ( avg_sample (swap.pagesout @0..9 ) ) > 0 &&
88               30 %_sample swap.pagesout >= 5
89           ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \
90                   " %vpgsout/s@%h";
91
92           // --- END GENERATED SECTION (changes below will be preserved) ---
93
94
95       To see how this all works, you can generate this file as follows:
96
97           # cat - | pmieconf -f /tmp/pmieconf.out \
98               -r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global
99           modify memory.exhausted delta "4 minutes"
100           modify memory.exhausted enabled yes
101           modify memory.exhausted pcplog_action yes
102           ^D
103           #
104
105       Then verify that the generated file is a valid pmie configuration  file
106       using:
107
108           # pmie -C /tmp/pmieconf.out
109
110       This parses the file, and then exits after reporting any syntax errors.
111       Now replace -C with -v (above), and watch pmie do its work!
112

PMIECONF-RULES SYNTAX

114       A pmieconf-rules specification consists of a number  of  separate  data
115       objects  which together form a complete rule specification (note that a
116       specification may span multiple files  and  even  multiple  subdirecto‐
117       ries).   Each  object  must  have an identifier string and a data type,
118       followed by an (optional) list of attributes.
119
120       The generic specification of a pmieconf-rules object is thus:
121
122           type identifier [ attribute = value ]* ;
123
124       The set of valid types is: "rule" (rule  definition),  "string"  (arbi‐
125       trary,  double-quote enclosed string), "double", "integer", "unsigned",
126       "percent" (real number between 0 and 100), "hostlist" (space  separated
127       list  of  host  names),  "instlist"  (space  separated  list  of metric
128       instance names), and  the  four  pmie  action  types,  namely  "print",
129       "shell", "alarm", and "syslog".
130
131       Rule  names  use the ``.'' character to introduce the concept of a rule
132       group, e.g. "memory.exhausted" associates this rule with  the  "memory"
133       group.   pmieconf  can  operate  at  either the level of rule groups or
134       individual rules.  The group name "global" is reserved and may  not  be
135       used with any rule.
136
137       Usually  when  an  object  is created it is associated with the current
138       rule.  However, if an object's name is preceded by the  reserved  group
139       name "global", then that object is visible to all rules.
140
141       The  set  of  valid  attributes is: "help" (descriptive text about this
142       object), "modify" (value is yes/no, flags whether pmieconf should allow
143       changes), "enabled" (value is yes/no, flags whether this is on or off -
144       only meaningful for rules  and  actions),  "display"  (yes/no  -  flags
145       whether  pmieconf should show this object), "default" (value determined
146       by type, and is the default value for this  object),  and  specific  to
147       objects  of  rule  type are the "version", "predicate", and "enumerate"
148       attributes.  "version" and  "predicate"  are  fairly  self  explanatory
149       ("predicate" must equate to a valid pmie rule when expanded), but "enu‐
150       merate" requires further discussion.
151
152       The "enumerate" clause is useful when you wish  to  generate  multiple,
153       similar  pmie  rules  from a single predicate.  This is most useful for
154       rule definitions wishing to use the "some_inst" clause in the pmie lan‐
155       guage across multiple hosts.  For a rule to use these together, it must
156       be certain that the instance list is the same on all of  the  monitored
157       hosts.   This is rarely true, so the "enumerate" attribute allows us to
158       generate  multiple  rules,  expanded  over  variables  of  either  type
159       "instlist"  or  "hostlist".   These variables make up the value for the
160       "enumerate" attribute - which is a space-separated list  of  "instlist"
161       or "hostlist" variable names.
162
163       Objects  can  be  incorporated  into other object definitions using the
164       $identifier$ syntax.  See the example later for more insight  into  how
165       this is useful.
166
167       When  pmieconf  is  generating the pmie configuration file, it looks at
168       each enabled rule with N enabled actions (where N > 0) and expands  the
169       string:
170
171           // "version" identifier
172           delta = $delta$;
173           "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;
174
175       The  delta, threshold, and action variables are defined globally (using
176       the "global" keyword) for all rules, but can, of course, be changed  at
177       the level of an individual rule or rule group.
178

PMIECONF-RULES EXAMPLE

180       The  following  is an example of a single pmieconf-rules specification,
181       showing a number of different aspects of the language discussed  above.
182       The example defines a rule ("memory.exhausted") and a string ("rule").
183
184           rule    memory.exhausted
185                   default = "$rule$"
186                   predicate =
187           "some_host (
188               ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 &&
189               $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$
190           )"
191                   enabled = yes
192                   version = 1
193                   help    =
194           "The system is swapping modified pages out of main memory to the
195           swap partitions, and has been doing this on at least pct of the
196           last 10 evaluations of this rule.
197           There appears to be insufficient main memory to meet the resident
198           demands of the current workload.";
199
200           string  rule
201                   default = "Severe demand for real memory"
202                   modify  = no
203                   display = no;
204
205       Note  that  for  the  above  rule to be complete, "threshold" and "pct"
206       would also need to be defined - for the full expression of  this  rule,
207       refer to $PCP_VAR_DIR/config/pmieconf/memory/exhausted.
208

FILES

210       $PCP_VAR_DIR/config/pmieconf/*/*
211                 generalized system resource monitoring rules
212       $PCP_VAR_DIR/config/pmieconf/config.pmie
213                 default  super-user  settings  for system resource monitoring
214                 rules
215       $HOME/.pcp/pmie/config.pmie
216                 default user settings for system resource monitoring rules
217

SEE ALSO

219       pmie(1) and pmieconf(1).
220
221
222
223Performance Co-Pilot                  PCP                          PMIECONF(5)
Impressum