ANALYSIS.METRIC_TREE

A metric tree specifying the metrics that should be collected and displayed with this analysis and how they should be displayed. This metric tree is a recursive structure consisting of a Python list of displayed metrics. Each displayed metric consists of a Python 2- or 3-tuple, containing:

• A metric to be displayed (either the query("<query-name>") function, or, if only a label not associated with any metric is desired, a Python string containing that label)

• A Python set of display attributes:

  • "summary" indicating that the metric should be displayed in the Summary window

  • "grid" indicating that the metric should be displayed in the grid panes (Bottom-up and Top-down Tree)

  • "srcasm" indicating that the metric should be displayed (and expanded into its constituent PMU events) in the Source/Assembly pane

  • "collapsed" indicating that the metric should be collapsed by default so that it must be expanded to show its children

• Optionally, a child metric tree specified (just as the top-level metric tree) as a Python list of displayed metrics

The way that this tree is displayed depends on the window/pane:

• In the Summary window, a hierarchical, collapsible tree is displayed. Issues are marked with pink backgrounds and issue text.

• In the grid panes, nested columns are used to reproduce the tree structure. When a column in the grid has nested columns, the column header indicates this: if the parent is expanded, the headers of nested columns are shown underneath the parent header (which spans all its children). If the parent is collapsed, only a single column, containing the parent metric value, is shown. Parent columns can be expanded or collapsed by clicking a 'twistie' icon in the upper right-hand corner of their column header. Issues are marked with pink backgrounds and tooltips.

• In the Source/Assembly pane, nested columns are shown as in the grid pane. However, the computed values of metrics are never shown. Instead, each metric is further expanded to show all events that are directly referenced (that is, given by name in the formula; events only mentioned in queries referenced in the formula are not included.) Only leaf metrics are thus expanded. If a metric has both a formula and nested metrics, then its events are not displayed. Leaf metrics cannot be collapsed.

The following grammar describes the syntax of the metric_tree attribute. Since [] and () are meaningful in Python, { and } is used to indicate grouping in this grammar.

<metric_tree> ::= [ <displayed_metric> {, <displayed_metric> }* ]
<displayed_metric> ::= ( <metric_specifier>, <attribute_list> {, <metric_tree>}? )
<metric_specifier> ::= query("<text>") | "<text>"<attribute_list> ::= set( { <attribute> {, <attribute}* }? )
<attribute> ::= "summary" | "grid" | "srcasm" | "collapsed"