Please enable JavaScript to view this site.

Performance Validator Help

 

The Statistics tab displays performance data about each function called by your program.

 

interactiveRead on, or click a part of the image below to jump straight to the help for that area.

 

statistics-tab

 

As with many of the tab views, the display is split into two resizable panes.

 

The table of statistics on the left has extensive performance data

 

The table's popup menu provides plenty of options to filter data or to examine more detail
 

The right side shows the source code view for any function selected on the left

 

 

The statistics view

 

Performance data is shown for every function that has been hooked.

 

The default ordering of functions is by directory first, and then by the files in those directories.

 

The data can be otherwise sorted by any column and you can change the frequency with which the data is updated.

 

The amount of information displayed can be controlled by adding or removing columns or by filtering for specific areas of interest.

 

Double clicking any item will display the function on the Relations tab.

 

 

What data is available?

 

The Statistics view can show a large amount of performance related data, although not all of it is displayed by default.

 

The following table list all the available columns of data.

 

Attribute

Description

Shown by default

Class

class name

No

Method

method name (or function name if no class)

No

Class::Method

class::method name (or function name if no class)

Yes

Address

function address

Yes if sampling

Num Children

number of child functions of a function

No

Av Func

Av Func %

average time a function takes to execute (excludes child functions)

No

Av Total

Av Total %

average total time a function takes to execute, including its children

No

Call Count

Call Count %

number of times the function is called

Yes

Function

Function %

the time a function takes to execute (excludes child functions)

Yes

Children

Children %

the time a function's child functions take to execute

Yes

Total

Total %

the time a function and its child functions take to execute

Yes

Longest

Longest %

the longest time a function and its child functions take to execute


Shortest

Shortest %

the shortest time a function and its child functions take to execute


Sample Count

Sample Count %

the number of times a function is found in the sampled data

Yes

Module

name of the module containing the function

Yes

Filename

name of the file containing the function

Yes

 

Items in green are not available in Sampling data collection mode as the yellow Sample Count columns are substituted instead.

 

Percentage values are relative to the total run time or total number of calls made to all functions.

 

seeAlsoYou may not need all this information - see the section on changing which columns are displayed.

 

 

Percentage bars

 

All the cells in the table that show numerical data have a percentage bar indicating one of the following:

 

the function's value relative to the maximum value in the column

 

e.g. Call Count in the example below
 

the function's percentage contribution to the total

 

e.g. Call Count %, or Function time, below

 

statistics-highlighted-cells

 

 

Window orientation

 

To adapt to your screen layout, the horizontal or vertical orientation of the statistics and source code panes can be toggled with the orientation button.

 

orientation1                 orientation2

 

 

Updating the display

 

Display... instructionStep display the Statistics display dialog, which controls the auto-updating of the display.

 

 statistics-display-dialog

 

Auto update... instructionStep switch the automatic updating on or off - see the next option

 

...every N seconds instructionStep automatically updates the display at your choice of interval, from 1.0 to 60 seconds

 

Adjust this depending on the complexity of your application.

 

An update interval that is too short may mean Performance Validator spends too much time updating the display.

 

Refresh instructionStep updates the display - as does the refresh button on the Tools menu and toolbar

 

With auto update off, you'll need to use this Refresh button to update the display when you wish.

 

Do not scroll first column instructionStep optionally keep the first column fixed when scrolling the table horizontally

 

Unless you changed the visible columns, or reordered them, the first column will typically be Class::Method.

 

 

Sorting the data

 

You can sort the data in the table by clicking in the table header.

 

note Note that while your application is executing, the sorted data is live. Sorting may not complete correctly as the data may change during the sort. Only when your program has finished executing is the sorted data guaranteed accurate.

 

 

Managing the data being displayed

 

There are two ways to change what's displayed in the view.

 

hide or show whole columns of data in the table
 

filter out unwanted functions, or only show specific functions of interest

 

 

Changing which columns are displayed

 

