Filtering Data

The Performance Analyzer offers several ways to filter data so you can focus on areas of interest in your program. When you filter, you specify criteria for the data you want to view. When the filter is applied, the data that does not meet the criteria is removed from view in all the Analyzer tabs that support filtering.

When you first open experiments in the Performance Analyzer, you see data for all functions in all loaded experiments, and for all threads and CPUs for each experiment, and for the complete time period covered by the experiment.

You can filter by the following:

• Experiments - select which of the currently loaded experiments whose metrics you want to see

• Threads - select the data collected from specific thread IDs

• CPUs - select the data collected from specific CPU IDs

• Samples - select the data collected at particular sample points

• Call stacks - select the data collected from call stacks that include a particular function

• Call tree branches - select the data collected from call stacks from a particular branch of a call tree

• Time range - select the data collected during a particular time range

• Labels - select the data specified by a label that identifies a particular period of time

You can filter from multiple locations:

• In data tabs such as Functions, Callers-Callees, and Timeline, you can select a predefined filter from a popup menu by right-clicking on data such as a function name in the tab. The filters are called context filters.

• Using the Experiments and General tabs of the Manage Filters dialog box, you can select experiments, threads, CPUs, or samples whose data you want to display.

• Using the Custom tab of the Manage Filters dialog box, you can edit filter expressions to create custom filters to precisely define the data to be displayed.

When you set a filter, the data is filtered in all the Analyzer tabs. You can combine filters to display metrics from highly specific areas of your program's run.

Using Context Filters

Context filters are context-specific filters that are available in several data tabs in the Performance Analyzer. You access them by right-clicking with the mouse or by pressing Shift-F10 on the keyboard. When you select a context filter, the data is immediately filtered.

In general, you use context filters by selecting one or more items in the tab that you want to focus on, right-clicking the mouse, and selecting the appropriate filter. For most data tabs the filters enable you to include or not include the data that meets the criteria named in the filter. This enables you to use the filters to either focus on data from a particular area of your program, or exclude data from a particular area.

Some ways you can use context filters include:

• Add multiple filters to narrow down the data. The filters are combined in a logical AND relationship, which requires the data to match all of the filters.

• Add a filter in one tab and then view the filtered data in another tab. For example, in the Call Tree tab you can find the hottest branch, then select “Add Filter: Include only stacks containing the selected branch”, and then go to the Functions tab to view metrics for the functions called in that code branch.

• Add multiple filters from multiple tabs to create a very specific set of data.

• Use context filters as a basis for creating custom filters. See Using Custom Filters.

Managing Filters

You can use the Manage Filters dialog box to perform simple filtering on experiments, threads, CPUs, and samples. This filtering can be used together with context filters.

The Manage Filters dialog box can be accessed in multiple ways:

• Choose View ⇒ Manage Filters

• Click the Manage Filters button in the toolbar

• Right-click in a data tab such as the Functions tab, and select Manage Filters from the context menu

• Right-click in the Experiments tab and select Filter Experiments

The Manage Filters dialog box enables you to do general filtering to select data to display from particular experiments, sample points, threads, and CPUs. You use the Experiments tab and the General tab together to specify the items whose data you want to display. The selections made in the Experiments and General tabs are combined for filtering using a logical AND (the && operator). Data must match all the selections made in these tabs to be included in the data tabs.

The Analyzer help includes instructions for using the Manage Filters dialog box.

The dialog box also provides a Custom tab that you can use to customize filters. See the following section for more information.

Using Custom Filters

The Custom tab enables you to type in your own filter expressions or edit previously applied filters to create custom filters. The filters in the Custom tab are separate from the filters applied through the Experiments and General tabs of the Manage Filters dialog box.

When you select context filters in Performance Analyzer data tabs, filter expressions are generated and are immediately applied to filter the data. The generated filter expressions are also added to a text box in the Custom tab, where you can use them as a beginning point for creating custom filters.

You can edit the filters, and use the arrow buttons above the Filter Specification panel to undo and redo your edits. You can also press Ctrl-Z to undo and Shift-Ctrl-Z to redo as you would in a text editor.

Filter expressions use standard C relational operators (==, >=, &&, ||, and so on) along with keywords that are specific to the experiment. To see the keywords that you can use in an experiment that is open in the Analyzer, click the Show Keywords button in the Custom tab.

The filter expression syntax is the same as that used for filtering with er_print. See Expression Grammar for information about filter expressions.

The edited filters do not affect the data tabs until you click OK or Apply. If you click Apply, the Custom tab remains open. If you select context filters in the Analyzer data tabs, you can see the filter expressions generated by your selections as they are added to the Filter Specification text box. Each new filter is placed on a new line beginning with &&, the logical "and" operator. Experiment data must match the first filter and the second filter and the third filter, and so on, in order to be displayed. You can change && to || if you want data to match the first filter or the second filter, for example.

You can also use the Custom tab to filter using labels as explained in the following section.

Using Labels for Filtering

Labels are names you can assign to a portion of an experiment. Using the er_label command, you can assign a label name to a period of time in an experiment and the label persists with the experiment. You can use the label to filter the experiment data with the er_print command or the Performance Analyzer to include or exclude the data collected during the labelled time period.

See Labeling Experiments for information about how to use the er_label utility to create labels.

In the Performance Analyzer you can filter data from the labeled time period in the Custom tab of the Manage Filters dialog box. Type the label name in the Filter Specification panel and click Apply to filter the data specified by the label. You do not need to use any numerical comparison because the label acts as a nickname for a filter expression that uses a numerical comparison with the TSTAMP keyword. You can combine the label with other filters in the Custom tab by adding it on a separate line preceded by &&.

You can see if there are labels assigned to an experiment that is open in the Performance Analyzer by clicking the Show Keywords button in the Custom tab. You can also use the er_print -describe command to see the same information. Labels are listed first in the display and include the actual filter expression with the TSTAMP keyword that is implemented by the label.

After applying a label filter, you can click the Timeline tab to see data is removed in the intervals that were defined by the label. The data is also filtered in other tabs that support filtering.