Intel® MPI Library Developer Reference for Linux* OS

ID 768732
Date 6/24/2024
Public
Document Table of Contents

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.