Cray Apprentice2 is a post-processing performance data visualization tool. After you use pat_hwpc or pat_build to instrument a program for a performance analysis experiment, execute the instrumented program, and generate one or more performance analysis data files, use Cray Apprentice2 to explore the experiment data and generate a variety of interactive graphical reports.
Cray Apprentice2 supports the following options:
| --limit tag_count | If you don't want to read in entire data files, you can launch Cray Apprentice2 using the --limit option to specify the maximum number of tags to be read in, which is tag_count. This option recognizes the K, M, and G abbreviations for kilo, mega, and giga; therefore, to limit Cray Apprentice2 to reading in three million tags, enter: app2 --limit 3M | |
| --limit_per_pe tag_count | The --limit option is an aggregate value for the entire program. When working with distributed processing programs this can produce misleading results, as it exaggerates the time spent and activity occurring on the lower-ranked processors. The --limit_per_pe option is identical to the --limit option, except that it causes Cray Apprentice2 to read in the specified amount of data for each processing element, thus preserving data parallelism. | |
| data_files | Depending on the experiment being conducted, CrayPat may generate a single data file or a directory full of data files, in either .xf (CrayPat native) or .ap2 (Cray Apprentice2 native) formats. In addition, pat_report may be used to convert CrayPat output files into .xml or .ap2 format files. Cray Apprentice2 can read in either single data files or entire directories of data files, in either .ap2, .xml, or .xml.gz (gzipped XML) formats. If desired, you may specify the name of the file or directory to be read in on the app2 command line. Alternately, you may skip specifying the data files or directory on the command line and instead select the data to work with later, through the Cray Apprentice2 GUI.
|
Cray Apprentice2 includes an online 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.
The Cray Apprentice2 module must be loaded before you can use Cray Apprentice2. The CrayPat module is required when instrumenting programs and running performance analysis experiments, but is not required when using Cray Apprentice2.
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.
Cray Apprentice2 can display an enormous amount and variety of data, but it is dependent on the options you selected when you instrumented the program and the runtime environment variables you specified when you executed the instrumented program. If your reports do not seem to show the details you expect, check the PAT_RT_SUMMARY environment variable. If this variable is set to a nonzero value, the data captured during program execution will be summarized and aggregated when it is saved and details will never show up in Cray Apprentice2.
For more information about PAT_RT_SUMMARY and other environment variables, see the pat(1) man page.
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 CrayPat module. The CrayPat module must be loaded before the program is compiled.
% module load craypat |
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 -A -u -g mpi mpptest |
This produces an instrumented copy of the executable named mpptest+pat.
Set the PAT_RT_SUMMARY environment variable to turn off data summarization.
% setenv PAT_RT_SUMMARY 0 |
Execute the instrumented program. For example, to run the program on 16 PEs, enter this command:
% yod -size 16 mpptest+pat |
This produces a data file containing the performance information captured during program execution and named program_name+pat+PID.ap2.
Load the Cray Apprentice2 module.
% module load apprentice2 |
Launch the Cray Apprentice2 application.
% app2 |
Use the Cray Apprentice2 GUI to navigate to the directory containing the data file created in step 5. 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.
Note: If you do not specify the -A option when instrumenting the program, the data files created during program execution will be in .xf format. These files can be converted to .ap2 format using pat_report, as shown in this example: