Interactive Presentation of Performance

The HPCToolkit Performance Tools


Version 2024.01.1-release

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.


An HPCToolkit experiment database produced by hpcprof/hpcprof-mpi.


-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.

Data representation

The database generated by hpcprof/hpcprof-mpi consists of 4 dimensions: execution context (also called execution profile), time, tree node context, and metric. The term execution context includes any logical threads (such as OpenMP, pthread and C++ threads), and also MPI processes and GPU streams. The time dimension represents the timeline of the program's execution, and tree node context depicts a top-down path in a calling-context tree. This time dimension is only available if the application is profiled with traces enabled (hpcrun -t option). Finally, the metric dimension constitutes program measurements performed by hpcrun such as cycles, number of instructions, stall percentages and also some derived metrics such as ratio of idleness.

The following table summarizes different views supported by hpcviewer:

View Dimension Note
Profile view - Table Tree node context x Metrics display the tree and its associated metrics
Profile view - Thread Tree node context x Metrics display the tree and its metrics for a set of execution contexts
Profile view - Graph Execution contexts x Metrics display a metric of a specific tree node for all execution contexts
Trace view - Main Execution contexts x Time display execution context behavior over time
Trace view - Depth Tree node context x Time display call stacks over time of an execution context

Profile view


hpcviewer supports four principal views of an application's performance data. Each view reports both inclusive costs (including callees) and exclusive costs (excluding callees).


The browser window is split into two panes:

Plot Graphs

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.


Trace view

The view interactively presents program traces in a top-down fashion. It comprises of three different parts.


Main view

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:

The information pane contains some information concerning the range status of the current displayed data.

Depth view

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 pane

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.

Call stack pane

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.

Statistics 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. 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.

Mini map pane

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.


This menu is to allow users to filter certain nodes in the Profile view or filter certain profiles in the Trace view.


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.


This menu displays information about the viewer.

See Also

hpctoolkit(1) .


Version: 2024.01.1-release

License and Copyright

© 2002-2023, Rice University.


Rice University's HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: https://hpctoolkit.org.