Overview

HPCToolkit provides the hpcviewer (Adhianto, Mellor-Crummey, and Tallent 2010; N. R. Tallent et al. 2011) performance presentation tool for interactive examination of performance databases. hpcviewer presents a heterogeneous calling context tree that spans both CPU and GPU contexts, annotated with measured or derived metrics to help users assess code performance and identify bottlenecks.

The database generated by hpcprof consists of 4 dimensions:

To simplify performance data visualization, hpcviewer restricts the display of two dimensions at a time: the Profile View displays pairs of (call-path, metric) or (execution context, metric) dimensions and the Trace View visualizes the behavior of execution contexts over time. The table below summarizes views supported by hpcviewer.

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

Note that in the Profile view, GPU stream execution contexts are not shown in this view; metrics for a GPU operation are associated with the calling context in the thread that initiated the GPU operation (Section Thread View). In the Trace view, GPU streams have their trace lines independently from their host, allowing for the traces between hosts and devices to be separated.

Launching

Requirements to launch hpcviewer:

  • On all platforms: Java 17 or newer (up to Java 21).
  • On Linux: GTK 3.20 or newer.

hpcviewer can be launched from a command line (Linux platforms) or by clicking the hpcviewer icon (for Windows, Mac OS X, and Linux platforms). The command line syntax is as follows:

 hpcviewer [options] [<hpctoolkit-database>]

Here, <hpctoolkit-database> is an optional argument to load a database automatically. Without this argument, hpcviewer will prompt for the location of a database. Possible options for hpcviewer are shown below:

-h, --help
Print a help message.
-jh, --java-heap size
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.
-v, --version
Print the current version

On Linux, when hpcviewer is installed using its install.sh script, one can specify the maximum size for the Java heap on the current platform. When analyzing measurements for large and complex applications, it may be necessary to use the --java-heap option to specify a larger heap size for hpcviewer to accommodate many metrics for many contexts.

On macOs and Windows, the value of JVM maximum heap size is stored in hpcviewer.ini file, specified with -Xmx option. On macOS, this file is located at hpcviewer.app/Contents/Eclipse/hpcviewer.ini.

Menus

hpcviewer provides four main menus: File, Filter, View, and Help.

File

This menu includes several menu items for controlling basic viewer operations.

  • New window
    Open a new hpcviewer window that is independent of the existing one. However, filtering CCT node operation (see Filtering Tree Nodes) will also affect all hpcviewer windows.
  • Open database
    Open a database without replacing the existing one. This menu can be used to compare two databases.
  • Open remote database (experimental feature)
    Open a database located at the remote host via a secured SSH tunnel. One can use the private key option to connect without typing a password. See Remote database page for further details.
  • Switch database
    Load a performance database into the current hpcviewer window replacing the existing opened databases.
  • Close database
    Unloading an open database.
  • Merge databases
    Merging two databases that are currently in the viewer. Currently, it doesn't support storing a merged database in a file.
    • Top-down tree: Merging the top-down tree of the databases.
    • Flat tree: Merging the flat (static) tree of the databases.
  • Preferences
    Display the settings window, 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 rendering option, the number of working threads to be used and the tooltip's delay.
    • Debug: Enable/disable debug mode and experimental feature.
  • Exit
    Quit the hpcviewer application.

Filter

This menu only contains one submenu:

  • Filter CCT nodes
    Open a filter property window that lists a set of filters and their properties (Section Filtering Tree Nodes).
  • Filter execution contexts (Trace view only)
    Open a window to hide or show trace lines.

View

This menu is only visible if at least one database is loaded.

  • Show metrics (Profile view only)
    Display the list of metrics including their name, description, and visibility. For GPU metrics, the descriptions are useful for explaining what the short and somewhat cryptic metric names mean. From this list, one can use the Edit button to rename or modify a derived metric, including the formula. Once the change is confirmed, it will be propagated to the list and all views (Top-down, Bottom-up, and Flat) in the current database.
  • Show color map (Trace view only)
    Open a window showing the customized mapping between a procedure pattern and a color. See the Color map Section.
  • Debug (if the debug mode is enabled) \
    • Show database raw's XML: Display of HPCToolkit's raw XML representation for performance data. This menu is only available for old HPCToolkit databases.

Help

This menu displays information about the viewer. The menu contains only one menu item:

  • About
    Displays brief information about the viewer, including JVM and Eclipse variables, and error log files.

Limitations

Some important hpcviewer limitations are listed below:

  • Limited number of metric columns.
    With a large number of metric columns, hpcviewer's response time may become sluggish as this requires a large amount of memory.
  • Experimental Windows 11 platform.
    The Windows version of hpcviewer is mainly tested on Windows 10. Support for Windows 11 is still experimental.
  • No support for dark themes.
    We received reports that hpcviewer is not very visible on Linux with a dark theme. It is still an ongoing work.
  • Linux TWM window manager is not supported.
    Reason: This window manager is too ancient.