PerfReport 1

Complete: 5

WARNING

PerfReport version 1 is deprecated. Use it exclusively if you are forced to analyse profiles generated with the standard unpatched version of Callgrind. In any other case please use PerfReport 2. Should you be just about to start profiling, consider using Callgrind FCE or IgProf.



Invoking the tool

To invoke the tool, please type

perfreport -i (PROFILE) -d (XMLCONFIG) -o (OUTDIR) 

where

  • (PROFILE) is the file containing your Callgrind (or edmEventSize) profile,
  • (XMLCONFIG) is an XML file describing the contents and the looks of the report to produce (see below) and
  • (OUTDIR) is the path to an empty directory where you want the output to go.

Apart from the mandatory -i, -d and -o, you can use any of the following optional switches:

  • -e use this switch if your profile was generated by the edmEventSize tool instead of Callgrind
  • -c use this switch in order to specify what cost type in the profile you wish to be used. The abbreviation (see below) of the desired cost type must follow the -c switch. If you do not use -c, the first cost type in the profile is used by default.

Authoring XML report descriptions

1. Quickstart using examples

In case you do not want to spend a lot of time reading the documentation, start from one of the following typical examples. You can run the report generation utility choosing an XML description that suits your needs from the list below. This will suffice in many cases. If you happen not to find what you need, read the sections for expert users.

The sample outputs have been created using the data callgrind.out.relval.070219.

You can download the XML descriptions or access them directly via AFS. They reside in the path

     /afs/cern.ch/user/m/moserro/public/html/doc/xmlexamples/

1.1 How to produce standard reports

XML description of output produced sample output
allstandard.xml A standard report containing the most common elements: an overall view, an aggregation by library view, an aggregation by first namespace view, an aggregation by full namespace (=class) view, inclusive of graphics and function info pages. The template collapser is activated by default. Turn it off by editing the respective line. overall.html
overall.xml Same as above, but generate only a the overall view. overall.html
bylibrary.xml Same as above, but generate only the aggregation by library. liblist.html
byclass.xml Same as above, but generate only the aggregation by class / full namespace. clslist.html
byfirstnamespace.xml Same as above, but generate only the aggregation by first namespace. nmslist.html
edmeventsize.xml This XML description is suitable for generating a standard report from an edmEventSize profile.
The sample output for this XML example has been produced from the profile edmeventsize.profile.
objects_pp.html

1.2 How to use custom filtering and aggregation

XML description of output produced sample output
restriction.xml Use this example if you do not want to look at the entire data, but just at a subset of it which is in your field of interest. The example restricts the input data to everything that comes from GEANT4 libraries. The functions within this range are grouped and aggregated by class. Edit the file and change the filter values if you want to restrict to something else. clslist.html
customaggregation.xml Edit this example report description if you want to create an aggregation of your own. Two groups are predefined: every function in the G4Navigator and every function coming from libG4graphics_reps.so. myreport.html
regexpalphabet.xml In this example, functions are aggregated by the first letter of their name. This may not be of practical use, but it demonstrates how to use regular expressions in filter descriptions. The example also demonstrates how to incorporate boolean connective filters. myreport.html

1.3 Tool validation views

XML description of output produced sample output
validation.xml This file can be used for validation of the tool: it prints out a list containing ALL the functions, with no display limit. No graphics or function info pages. The template collapser is off. validation.html
validation_tcollapse.xml Same as above, but the template collapser is turned on. Useful to test the template collapser. validation.html
validation_intellinames.xml Same as above, but the function names are displayed using intelligentname naming discipline. Useful for testing the rules that describe intelligent names. validation.html

2. Top level schema and the <report> element

An XML report description has the following layout.

<report>
 ...(options) ...
 <reportsection>
  ...
 </reportsection>
 <reportsection>
  ...
 </reportsection>

 ...
</report>

Every report section defines a specific view of the data represented in the report and has its own entry page together with, possibly, subpages linked from there.

3. The <reportsection> element

The reportsection element represents a main page within the report, consisting of a table of (possibly aggregated) report items and, optionally, graphical representations of that data. Subpages which give detailed information about the items listed may be attached to such a page.

All child elements of a reportsection are optional and can be omitted. The simplest meaningful XML report description therefore is

<report>
 <reportsection>
 </reportsection>
</report>

