hpcviewer:
Interactive Presentation of Performance
The HPCToolkit Performance Tools
2023/05/31
Version 2023.03.01-develop
The Java-based hpcviewer
interactively presents program performance in a top-down fashion.
Table of Contents
Command-line usage:
hpcviewer
[options]
[hpctoolkit-database]
GUI usage:
Launch hpcviewer
and open the experiment database [hpctoolkit-database].
The Java-based hpcviewer
interactively presents program-performance experiment databases
in a top-down fashion.
Since experiment databases are self-contained,
they may be relocated from a cluster for visualization on a laptop or workstation.
- hpctoolkit-database
- An HPCToolkit experiment database
produced by hpcprof.
- -h --help
-
Print a help message.
- -jh, --java-heap
-
Set the JVM maximum heap size for this execution of hpcviewer.
The value of size
must be
in megabytes (M) or gigabytes (G). For example, one can specify a size
of 3 gigabytes as either
3076M or 3G.
hpcviewer
supports four principal views of an application's performance data.
Each view reports both inclusive costs (including callees) and exclusive costs (excluding callees).
- Top-down view.
A top-down view depicting the dynamic calling contexts (call paths) in which costs were incurred.
With this view one can explore the performance of an application in a top-down manner
to understand the costs incurred by calls to a procedure in a particular calling context.
- Bottom-up view.
This bottom-up view enables one to look upward along call paths.
It apportions a procedure's costs to its caller and, more generally,
its calling contexts.
This view is particularly useful for understanding the performance of software components or procedures
that are used in more than one context.
- Flat view.
This view organizes performance data according to the static structure of an application.
All costs incurred in any
calling context by a procedure are aggregated together in the flat view.
- Thread view
This view displays the metric values of execution contexts.
An execution context is an abstraction of a measure of code execution such as threads and processes.
To activate the view, select a thread or a set of execution contexts by clicking the thread-view button from the Top-down view.
On the execution context selection window, select the checkbox of the execution contexts of interest.
To narrow the list, specify the name on the filter part of the window.
Once the execution contexts have been selected, click OK,
and the Thread view will be activated.
The tree of the view is the same as the tree from the Top-down view, with the metrics only from the selected execution contexts.
If there is more than one selected thread, the metrics are the sum of the metric values.
Currently contexts for GPU streams are not shown in the thread view; metrics for a GPU operation are associated with the calling context in the thread that initiated the GPU operation.
The browser window is split into two panes:
hpcviewer
can display graphs of thread-level metric values
which is useful for quickly assessing load imbalance across processes and threads.
To create a graph,
choose the top-down view and select an item in the navigation pane,
then click the graph button above the navigation pane.
A list of graphable metrics appears at the bottom of the context menu,
each with a sub-menu showing the three graph styles that hpcviewer
can make.
The Plot
graph displays metrics ordered by execution context.
The Sorted plot
graph displays metrics sorted by value;
and the Histogram
graph displays a barchart of metric value distributions.
The view interactively presents program traces in a top-down fashion.
It comprises of three different parts.
- Main view (left, top):
This is the primary view.
This view, which is similar to a conventional process/time (or space/time) view, shows time on the horizontal axis and process (or thread) rank on the vertical axis; time moves from left to right.
Compared to typical process/time views, there is one key difference.
To show call path hierarchy, the view is actually a user-controllable slice of the process/time/call-path space.
Given a call path depth, the view shows the color of the currently active procedure at a given time and process rank.
(If the requested depth is deeper than a particular call path, then the viewer simply displays the deepest procedure frame and, space permitting, overlays an annotation indicating the fact that this frame represents a shallower depth.)
hpcviewer assigns colors to procedures based on (static) source code procedures.
Although the color assignment is currently random, it is consistent across the different views.
Thus, the same color within the Trace and Depth Views refers to the same procedure.
The Trace View has a white crosshair that represents a selected point in time and process space.
For this selected point, the Call Path View shows the corresponding call path.
The Depth View shows the selected process.
- Depth view (left, bottom):
This is a call-path/time view for the process rank selected by the Trace view's crosshair.
Given a process rank, the view shows for each virtual time along the horizontal axis a stylized call path along the vertical axis, where `main' is at the top and leaves (samples) are at the bottom.
In other words, this view shows for the whole time range, in qualitative fashion, what the Call Path View shows for a selected point.
The horizontal time axis is exactly aligned with the Trace View's time axis; and the colors are consistent across both views.
This view has its own crosshair that corresponds to the currently selected time and call path depth.
- Summary view (same location as depth view on the left-bottom part):
The view shows for the whole time range displayed, the proportion of each subroutine in a certain time.
Similar to Depth view, the time range in Summary reflects to the time range in the Trace view.
- Call stack view (right, top):
This view shows two things: (1) the current call path depth that defines the hierarchical slice shown in the Trace View; and (2) the actual call path for the point selected by the Trace View's crosshair.
(To easily coordinate the call path depth value with the call path, the Call Path View currently suppresses details such as loop structure and call sites; we may use indentation or other techniques to display this in the future.)
- Statistics view (tab in top, right pane)
The view shows a list of procedures and the estimated execution percentage for each for the time interval currently shown in the Trace view.
- GPU Blame view (tab in top, right pane)
This view shows the list of procedures that cause GPU idleness displayed in the trace view.
- Mini map view (right, bottom):
The Mini Map shows, relative to the process/time dimensions, the portion of the execution shown by the Trace View.
The Mini Map enables one to zoom and to move from one close-up to another quickly.
Note:
- GPUs are very fast, hence the time interval during which a GPU operation is active may be very short. A problem for users is that it may be hard to locate short GPU operations that are separated by long intervals of idleness in the trace. Such operations will often be invisible because
when hpcviewer renders a pixel in a trace, it will not show a GPU operation unless the time point at the left edge of the pixel's associated time interval falls within the time interval of the GPU operation.
To force hpcviewer to render a GPU operation if any GPU operation is active within the time interval associated with a pixel, one can enable Expose GPU traces
by clicking the menu File
- Preferences
and click the Traces
page, then check the Expose GPU traces
option.
Warning: enabling this option causes trace statistics to be unreliable because GPU activity will be overrepresented.
Main view is divided into two parts: the top part which contains action pane
and the information pane,
and the main view which displays the traces.
The buttons in the action pane are the following:
- Home : Resetting the view configuration into the original view, i.e., viewing traces for all times and processes.
- Horiontal zoom in / out : Zooming in/out the time dimension of the traces.
- Vertical zoom in / out : Zooming in/out the process dimension of the traces.
- Navigation buttons : Navigating the trace view to the left, right, up and bottom, respectively. It is also possible to navigate with the arrow keys in the keyboard. Since Trace view does not support scrool bars, the only way to navigate is through navigation buttons (or arrow keys).
- Undo : Canceling the action of zoom or navigation and returning back to the previous view configuration.
- Redo : Redoing of previously undo change of view configuration.
- Save/Load a view configuration : Saving/loading a saved view configuration.
A view configuration file contains the information of the current dimension of time and process, the depth and the position of the crosshair.
It is recommended to store the view configuration file in the same directory as the database to ensure that the view configuration file matches well with the database since the file does not store which database it is associated with.
Although it is possible to open a view configuration file which is associated from different database, it is highly not recommended since each database has different time/process dimensions and depth.
The information pane contains some information concerning the range status of the current displayed data.
- Time Range. The information of current time-range (horizontal) dimension.
- Cross Hair. The information of current crosshair position in time and execution-context dimensions.
Depth view shows all the call path for a certain time range [t_1,t_2]= {t | t_1 <= t <= t_2} in a specified process rank p. The content of Depth view is always consistent with the position of the cross-hair in Trace view.
For instance once the user clicks in process p and time t, while the current depth of call path is d, then the Depth view's content is updated to display all the call path of process p and shows its cross-hair on the time t and the call path depth d.
On the other hand, any user action such as cross-hair and time range selection in Depth view will update the content within Trace view. Similarly, the selection of new call path depth in Call view invokes a new position in Depth view.
In Depth view a user can specify a new cross-hair time and a new time range.
Specifying a new cross-hair time.
Selecting a new cross-hair time t can be performed by clicking a pixel within Depth view. This will update the cross-hair in Trace view and the call path in Call view.
Selecting a new time range.
Selecting a new time range [t_m,t_n]= {t | t_m <= t <= t_n} is performed by first clicking the position of t_m and drag the cursor to the position of t_n. A new content in Depth view and Trace view is then updated. Note that this action will not update the call path in Call view since it does not change the position of the cross-hair.
Summary view presents the proportion of number of calls of time t across the current displayed rank of process p.
Similar to Depth view, the time range in Summary view is always consistent with the time range in Trace view.
One can also select a new time range in this view.
This view lists the call path of process p
and time t
specified in Trace view and Depth view.
This view can show a call path from depth 0 to the maximum depth, and the current depth is shown in the depth editor (located on the top part of the view).
In this view, the user can select the depth dimension by either typing the depth in the depth editor or selecting a procedure in the table of call path.
The view shows a list of procedures and the estimated execution percentage for each for the time interval currently shown in the Trace view.
Whenever the user changes the time interval displayed in the Trace view, the statistics view will update its list of procedures and their execution percentages to
reflect the current interval. Similarly, a change in the selected call path depth will also update the contents of the statistics view.
The Mini view shows, relative to the process/time dimensions, the portion of the execution shown by the Trace view.
In Mini view, the user can select a new process/time (p_a,t_a),(p_b,t_b) dimensions by clicking the first process/time position (p_a,t_a) and then drag the cursor to the second position (p_b,t_b).
The user can also moving the current selected region to another region by clicking the white rectangle and drag it to the new place.
hpcviewer
provides five main menus:
This menu includes several menu items for controlling basic viewer operations.
- New window
Open a new hpcviewer
window that is independent from the existing one.
- Switch database
Load a performance database into the current hpcviewer
window and close all opened databases (if any).
- Open database
Load a performance database into the current hpcviewer
window.
Currently hpcviewer
restricts maximum of five database open at a time.
To display more, one can either closing an existing open database, or opening a new hpcviewer
window.
- Close database
Unloading a performance database.
- Merge database
Merging two database that are currently in the viewer. If hpcviewer
has more than two
open database, then one needs to choose which database to be merged.
Currently hpcviewer
does not support storing a merged database into a file.
- Merge top-down tree Merging the top-down trees of the two opened database.
- Merge flat tree Merging the flat trees of the two opened database.
- Preferences...
Display the settings dialog box which consists of three sections:
- Appearance Change the fonts for tree and metric columns and source viewer.
- Traces Specify settings for Trace view such as the number of working threads to be used and the tooltip's delay.
- Debug Enable/disable debug mode.
- Exit
Quit the hpcviewer
application.
This menu is to allow users to filter certain nodes in the Profile view or filter certain profiles in the Trace view.
- Filter execution contexts (Trace view mode only).
Open a window for selecting which ranks or threads or GPUs should be displayed.
- Filter CCT nodes.
Open a filter property window which lists a set of filters and its properties.
hpcviewer
allows users to define multiple filters, and each filter is associated with a type and a glob pattern (A glob pattern specifies which name to be removed by using wildcard characters such as *, ? and +).
There are three types of filter: ``self only''
to omit matched nodes,
``descendants only''
to exclude only the subtree of the matched nodes, and ``self and descendants''
to
remove matched nodes and its descendants.
This menu is only visible if at least one database is loaded.
All actions in this menu are intended primarily for tool developer use.
By default, the menu is hidden. Once a database is loaded, the menu is then visible.
- Show metric
Show the metric property view which allows to show or hide specified metrics of the current table.
One can also edit the name of a metric column or even edit the formula of a derived metric.
- Split window
Enabled if there are two databases open. This menu allows to split vertically two databases into two panes to easily compare them.
- Color map Trace view only: to open a window which shows customized mapping between a procedure pattern and a color. hpcviewer allows users to customize assignment of a pattern of procedure names with a specific color.
- Debug (if the debug mode is enabled)
A special set of menus for advanced users when the debug mode is enabled. The menu is useful to debug hpcviewer.
The menu consists of:
- Show database raw's XML
Enable one to request display of raw XML representation for performance data.
This menu displays information about the viewer.
- About.
Displays brief information about the viewer, including JVM and Eclipse variables, and error log files.
hpctoolkit(1)
.
Version: 2023.03.01-develop
- Copyright
- © 2002-2023, Rice University.
- License
- See LICENSE.
Rice University's HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.