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 in Table 1.2.

Table 1.2 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.