.. _cha:QuickStart: Quick start guide ================= .. _sec:QuickStartInstrumentationPackage: The instrumentation package --------------------------- .. _subsec:QuickStartInstrumentationPackageUncompress: Uncompressing the package ^^^^^^^^^^^^^^^^^^^^^^^^^ |TRACE| 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). |TRACE| 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: .. code-block:: sh gunzip -c extrae.tar.gz | tar -xvf - The unpacking process will create different directories on the current directory (see :numref:`tab:PackageDescription`). .. tabularcolumns:: |l|p{10cm}| .. table:: Package contents description :name: tab:PackageDescription +---------------+-----------------------------------------------------------+ | **Directory** | **Contents** | +===============+===========================================================+ | bin | Contains the binary files of the |TRACE| tool. | +---------------+-----------------------------------------------------------+ | etc | Contains some scripts to set up environment variables and | | | the |TRACE| internal files. | +---------------+-----------------------------------------------------------+ | lib | Contains the |TRACE| tool libraries. | +---------------+-----------------------------------------------------------+ | share/man | Contains the |TRACE| manual entries. | +---------------+-----------------------------------------------------------+ | share/doc | Contains the |TRACE| manuals (pdf, ps and html versions). | +---------------+-----------------------------------------------------------+ | share/example | Contains examples to illustrate the |TRACE| | | | instrumentation. | +---------------+-----------------------------------------------------------+ .. _sec:QuickStartQuickRunning: Quick running ------------- .. note:: There are several included examples in the installation package. These examples are installed in :file:`${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 :envvar:`EXTRAE_HOME` environment variable to the directory where the package was installed. Use the :command:`export` or :command:`setenv` commands to set it up depending on the shell you use. If you use sh-based shell (like :command:`sh`, :command:`bash`, :command:`ksh`, :command:`zsh`, *...*), issue this command: .. code-block:: sh export EXTRAE_HOME= however, if you use :command:`csh`-based shell (like :command:`csh`, :command:`tcsh`), execute the following command: .. code-block:: csh setenv EXTRAE_HOME where `` refers where |TRACE| was installed. .. note:: Henceforth, all references to the usage of the environment variables will be used following the :command:`sh` format unless specified. |TRACE| 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, |TRACE| also offers different mechanisms to trace applications. .. _subsec:RunningTraceDynInst: Quick running |TRACE| - based on DynInst ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |TRACE| needs some environment variables to be setup on each session. Issuing the command: .. code-block:: sh source ${EXTRAE_HOME}/etc/extrae.sh on a :command:`sh`-based shell, or .. code-block:: sh source ${EXTRAE_HOME}/etc/extrae.csh on a :command:`csh`-based shell will do the work. Then copy the default XML configuration file [#QUICKXML]_ into the working directory by executing: .. code-block:: sh cp ${EXTRAE_HOME}/share/example/MPI/extrae.xml . If needed, set the application environment variables as usual (like :envvar:`OMP_NUM_THREADS`, for example), and finally launch the application using the :command:`${EXTRAE_HOME}/bin/extrae` instrumenter like: .. code-block:: sh ${EXTRAE_HOME}/bin/extrae -config extrae.xml where `` is the application binary. .. _subsec:RunningTraceNOTDynInst: Quick running |TRACE| - NOT based on DynInst ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |TRACE| needs some environment variables to be setup on each session. Issuing the command: .. code-block:: sh source ${EXTRAE_HOME}/etc/extrae.sh on a :command:`sh`-based shell, or: .. code-block:: sh source ${EXTRAE_HOME}/etc/extrae.csh on a :command:`csh`-based shell will do the work. Then copy the default XML configuration file [#QUICKXML]_ into the working directory by executing: .. code-block:: sh cp ${EXTRAE_HOME}/share/example/MPI/extrae.xml . and export :envvar:`EXTRAE_CONFIG_FILE` as: .. code-block:: sh export EXTRAE_CONFIG_FILE=extrae.xml If needed, set the application environment variables as usual (like :envvar:`OMP_NUM_THREADS`, for example). Just before executing the target application, issue the following command: .. code-block:: sh export LD_PRELOAD=${EXTRAE_HOME}/lib/ where `` is one of the libraries listed in :numref:`tab:AvailableExtraeLIBS`. .. tabularcolumns:: |l|c|c|c|c|c|c|c|c|c| .. table:: Available libraries in |TRACE|. Their availability depends upon the configure process. :name: tab:AvailableExtraeLIBS +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | **Library** | **Application type** | +==============================+==========+=======+==========+===========+=========+===============+========+==========+========+ | | *Serial* | *MPI* | *OpenMP* | *pthread* | *SMPss* | *nanos/OMPss* | *CUDA* | *OpenCL* | *Java* | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libseqtrace | Yes | | | | | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libmpitrace [#FORTRAN]_ | | Yes | | | | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libomptrace | | | Yes | | | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libpttrace | | | | Yes | | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libsmpsstrace | | | | | Yes | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libnanostrace | | | | | | Yes | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libcudatrace | | | | | | | Yes | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libocltrace | | | | | | | | Yes | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | javaseqtrace.jar | | | | | | | | | Yes | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libompitrace [#FORTRAN]_ | | Yes | Yes | | | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libptmpitrace [#FORTRAN]_ | | Yes | | Yes | | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libsmpssmpitrace [#FORTRAN]_ | | Yes | | | Yes | | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libnanosmpitrace [#FORTRAN]_ | | Yes | | | | Yes | | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libcudampitrace [#FORTRAN]_ | | Yes | | | | | Yes | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | libcudaompitrace [#FORTRAN]_ | | Yes | Yes | | | | Yes | | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ | liboclmpitrace [#FORTRAN]_ | | Yes | | | | | | Yes | | +------------------------------+----------+-------+----------+-----------+---------+---------------+--------+----------+--------+ .. _sec:QuickMerging: Quick merging the intermediate traces ------------------------------------- Once the intermediate trace files (:file:`*.mpit` files) have been created, they have to be merged (using the :command:`mpi2prv` command) in order to generate the final |PARAVER| trace file. Execute the following command to proceed with the merge: .. code-block:: sh ${EXTRAE_HOME}/bin/mpi2prv -f TRACE.mpits -o output.prv The result of the merge process is a |PARAVER| tracefile called :file:`output.prv`. If the :option:`-o` option is not given, the resulting tracefile is called :file:`EXTRAE_Paraver_Trace.prv`. .. rubric:: Footnotes .. [#QUICKXML] See section :ref:`cha:XML` for further details regarding this file. .. [#FORTRAN] 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``.