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.