It will produce a standard report with default options which shows the top 20 functions overall in a table and a pie chart.

Optionally however, you can add any of the following subtags:

subelement purpose
maintitle Specifies the main heading for the entry page of the reportsection. Try to meaningfully describe here what the page shows.
subtitle Specifies the subtitle for the entry page of the reportsection. Use to further describe what is the content of the page.
displayitems Put an integer in this subtag which determines how many entries should be at most printed in the list on this page and on its subpages. If any of the lists exceeds this number, the remainder of the report items is summarized in an {others} entry. If the reportsection lacks this tag, the default value is used, which is 20. Set the value to zero if you wish to have no limit at all.
outfile Specifies the filename for the entry page of the reportsection. Provide only the filename and NO path; the utility will concatenate the name with the output path specified at invocation time.
producepiecharts Put the value yes in this tag to activate production of pie charts on this page and its subpages. Put no to deactivate it. Any other value or a missing tag is interpreted as no.
producelegends Put the value yes in this tag to activate production of legends for the pie charts on this page and its subpages. Put no to deactivate it. Any other value or a missing tag is interpreted as no. If you have deactivated production of charts on this page, this value is ignored.
produceinfopages Put the value yes in this tag to activate production of function info pages (showing callers and callees) for every function appearing on this page and its subpages. Put no to deactivate it. Any other value or a missing tag is interpreted as no.
data Use this tag to specify what data should be used in this section of the report. The description uses filters and is described here. If you omit the tag, all loaded data is represented.
aggregation Use this tag to specify in what way data should be aggregated in this report section. The description uses templates or custom aggregates and is described here. If you omit the tag, single cost elements (functions) are shown in the top-level list without appying aggregation.
collapsetemplates Put yes into this element to globally activate the template collapser in this section and its subsections. Any value other than yes or a missing tag will be interpreted as no.

The way the template collapser works might depend on the kind of aggregation you do at the same time. If you choose standard aggregation by class or by namespace, the template collapser is applied to the data before aggregation, such that multiple instances of the same templated class will be collapsed. In case you choose aggregation by library, the data is first aggregated and only then collapsed. This ensures that the costs in different instances of the same templated function or class will be attributed to their respective libraries if they reside in different libraries. In case of custom aggregations, the tool chooses the discipline for the by-library case as well, as it cannot make assumptions about the intention of your aggregation.

Whenever the utility builds a table within this report section, it will display a set of columns, according to which of the following options you activate:

subelement purpose
showabsoluteselfcost Shows the absolute self cost of every function. This column is visible by default. Put no inside this tag to deactivate.

Note: in case of edmEventSize profiles, this refers to the plain object size.

showrelativeselfcost Shows the relative self cost (percentage) of every function. This column is visible by default. Put no inside this tag to deactivate.

Note: in case of edmEventSize profiles, this refers to the relative plain object size.

showabsoluteinclusivecost Shows the absolute inclusive cost (which means 'inclusive of cost incurred by calles') of every function. This column is invisible by default. Put yes inside this tag to activate.

Note (1): Inclusive cost figures are only ESTIMATES. Depending on the topology of the call graph, it is difficult or impossible to compute (or even define!) accurate inclusive metrics. In aggregation lists, this column is never shown because, as of now, it is impossible to compute those metrics from standard Callgrind profiles. The tool overrides your setting in these cases.

Note (2): in case of edmEventSize profiles, this refers to the compressed object size.

showcallcount Shows the number of times the function was called. This column is invisible by default. Put yes inside this tag to activate.
showchartcolor Shows the number and the color that are used to represent the reportitem in any chart or legend. This column is visible by default if graphics production is activated. Otherwise, the default is invisible. Put yes or no to override.
showfunctionname Shows the number and the color that are used to represent the reportitem in any chart or legend. This column is visible by default. Put no if (for some strange reason ;)) you want to hide it.

If you activate the showfunctionname option, then you can also configure the way in which function names are displayed. To this end, add a <namingdiscipline> element to the reportsection and put one of the following values inside:

