app2

visualizes performance analysis data

Author:: Hewlett Packard Enterprise Development LP.
Copyright:: Copyright 2019,2021-2024 Hewlett Packard Enterprise Development LP.
Manual section:: 1

SYNOPSIS

app2 [[user@host]:] [-V] [–compare] [–cg] [experiment_data_directory …]

DESCRIPTION

Cray Apprentice2 is a post-processing performance data visualization tool. After you instrument a program for a performance analysis experiment, execute the instrumented executable, and generate one or more experiment data directories, use Cray Apprentice2 to explore the experiment data and generate a variety of interactive graphical reports.

Cray Apprentice2 supports the following options:

[user]@host:

Cray Apprentice2 supports passwordless ssh. If you are using Cray Apprentice2 to access data files on a remote system, you can specify your user name and the host system name on the command line. For example:

$ app2 user@host:experiment_data_directory

Alternatively, if you have the same user name on both the local and remote systems, you may omit the user@ portion and enter:

$ app2 host:experiment_data_directory

-V, –version

Display the Cray Apprentice2 version number and exit.

–compare experiment_data_directory1 experiment_data_directory2

Launch Cray Apprentice2 and load the two data directories as a side-by-side display. The files in experiment_data_directory1 and experiment_data_directory2 must have the same experiment and summary types.

–cg

Launch Cray Apprentice2 with the callgraph as the initial panel.

experiment_data_directory …

Depending on the options and environment variables in effect at the time the experiment is conducted, CrayPat generates an experiment_data_directory containing the data captured during the program execution, in either .xf (CrayPat native) or .ap2 (Cray Apprentice2 native) formats.

Cray Apprentice2 can read-in either single .ap2 data files or entire directories of data files.

Note: Cray Apprentice2 cannot read files in CrayPat native (.xf) format. If your experiment generates .xf data files, you must use the pat_report utility to convert the CrayPat output files into .ap2 format files.

The experiment_data_directory argument to the app2 utility enables you to specify the name of the file or directory to be read-in when launching Cray Apprentice2. Alternately, you can omit the experiment_data_directory argument and instead select the data you want to work with later, through the Cray Apprentice2 GUI.

Cray Apprentice2 includes an integrated help system. All other information about using Cray Apprentice2 is presented in the help system, which is accessible whenever Cray Apprentice2 is running.

Cray Apprentice2 is a GUI tool that requires that your workstation support the X Window System. Depending on your system configuration, you may need to use the ssh -X option to enable X Window System support in your shell session. In some cases you may even need to enter a command like xhost + in order to enable X Window System hosting on your workstation.

NOTES

The perftools-base module must be loaded before you can use Cray Apprentice2. This module provides access to man pages, utilities such as Cray Apprentice2, pat_help, and grid_order, and the instrumentation modules. This module does not affect program behavior and can be left loaded when not collecting performance data.

To use Cray Apprentice2 to trace calls down to the source file line level, you must either have the original source files available in the same path as they were in when you compiled the program, or else you must remap the paths to the original files. The method for remapping source file paths is documented in the help system.

CAUTION

Cray Apprentice2 can display an enormous amount and variety of data, but it is completely dependent on the options you selected when you instrumented the program and the runtime environment variables you specified when you executed the instrumented executable. If your reports do not seem to show the details you expect, check the environment variable PAT_RT_SUMMARY. If this variable is set to a nonzero value, the data captured during program execution is summarized and aggregated when it is saved, and fine-grain details do not show up in Cray Apprentice2. (Note that if you use pat_run, you can use its option -t to set this environment variable to 1.)

For more information about PAT_RT_SUMMARY and other environment variables, see the intro_craypat(1) man page.

EXAMPLES

Example 1: Visualizing Callstack Sampling

This example describes the steps needed to instrument a simple program, conduct a performance analysis experiment, and examine the results.

Load the perftools-base module, then load the desired instrumentation module. The perftools-base module does not alter program behavior, but provides access to man pages, Cray Apprentice2, and the instrumentation modules. An instrumentation module must be loaded before the program is compiled.

Compile the program and pause before linking. This preserves the .o and .a files.

$ ftn -c mpptest.f

Link the program.

$ ftn -o mpptest mpptest.o

Instrument the program for a performance analysis experiment. For example, to trace all MPI calls and user-defined functions in your program and specify that the resulting data should be saved in an .ap2 format file, enter this command:

$ pat_build -u -g mpi mpptest

This produces an instrumented copy of the executable named mpptest+pat. Set the environment variable PAT_RT_SUMMARY to turn off data summarization.

$ export PAT_RT_SUMMARY=0

Execute the instrumented executable. For example, to run the program on 16 PEs, enter this command:

$ srun -n 16 mpptest+pat

This produces a data file containing the performance information captured during program execution and named mpptest+pat+PID.xf. Process the raw data collected during execution for viewing through Cray Apprentice2:

$ pat_report mpptest+pat+PID.xf > my_report

This produces a data file, mpptest+pat+PID.ap2, that is ready to view in Cray Apprentice2. Launch the Cray Apprentice2 application.

$ app2

Use the Cray Apprentice2 GUI to navigate to the directory containing the .ap2 data file. Open the file, and explore and examine the performance analysis data that you have collected. The actual information contained in the resulting data file will vary depending on your choice of pat_build options and runtime environment variables.

ENVIRONMENT VARIABLES

JMAN_CPU_SECONDS_MAX

Sets the maximum time in seconds that Cray Apprentice2 will sit idle, waiting for user input, before timing out and exiting with the message, Error 2! Server exited abnormally.

Default: 7200 (2 hours)