HP Caliper Advisor Rule Writer Guide

the text of the advice message. The computation of the index value takes into

account the frequency of the performance problem and its cost.

Exception handling.

The simplest handling is to ignore the exception (“pass”), but more sophisticated

rules can include error recovery. Note that the accessor functions (get_xxx())

and the advice() function will never raise an exception.

Writing Advice Text

Here are some suggestions for writing text:

• Each rule should produce a single piece of advice focused on a specific performance

problem area. A rule function that makes more than one advice() call is a

candidate to be split into multiple rules.

• Advice should be as explicit as possible. For example, it is more useful to say:

Function xyz is taking 23.9% of the CPU cycles.

than:

Examine the Caliper fprof report to determine which functions

are taking the most CPU time.

For another example, it is more useful to say:

Try adding the +O3 option to the compile command.

than:

Try one of the higher optimization options.

The best advice directs the user to do something to improve the application’s

performance. The next best advice suggests further measurement runs to explore

a potential performance problem.

Advice text should explain what is going on, what it means, and what to do next

clearly, but without getting too wordy. The user should not have to refer to a man

page or a reference manual to take the next step.

• A rule function should try to determine if the advice it is about to give has already

been followed and if so, not print it. For example, branch misprediction data might

suggest that feedback-based optimization could help performance. The rule function

could query the application’s compilation options to verify that the option had

not been used before calling advice() and suggesting it.

• It is possible to give differently worded advice, particularly when suggesting an

HP Caliper measurement run, when the GUI is being used. To do so, test the

predefined global variable IS_GUI_REPORT. For example:

if IS_GUI_REPORT:

advice_text = "To get more advice on hot functions, " \

"make a 'CPU cycles (flat profile)' collection run."

else:

60 Writing Rules for the HP Caliper Advisor