stat-view man page

stat-view - invoke the Stack Trace Analysis Tool viewer.

SYNOPSIS

stat-view [ file.dot… ]

where [ file.dot… ] represents zero or more STAT generated .dot files.

DESCRIPTION

stat-view is a GUI for viewing STAT-outputted dot files. stat-view provides easy navigation of the call prefix tree and also allows manipulation of the call tree to help focus on areas of interest. Each node in the STAT call prefix tree represents a function call and the directed edges denote the calling sequence. Further, the edges are labeled by the set of tasks that have taken that call path. For simplification, stat-view will display the number of tasks in the set and truncate long task lists in the main display with “…” notation. Similarly, long function node label names will be truncated with “…” notation. The truncation length can be modified via the File->Preferences menu (this requires clicking the Layout button to rerender any already loaded graphs). Nodes are colored based on the set of tasks of the incoming edge, providing a visual distinction when different tasks take different branches.

The stat-view GUI also allows you to view the application source files in the stack traces, when sampling is done at the source file and line number granularity. This may require the source file’s path to be added to the search path, through File -> Add Search Paths. If an application’s source code is edited after STAT is run, the line numbers shown in the stack traces may not be accurate. To alleviate this problem, STAT can optionally cache the source files for the currently displayed .dot file. To cache files click on the File -> Add Search Paths menu item. This will find and save the source files in the .dot file’s stat_results directory. The next time you open the .dot file with stat-view, the source files will automatically be loaded from the cache.

By left clicking on a node in the call prefix tree you will get a window displaying the full list of tasks and the full frame label . This window also contains buttons that allow for the manipulation of the graph from that node. Right clicking on a node provides a pop-up menu with the same options. Note all of these operations are performed on the current visible state of the call prefix tree.

The node operations are defined as follows:

Advanced

Display the full node and edge attributes.

Join Equivalence Class

collapses all of the descendent nodes with the same equivalence class into the current node and renders in a new tab.

Collapse

hide all of the descendents of the selected node.

Collapse Depth

collapse the entire tree to the depth of the selected node.

Hide

the same as Collapse, but also hides the selected node.

Expand

show (unhide) the immediate children of the selected node.

Expand All

show (unhide) all descendents of the selected node.

Focus

hide all nodes that are neither ancestors nor descendents of the selected node. (Note: This will not unhide any hidden ancestors.)

View Source

creates a popup window displaying the source file (only for stack traces with line number information). This may require the source file’s path to be added to the search path, through File -> Add Search Paths.

Translate

For traces with module and offset granularity, this button will translate all node labels into source file and line number information and open the resulting graph in a new tab.

Temporally Order Children

(prototype only) determine the temporal order of the node’s children (only for stack traces with line number information). Requires the source file’s path and all include paths to be added to the search path, through File -> Add Search Paths.

OK

closes the pop-up window.

The main window also has several tree manipulation options . Note the initial click of a traversal operation operates on the original call prefix tree, while the remaining operations are performed on the current visible state of the call prefix tree.

The toolbar operations are defined as follows:

Open

Open a STAT generated .dot file

Save As

Save the current graph in .dot format, which can be displayed by stat-view or in an image format, such as PNG or PDF, which can be viewed on any computer with an image viewer

Undo

Undo the previous operation

Redo

Redo the undone operation

Reset

Revert to the original graph

Layout

Reset the layout of the current graph and open in a new tab. This is useful for compacting wide trees after performing some pruning operations.

Cut

This feature allows you to collapse the prefix tree below the implementation frames for various programming models. For instance, a user may wish to hide all calls that happen within the MPI library. The programming models may be entered in a configuration file or added by the user. STATview looks for configuration files in $prefix/etc/STAT/STATview_models.conf and in $HOME/.STATview_models.conf. Programming models are specified as regular expressions, using Python’s re module syntax, and the re.search function is used in favor of re.match.

[Cut] MPI

Collapse the MPI implementation frames below the MPI function call.

[Cut] Pthreads

Collapse the Pthread implementation frames below the Pthread function call.

Join

Join consecutive nodes of the same equivalence class into a single node and render in a new tab. This is useful for condensing long call sequences.

[Traverse] Eq C

Traverse the prefix tree by expanding the leaves to the next equivalence class set. The first click will display the top-level equivalence class.

[Traverse Longest] Path

Traversal focus on the next longest call path(s). The first click will focus on the longest path.

[Traverse Shortest] Path

Traversal focus on the next shortest call path(s). The first click will focus on the shortest path.

[Traverse Least] Tasks

Traversal focus on the path(s) with the next least visiting tasks. The first click will focus on the path with the least visiting tasks.

[Traverse Most] Tasks

Traversal focus on the path(s) with the next most visiting tasks. The first click will focus on the path with the most visiting tasks.

[Traverse Least] TO

Temporal Order traversal focus on the path(s) that have made the least execution progress in the application. The first click will focus on the path that has made the least progress.

[Traverse Most] TO

Temporal Order traversal focus on the path(s) that have made the most execution progress in the application. The first click will focus on the path that has made the most progress.

Search

Search for call paths containing specified text, taken by specified tasks, or from specified hosts. Search text may be a regular expression, using the syntax described in <URL:http://docs.python.org/library/re.html>.

[Identify] Eq C

Identify the equivalence classes of the visible graph. After clicking on this button, a window will pop up showing the complete list of equivalence classes.

AUTHOR

(Written by ) Gregory L. Lee <lee218@llnl.gov>

SEE ALSO

stat-cl(1), stat-gui(1)