Interoperability with Other Tools through -gtool

To simplify interoperability with other analysis tools, Intel® MPI Library provides the -gtool option (also available as the I_MPI_GTOOL environment variable). By using the -gtool option you can analyze specific MPI processes with such tools as Intel® VTune™ Amplifier XE, Intel® Advisor, Valgrind* and other tools through the mpiexec.hydra or mpirun commands.

Without the -gtool option, to analyze an MPI process with the VTune Amplifier, for example, you have to specify the relevant command in the corresponding argument set:

$ mpirun -n 3 ./myprog : -n 1 amplxe-cl -c advanced-hotspots -r ah -- ./myprog

The -gtool option allows you to specify a single analysis command for all argument sets (separated by colons ':') at once. Even though it is allowed to use -gtool within a single argument set, it is not recommended to use it in several sets at once and combine the two analysis methods (with -gtool and argument sets).

For example, to analyze processes 3, 5, 6, and 7 with the VTune Amplifier, you can use the following command line:

$ mpirun -n 8 -gtool "amplxe-cl -collect hotspots -r result:3,5-7" ./myprog

The -gtool option also provides several methods for finer process selection. For example, you can easily analyze only one process on each host, using the exclusive launch mode:

$ mpirun -n 8 -ppn 4 -hosts node1,node2 -gtool "amplxe-cl -collect hotspots -r result:all=exclusive" ./myprog

You can also use the -gtoolfile option to specify -gtool parameters in a configuration file. All the same rules apply. Additionally, you can separate different command lines with section breaks.

For example, if gtool_config_file contains the following settings:

env VARIABLE1=value1 VARIABLE2=value2:3,5,7-9; env VARIABLE3=value3:0,11
env VARIABLE4=value4:1,12

The following command sets VARIABLE1 and VARIABLE2 for processes 3, 5, 7, 8, and 9 and sets VARIABLE3 for processes 0 and 11, while VARIABLE4 is set for processes 1 and 12:

$ mpirun -n 16 -gtoolfile gtool_config_file a.out

Using -gtool for Debugging

The -gtool runtime option can help you with debugging, when attaching to several processes at once. Instead of attaching to each process individually, you can specify all the processes in a single command line. For example:

$ mpirun -n 16 -gtool "gdb:3,5,7-9=attach" ./myprog

The command line above attaches the GNU* Debugger (GDB*) to processes 3, 5, 7, 8 and 9.


Do not use the -gdb and -gtool options together. Use one option at a time.

See Also

Intel® MPI Library Developer Reference, section Command Reference > mpiexec.hydra > Global Options > gtool Options

For more complete information about compiler optimizations, see our Optimization Notice.
Select sticky button color: 
Orange (only for download buttons)