value meaning
functionname Displays only the name of the function without namespace or type information.
functionnamewithsignature Displays the function name inclusive of return type and argument list.
fullfunctionname Displays a fully qualified function name including all levels of preceding namespaces. This is the default.
fullfunctionnamewithsignature Displays a fully qualified function name including all levels of preceding namespaces plus return type and argument list.
intelligentname Tries to guess what is the most 'useful' information. This is: displays the top-level namespace, then, if necessary, dots (...), then the lowest-level namespace (which is most likely the class name), then the function names. Removes all templating information and signature (templates are replaced by dots if the template collapser is deactivated). However, if the given function is the definition of a C++ operator then signature and return type information is displayed.

Help with improving on these rules and send us your suggestions!

If you want to control the ordering used to sort the items in the list, add a <sortby> element to the reportsection and put one of the following values inside:

value meaning
selfcost Sorts by descending self cost. This is the default.

Note: in case of edmEventSize profiles, this refers to the plain object size.

inclusivecost Sorts by descending inclusive cost.

Note: in case of edmEventSize profiles, this refers to the compressed object size.

fullfunctionname Sorts by the full function name (inclusive of namespace/class information), alphabetically.
functionname Sorts by the function name (without namespace), alphabetically.

Please be aware that the sorting takes place before truncation of the list. So if you set the displayitems property to 20 and the sorting discipline to functionname, you will end up with a list containing the first 20 functions w.r.t. alphabetical ordering.

If you are creating a report with many subsections or with subsections that are logically related, it usually makes sense to add links to the pages that connect them to one another. To this end, the tool will produce a header on every page where all those links are collected and hierarchically grouped. For this feature to work you will have to provide information on where to position the current reportsection in the hierarchy. Use the following tags to do this:

subelement purpose
includenavheader Put yes inside this element to place the header on the page that displays the current reportsection. It will be possible to navigate among all reportsections that include the header. Those which don't are not reachable via links and constitute separate entry points into the report. The default is no. You can omit the tag.
navlevel1caption Provide a short name for the highest-level category the current reportsection belongs to. To be displayed in the leading row of the header.
navlevel2caption Provide a short name for the mid-level category the current reportsection belongs to. To be displayed in the middle row of the header.
navlevel3caption Provide a short name for the the current reportsection. To be displayed in the lowest row of the header.

4. Describing subsets of data using a <data> element

There are two ways of specifying a set of data. Either use the block

<data>
 <all />
</data>

to specify that you want to use all data available. Or, in case you want to remove certain report items, you can pass the data through a filter. To do so, use the following block:

<data>
 <filtered>
  <data>
   ...
  </data>
  <filter>

   ...
  </filter>
 </filtered>
</data>

Inside the inner <data> element, describe what data you want to pass through the filter. The inner <data>-tag follows the same rules as the outer one, so either put the block shown above to start from all and then filter, or use a block prefiltered and then attach another filter. This way, you can build filter chains of arbitrary length.

The innermost (or first) filter in the chain will be used for correction of inclusive values and caller/callee lists. This means that if you specify a filter that rejects all std::* calls as the innermost filter, the inclusive cost of every function calling something in std::* will decrease by the cost of those calls and will behave just as if those calls would not have been made. If you filter out std::* in an outer filter, all std::* will vanish from the top-level lists but not from caller/callee-lists and will still contribute to the inclusives of their callers.

See the following section to understand how to describe a filter using the <filter> element.

5. Describing a data filter using a <filter> element

The filter-tag is built in the follwing manner:

<filter>
 <type> ... </type>
 ...
</filter>

Depending on the type of filter you select inside type, there are different options you can select below.

The following filters are available:

