hpctraceviewer:
Interactive Presentation of Program Traces
The HPCToolkit Performance Tools
2020/06/09
Version 2020.08-develop
The Java-based hpctraceviewer
interactively presents dynamic behavior of a program.
Table of Contents
Command-line usage:
hpctraceviewer
[options]
[hpctoolkit-database]
GUI usage:
Launch hpctraceviewer
and open the Experiment database [hpctoolkit-database].
The Java-based hpctraceviewer
interactively presents program traces in a top-down fashion.
Since Experiment databases are self-contained, they may be relocated from a cluster for visulization on a laptop or workstation.
- hpctoolkit-database
- An HPCToolkit Experiment database, which is the result of executing hpcprof,
hpcprof-mpi
or hpcprof-flat.
- -h --help
-
Print help.
- -jh, --java-heap
-
Set the JVM maximum heap size for this execution of hpctraceviewer.
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.
hpctraceviewer
provides several views:
- Trace view (top, left pane):
This is hpctraceviewer's 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 hpctraceviewer simply displays the deepest procedure frame and, space permitting, overlays an annotation indicating the fact that this frame represents a shallower depth.)
hpctraceviewer 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 (tab in bottom, left pane):
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 (tab in bottom, left pane):
The view shows for the whole time range dislayed, 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 Path view (tab in top, right pane):
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.
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 view (bottom, right pane):
The Mini Map shows, relative to the process/time dimensions, the region of the execution shown by the Trace View.
In the Mini map, dragging the selected region or making a new selection enables one to change the region of the trace that is the current focus for analysis.
Trace 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 / 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.
- Process Range. The information of current process-range (vertical) dimension.
- Cross Hair. The information of current crosshair position in time and process dimensions.
Depthview 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 proces p.
Similar to Depth view, the time range in Summary view is always consistent with the time range in Trace 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 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.
hpctraceviewer
provides three main menus:
- File menu which contains two sub menus:
- Open database: to load a database experiment directory. The directory has to contain experiment.xml (CCT and metric information) or callpath.xml (uniquely CCT information), and *.hpctrace or experiment.mt files which provide trace information.
- Exit: to quit the application.
- View menu to enhance appearance which contains two sub menus:
- Show debug info: to enable/disabe the display of debugging information in the form of `a(b)' where a is the maximum depth (this number is shown if the current depth reaches the maximum depth) and b is the number of records on the trace view.
The number of records can be useful to identify blocking procedures (such as I/O operations). Note: the numbers are displayed only if there's enough space in the process time line.
- Using midpoint painting: if checked, the trace painting will use {midpoint} painting algorithm. By using the later, for every samples S1 at time T1, S2 at time T2 and S3 at time T3, hpctraceviewer renders a block from T1 to (T1+T2)/2 to sample S1, and a block from from (T1+T2)/2 to (T2+T3(/2 for sample S2, and so forth.
If the menu is not checked, then a simpler {rightmost} algorithm is used: it will render a block from T1 to T2 for sample S1, and a block from T2 to T3 for sample S2, and so forth.
- Show procedure-color mapping: to open a window which shows customized mapping between a procedure pattern and a color. hpctraceviewer allows users to customize assignment of a pattern of procedure names with a specific color.
- Filter ranks: to open a window for selecting which ranks and/or threads should be displayed or hidden.
Recall that a rank can be a process (e.g. MPI applications), a thread (OpenMP applications) or a process/thread pair (hybrid MPI and OpenMP applications).
hpctraceviewer
allows two types of filtering: either you specify which ranks {to show} or {to hide} (default is to hide).
To add a pattern to filter, you need to click the "Add" button and type the pattern in the format minimum:maximum:stride.
For instance, 3:7:2
in the process box with the thread box empty will match all threads of processes 3, 5, and 7.
To remove a pattern, you have to select the pattern to remove, and click the "Remove" button. Finally, clicking to "Remove all" button will clear the list of patterns.
- Window menu to manage the layout of the application. The menu only provide one sub menu:
- Reset layout: to reset the layout to the original one.
hpctraceviewer
also provides a context menu to save the current image of the view.
This context menu is available is three views: trace view, depth view and summary view.
hpctoolkit(1)
.
Version: 2020.08-develop
- Copyright
- © 2002-2020, Rice University.
- License
- See README.License.
Rice University's HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.