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, 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 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 settings 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 discussed 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
customizations 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, followed 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).
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
