1. Quick start guide

1.1. The instrumentation package

1.1.1. Uncompressing the package

Extrae is a dynamic instrumentation package to trace programs compiled and run with the shared memory model (like OpenMP and pthreads), the message passing (MPI) programming model or both programming models (different MPI processes using OpenMP or pthrads within each MPI process). Extrae generates trace files that can be later visualized with Paraver.

The package is distributed in compressed tar format (e.g., extrae.tar.gz). To unpack it, execute from the desired target directory the following command:

gunzip -c extrae.tar.gz | tar -xvf -

The unpacking process will create different directories on the current directory (see Table 1.1).

Table 1.1 Package contents description

Directory	Contents
bin	Contains the binary files of the Extrae tool.
etc	Contains some scripts to set up environment variables and the Extrae internal files.
lib	Contains the Extrae tool libraries.
share/man	Contains the Extrae manual entries.
share/doc	Contains the Extrae manuals (pdf, ps and html versions).
share/example	Contains examples to illustrate the Extrae instrumentation.

1.2. Quick running

Note

There are several included examples in the installation package. These examples are installed in $EXTRAE_HOME/share/example and cover different application types (including serial/MPI/OpenMP/CUDA/etc.). We suggest the user to look at them to get an idea on how to instrument their application.

Once the package has been unpacked, set the EXTRAE_HOME environment variable to the directory where the package was installed. Use the export or setenv commands to set it up depending on the shell you use. If you use sh-based shell (like sh, bash, ksh, zsh, …), issue this command:

export EXTRAE_HOME=<DIR>

however, if you use csh-based shell (like csh, tcsh), execute the following command:

setenv EXTRAE_HOME <DIR>

where <DIR> refers where Extrae was installed.

Note

Henceforth, all references to the usage of the environment variables will be used following the sh format unless specified.

Extrae is offered in two different flavors: as a DynInst-based application, or stand-alone application. DynInst is a dynamic instrumentation library that allows the injection of code in a running application without the need to recompile the target application. If the DynInst instrumentation library is not installed, Extrae also offers different mechanisms to trace applications.

1.2.1. Quick running Extrae - based on DynInst

Extrae needs some environment variables to be setup on each session. Issuing the command:

source ${EXTRAE_HOME}/etc/extrae.sh

on a sh-based shell, or

source ${EXTRAE_HOME}/etc/extrae.csh

on a csh-based shell will do the work. Then copy the default XML configuration file [1] into the working directory by executing:

cp ${EXTRAE_HOME}/share/example/MPI/extrae.xml .

If needed, set the application environment variables as usual (like OMP_NUM_THREADS, for example), and finally launch the application using the ${EXTRAE_HOME}/bin/extrae instrumenter like:

${EXTRAE_HOME}/bin/extrae -config extrae.xml <PROGRAM>

where <PROGRAM> is the application binary.

1.2.2. Quick running Extrae - NOT based on DynInst

Extrae needs some environment variables to be setup on each session. Issuing the command:

source ${EXTRAE_HOME}/etc/extrae.sh

on a sh-based shell, or:

source ${EXTRAE_HOME}/etc/extrae.csh

on a csh-based shell will do the work. Then copy the default XML configuration file [1] into the working directory by executing:

cp ${EXTRAE_HOME}/share/example/MPI/extrae.xml .

and export EXTRAE_CONFIG_FILE as:

export EXTRAE_CONFIG_FILE=extrae.xml

If needed, set the application environment variables as usual (like OMP_NUM_THREADS, for example). Just before executing the target application, issue the following command:

export LD_PRELOAD=${EXTRAE_HOME}/lib/<LIB>

where <LIB> is one of the libraries listed under ${EXTRAE_HOME}/lib Table 1.2.

Table 1.2 Some of the available libraries in Extrae. Their availability depends upon the configure process.

Library	Application type
	Serial	MPI	OpenMP	pthread	SMPss	nanos/OMPss	CUDA	OpenCL	Java
libseqtrace	Yes
libmpitrace [2]		Yes
libomptrace			Yes
libpttrace				Yes
libsmpsstrace					Yes
libnanostrace						Yes
libcudatrace							Yes
libocltrace								Yes
javaseqtrace.jar									Yes
libompitrace [2]		Yes	Yes
libptmpitrace [2]		Yes		Yes
libsmpssmpitrace [2]		Yes			Yes
libnanosmpitrace [2]		Yes				Yes
libcudampitrace [2]		Yes					Yes
libcudaompitrace [2]		Yes	Yes				Yes
liboclmpitrace [2]		Yes						Yes

1.3. Quick merging the intermediate traces

Once the intermediate trace files (*.mpit files) have been created, they have to be merged (using the mpi2prv command) in order to generate the final Paraver trace file. Execute the following command to proceed with the merge:

${EXTRAE_HOME}/bin/mpi2prv -f TRACE.mpits -o output.prv

The result of the merge process is a Paraver tracefile called output.prv. If the -o option is not given, the resulting tracefile is called EXTRAE_Paraver_Trace.prv.

Footnotes

[1]	(1, 2) See section Extrae XML configuration file for further details regarding this file.

[2]	(1, 2, 3, 4, 5, 6, 7, 8) If the application is Fortran append an f to the library. For example, if you want to instrument a Fortran application that is using MPI, use libmpitracef instead of libmpitrace.