The choice of which columns to display is the same on the Statistics and Relations tabs. In fact, you can choose to control columns in both areas from the same configuration dialog.

 

Columns instructionStep shows the Configure Columns dialog for the Statistics view

 

If you're using a sampling method to collect statistics, you'll see the dialog on the right.

 

configure-columns   configure-columns-sampling-statistics

 

Check or uncheck which columns you want to show and hide.

 

Up / Down instructionStep nudge a selected column name up or down in the list

 

Columns at the top are displayed left-most in the table

 

Reset instructionStep set the visibility and the order of columns back to their defaults

 

Don't scroll first column instructionStep optionally keep the first column fixed when scrolling the table horizontally

 

Unless you changed the visible columns, or reordered them, the first column will typically be Class::Method.

 

Apply to all display tabs instructionStep if checked (default), the changes you make will affect both Statistics and Relations tabs

 

Once configured, click OK to apply the changes.

 

 

Filtering statistics in the table

 

The 'display filters' affect which functions are hidden and shown in the data. They do not affect which functions are hooked in the first place.

 

Filter instructionStep shows the Statistics Display Filter Manager:

 

statistics-display-filter-manager

 

The dialog initially has no items in the list. Add some items manually or use the convenience filter options on the popup menu.

 

Add... instructionStep displays the display filter dialog described below
 

Edit... instructionStep opens the display filter dialog populated with the selected item's criteria, ready for editing
 

Alternatively, just double click an entry in the list to show the filter dialog.

 

Remove instructionStep remove selected filter(s) in the list

Remove All instructionStep remove all filters

 

Enable All instructionStep enables all filters in the list

Disable All instructionStep disables all filters

 

You can also enable or disable individual items in the list via the yellow check box at the left of each row.

 

Invert Filters instructionStep leave unchecked to remove matched items from the display, or check to keep only matched items

 

Inverting filters is a powerful way to remove unwanted 'noise' in the data displayed, and to focus tightly on specific criteria.

 

note Take care when removing inverted filters as clearing the list and leaving inverting filters checked will leave no functions being displayed at all!

 

 

The Display Filter dialog

 

The dialog below allows you to create a filter based on matching one or more criteria.

 

display-filter-dialog

 

If you don't enter some of the details, they simply won't form part of the match criteria.

 

Enabled instructionStep set this particular filter active or inactive

 

This is exactly equivalent to checking the listed item in the display filter manager.

 

Class instructionStep enter the class name that the filter must match

 

If you enter a class but no method name then all functions in the class are filtered.
 

Method instructionStep enter the method name

 

If you enter a method but no class then the filter will match the named function in any class.

 

Filename instructionStep filter all functions in the specified file

 

The full path to the file is required.

 

Directory instructionStep filter all functions in the specified directory

 

The full directory path is required.

 

Module instructionStep filter all functions in the specified module

 

The full path to the module is required.

 

Address instructionStep filter an exact address in memory

 

 

Finding text

 

To find text in the table of statistics, use the Find Dialog where you can search in any or all of the different columns.

 

seeAlsoThe source code view has its own Find and Goto dialogs.

 

 

Statistics menu optionsright_mouse_button

 

The following popup menu is available over the data area to add filters, examine relations or edit code.

 

Menu actions apply to the function for the row at the menu-click location.

 

statistics-menu

 

 

right_mouse_buttonMenu options: Display Filter

 

The display filter sub-menu below provides a quick and convenient way to hide or show data based on attributes of the selected item.

 

statistics-menu-display-filter

 

Choosing any of these options will add the filter to the Display Filter dialog.

 

For example:

 

Class instructionStep hides all functions belonging to the same class
 

FileName instructionStep hides all functions that were in the same file

 

 

note These options work well for filtering out something you see in the display that you'd like to remove. You may not get the results you expect if the Display Filter dialog is set to have the filters inverted.

 

 

right_mouse_buttonMenu options: Function filter (Instrumentation)

 