filter purpose and available options
exactmatch The filter accepts every report item (function) for which a given property matches a given string value. Specify the propery you want to use inside a property-tag following the type. Specify the value you want to match it to inside a value-tag following the property. Be careful to use &gr; and < inside value tags if you want to use > or < signs inside your string constants. The list of properties available for the property tag can be found below.
regexpmatch This filter accepts every report item (function) for which a given property matches a given pattern which is interpreted as an EXTENDED POSIX regular expression (explanations can be found here). Specify the propery you want to use inside a property-tag following the type. Specify the pattern you want to match it against inside a pattern-tag following the property. Be careful to use &gr; and < inside pattern tags if you want to use > or < signs inside your regular expression. The list of properties available for the property tag can be found below.
and The boolean connective and-filter accepts every report item (function) that is accepted by two given filters. For example, use
<filter>
<type>and</type>
<firstfilter>
<filter>
...
</filter>
</firstfilter>
<secondfilter>
<filter>
...
</filter>
</secondfilter>
</filter>
Inside the firstfilter and secondfilter-blocks you can use filter-blocks to describe the operand filters recursively.
or The or-filter accepts if one of the two specified operand filters accepts. The syntax is analogous to the and-case.
not Write
<filter>
<type>not</type>
<operandfilter>
<filter>
...
</filter>
</operandfilter>
</filter>
to build a filter through which a report item passes if it does not pass the given operand filter.
cancelcalls The cancelcalls-filter is designed to serve the specific purpose of cancelling out a narrowly defined set of calls which should not be there in the profile. The syntax to define a cancelcalls filter is as follows:
<filter>
<type>cancelcalls</type>
<from>
<filter>
...
</filter>
</from>
<to>
<filter>
...
</filter>
</to>
</filter>
Within the from- and to-blocks you use filter-blocks to describe two sets of functions, the FROM and the TO set. In the final report, all calls going from functions within FROM to functions within TO will be removed and the respective inclusive metrics adjusted. Cancelcall-filters are effective only within the innermost filter block of a filter chain. Read the section about the <data> tag to understand why.

For the first two filter types, the following proterties can be chosen inside a property-tag:

property meaning
library The library where the function is stored. An appropriate value could for example be "mylibrary.so".
libraryfilename The library inclusive of its path where the function is stored. An appropriate value could for example be "/usr/lib/mylibrary.so".
firstnamespace The name of the namespace the function belongs to. Only the first level of nesting is used, so if the function is called A::B::C::f(), then the value of firstnamespace is A.
fullnamepsace The full name of the namespace the function belongs to. All levels of nesting are used, so if the function is called A::B::C::f(), then the value of fullnamespace is A::B::C.
functionname The name of the function. Namespace and class information, return types, function signature, etc. are all removed. For instance, if the function is called void A::B::C::f(int x), then the value of functionname is f.
fullfunctionname The full name of the function, inclusive of namespace(s) and class. Return types, function signature, etc. are removed. For instance, if the function is called void A::B::C::f(int x), then the value of fullfunctionname is A::B::C::f.

6. Specifying the aggregation mode using an <aggregation> element

You may want to see the total cost of an entire collection of functions. To calculate it, use and aggregation tag. The aggregation mode is described using a block of the following type:

<aggregation>
 <type> ... </type>
 ...
</aggregation>

Choose the type of aggregation within the type element. Depending on what type you select, the aggregation tag should or should not contain further elements. The following types are available:

type purpose and options
bylibrary Functions are aggregated by library. No options when using this type.
byfirstnamespace Functions are aggregated by first namespace (see above). No options when using this type.
byfullnamespace Functions are aggregated by full namespace, which is typically the class (see above). No options when using this type.
custom Perform a user-defined aggregation. Read on to see how to describe your aggregation.

In case you use the aggregation type custom then you have to define yourself what collections of functions you want to group together. This description uses filters as already described. Your custom aggregation block will look somehow as follows:

<aggregation>
 <type>custom</type>

 <aggregate>
  <name>...</name>
  <filter>
   ...
  </filter>
 </aggregate>

 <aggregate>
  <name>...</name>
  <filter>
   ...
  </filter>
 </aggregate>

 <aggregate>
  <name>...</name>
  <filter>
   ...
  </filter>
 </aggregate>

 ...
</aggregation>

Every aggregate-block will create an aggregated report item in the top-level view. The content of the name-element will be displayed as the title of that element. The filter-element determines which functions should go into this collection; it uses the same syntax as filters in any other context. The utility will pass the entirety of the functions through the filter you defined for the first aggregation element. All functions accepted by that filter are summarized under the given title and then removed from the global list. The second filter will therefore be applied to an already restricted list. You are encouraged to write your filters in a way that excludes non-empty intersections. If you do not, every function will still be reported only once and will enter into the first aggregation item that accepts it. This is to ensure that the aggregated list sums up to the overall total cost as expected.

Review status

Reviewer/Editor and Date (copy from screen) Comments
JennyWilliams - 17 Aug 2007 moved deprecated perfreport v1 documetation to separate page

Responsible: VincenzoInnocente
Last reviewed by: RobinMoser - 22 Mar 2007

Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r2 - 2007-10-02 - JennyWilliams



 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback