HP Caliper Advisor Rule Writer Guide

of the performance problem it looks for, and any limitations or special conditions
on the rule. Other relevant information (such as a reference to a document) can
also be included.
2
Function declaration.
All rule functions must be named rule_*, where * is replaced by the name of the
rule. The name is case-sensitive and must be unique among all rule files. You
should use a naming convention that keeps the names unique.
The function takes only one argument: the object to be analyzed. Any function not
named rule_* can be called as a helper function by other rules, but is not invoked
directly by the Advisor.
3
Exception handling.
Any exception raised by a rule function is treated as a fatal error. To prevent this
from happening, the rule code should be within a “try” block and exceptions dealt
with. Note that the accessor functions (get_xxx()) and the advice() function
will never raise an exception.
4
Testing rule limitations.
Every rule has some limitations as to the type of object, processor type and/or
run-time system it can deal with. A well-written rule will test for these conditions
early and return if they are not met. At a minimum, rules should test that the object
type is EXECUTABLE_OBJECT. That is the only type available in the current
release of the Advisor, but testing for it allows rules to work correctly in the future
when other types are available.
The advice that this particular rule can produce is only applicable to HP-UX, so
testing for that condition avoids generating unusable (although valid) advice on
Linux.
5
Retrieving performance data.
This is where a rule makes accessor function calls to retrieve any available data
for the performance area being analyzed. Special care should be taken to deal with
processor differences (especially with PMU-based data) and the different sources
of data that might be available. For example, this particular rule needs to determine
the percentage of ITLB misses. This data can be generated by a cpu measurement
run using the -m tlb or -m overview option, by an itlb measurement run, or
(less likely) a customized ecount measurement run. Unfortunately, different PMU
events are available based on the processor’s PMU type, and a rule must deal with
those differences. Anything that is not obvious about the code should be explained
with comments.
6
Analysis and advice generation.
The rule tests the retrieved data to determine if the performance problem might
exist. If it does, the rule generates the appropriate advice. The rule might make
additional accessor function calls to retrieve descriptive information to include in
What Makes a Good Rule? 59