While the display filter controls visibility of hooked data, instrumentation filters control which functions are hooked in the first place.

 

The function instrumentation filter sub-menu lets you add hook filters at different levels of granularity.

 

statistics-menu-instrumentation-filter

 

note The affect of adding function filters here depends on the current filter settings:

 

If the current filters are set to hook everything, adding new filters will switch to excluding newly selected hooks
 

Otherwise, the current filter will be retained, i.e. hook or don't hook newly selected items  

 

 

The first three options add filters to the Class and Function Filter Settings:

 

By Class instructionStep adds a new filter, excluding the entire class from the results of subsequent sessions
 

By Class and Method instructionStep excludes only the selected function from new sessions
 

By Function instructionStep excludes all matching function names irrespective of their containing class or even if not in a class at all
 

 

The next two, Filename and Directory, are part of the Source Files Filter settings.

 

By FileName instructionStep adds a new filter, excluding all functions in the same file (as the selected item) from the results of subsequent sessions
 

By Directory instructionStep excludes functions in all files in the same directory as the selected function
 

 

Finally, the DLL level is controlled by the Hooked DLLs settings.

 

By DLL instructionStep excludes functions in all files belonging to the same executable or DLL as the selected function
 

 

note Instrumentation filters become effective at the start of the next session. Adding a filter during a session will show the relevant rows in grey so that you can see which files would be filtered, but the performance data will continue to be included for the rest of the current session.

 

 

right_mouse_buttonMenu options: Line timing filter (Instrumentation)

 

Line timing instrumentation filters control which lines are hooked for line timing and are independent of the function filters above.

 

note The affect of adding line timing filters here depends on the current line timing filter settings:

 

If the current filters are set to hook everything, adding new filters will switch to only including newly selected hooks

 

Note that this is the opposite of function filters.
 

Otherwise, the current filter will be retained, i.e. hook or don't hook newly selected items  

 

The line timing instrumentation filter sub-menu lets you add hook filters at three different levels of granularity.

 

Each option add filters to the Line Timing Filter Settings:

 

By Class instructionStep adds a new filter, appending the entire class in the line timing results of subsequent sessions
 

By Class and Method instructionStep include only the selected function in the line timing of new sessions
 

By Function instructionStep includes all matching function names irrespective of their containing class or even if not in a class at all
 

note Instrumentation filters become effective at the start of the next session. Adding a filter during a session will show the relevant rows in grey so that you can see which files would be filtered, but the performance data will continue to be included for the rest of the current session.

 

 

right_mouse_buttonMenu option: Show in Analysis tab

 

The Analysis tab shows results of a query on the call tree based on the selected function and the criteria chosen from the menu:

 

Show in Analysis tab instructionStep choose any item in the following sub-menu, to be switched to the Analysis tab

 

statistics-menu-show-in-analysis

 

For example:

 

Class instructionStep the Analysis tab will show all points in the call tree that match the class of the selected function
 

File name instructionStep shows all points in the call tree that match the file name of the selected function

 

Slower Functions (%) instructionStep shows all functions that are slower than the selected function

 

 

right_mouse_buttonMenu options: Show in other tabs

 

Show in Relations tab instructionStep switch to the Relations tab where you can examine functions that either call, or are called by, the selected function

 

Double clicking any item will also display it in the Relations tab.

 

Go to Call Tree Node instructionStep switch to the Call Tree view where the display will be expanded to show the first match found for the selected function

 

Go to Call Graph Node instructionStep switch to the Call Graph view where the display will be expanded to show the first match found for the selected function

 

 

right_mouse_buttonMenu option: editing source code

 

Edit Source Code... instructionStep opens the default or preferred editor to edit the source code

 

 

right_mouse_buttonMenu option: column widths

 

Auto size column widths instructionStep sets the width of each column in the table appropriate to the content within

 

 

The file source code view

 

Clicking on a function in the statistics table shows that function's source code file in the right hand pane.

 

The source code view is described in detail separately as its behaviour is the same for all views.