gtool Options
-gtool
Use this option to launch such tools as Intel® VTune™ Amplifier XE, Intel® Advisor, Valgrind*, and the GDB* (GNU Debugger) for the specified processes through the mpiexec.hydra and mpirun commands. An alternative to this option is the I_MPI_GTOOL environment variable.
Syntax
-gtool "<command line for tool 1>:<ranks set 1>[=launch mode 1][@arch 1]; <command line for tool 2>:<ranks set 2>[=exclusive][@arch 2]; … ;<command line for a tool n>:<ranks set n>[=exclusive][@arch n]" <executable>
or:
$ mpirun -n <# of processes> -gtool "<command line for tool 1>:<ranks set 1>[=launch mode 1][@arch 1]" -gtool "<command line for a tool 2>:<ranks set 2>[=launch mode 2][@arch 2]" … -gtool "<command line for a tool n>:<ranks set n>[=launch mode 3][@arch n]" <executable>
In the syntax, the separator ';' and the -gtool option are interchangeable.
Arguments
| <arg> | Parameters |
| <rank set> | Specify the range of ranks that are involved in the tool execution. Separate ranks with a comma or use the '-' symbol for a set of contiguous ranks. To run the tool for all ranks, use the all argument.
NOTE:
If you specify incorrect rank index, the corresponding warning is printed and the tool continues working for valid ranks.
|
| [=launch mode] | Specify the launch mode (optional). See below for the available values. |
| [@arch] | Specify the architecture on which the tool runs (optional). For a given <rank set>, if you specify this argument, the tool is launched only for the processes residing on hosts with the specified architecture. This parameter is optional. |
NOTE:
Rank sets cannot overlap for the same @arch parameter. Missing @arch parameter is also considered a different architecture. Thus, the following syntax is considered valid: -gtool "gdb:0-3=attach;gdb:0-3=attach@hsw;/usr/bin/gdb:0-3=attach@knl"Also, note that some tools cannot work together or their simultaneous use may lead to incorrect results.
The following table lists the parameter values for [=launch mode]:
| [=launch mode] | Tool launch mode (optional). You can specify several values for each tool, which are separated with a comma ','. |
| exclusive | Specify this value to prevent the tool from launching for more than one rank per host. |
| attach | Specify this value to attach the tool from -gtool to the executable. If you use debuggers or other tools that can attach to a process in a debugger manner, you need to specify this value. This mode has been tested with debuggers only. |
| node-wide | Specify this value to apply the tool from -gtool to all ranks where the <rank set> resides or for all nodes in the case of all ranks. That is, the tool is applied to a higher level than the executable (to the pmi_proxy daemon). Use the -remote argument for ranks to use the tool on remote nodes only. |
NOTE:
The tool attached to an MPI process may be executed without having access to stdin. To pass input to it, run a rank under the tool directly, for example: -gtool "gdb --args:0"
Examples
The following examples demonstrate different scenarios of using the -gtool option.
Example 1
Launch the Intel® VTune™ Amplifier XE and Valgrind* through the mpirun command:
$ mpirun -n 16 -gtool "vtune -collect hotspots -analyze-system \ -r result1:5,3,7-9=exclusive@bdw;valgrind -log-file=log_%p:0,1,10-12@hsw" a.out
This command launches vtune for the processes that are run on the Intel® microarchitecture codenamed Broadwell. Only one copy of vtune is launched for each host, the process with the minimal index is affected. At the same time, Valgrind* is launched for all specified processes that are run on the Intel® microarchitecture codenamed Haswell. Valgrind's results are saved to the files log_<process ID>.
Example 2
Set different environment variables for different rank sets:
$ mpirun -n 16 -gtool "env VARIABLE1=value1 VARIABLE2=value2:3,5,7-9; env VARIABLE3=value3:0,11" a.out
Example 3
Apply a tool for a certain process through the -machinefile option.
In this example, suppose m_file has the following content:
$ cat ./m_file hostname_1:2 hostname_2:3 hostname_3:1
The following command line demonstrates how to use the -machinefile option to apply a tool:
$ mpirun -n 6 -machinefile m_file -gtool "vtune -collect hotspots -analyze-system \ -r result1:5,3=exclusive@hsw;valgrind:0,1@bdw" a.out
In this example, the use of -machinefie option means that processes with indices 0 and 1 are located on the hostname_1 machine, process 3 is located on the hostname_2 machine, and process 5 - on the hostname_3 machine. After that, vtune is applied only ranks 3 and 5 (since these ranks belong to different machines, the exclusive option matches both of them) in case if hostname_2 and hostname_3 machines have Intel® microarchitecture codenamed Haswell. At the same time, the Valgrind* tool is applied to both ranks allocated on hostname_1 machine in case if it has Intel® microarchitecture codenamed Broadwell.
-gtoolfile <gtool_config_file>
Use this option to specify the -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
NOTE:
The options and the environment variable -gtool, -gtoolfile and I_MPI_GTOOL are mutually exclusive. The options -gtool and -gtoolfile are of the same priority and have higher priority than I_MPI_GTOOL. The first specified option in a command line is effective and the second one is ignored. Therefore, use I_MPI_GTOOL if you do not specify -gtool or -gtoolfile.
Parent topic: mpiexec.hydra