Intel® Trace Collector 9.1 Update 2 User and Reference Guide

Tracing User Defined Events

If you wish to get more detailed information about your application, you can instrument and trace various user-defined events in your application, including non-MPI function calls. In practice, it is often useful to record entries and exits to/from functions or code regions within larger functions.

Use the following Intel® Trace Collector capabilities:

Automatic Function Instrumentation

Using Intel® Compilers

Intel® compilers can automatically instrument all user functions during compilation. At runtime, Intel® Trace Collector will record all function entries and exits in those compilation units.

To enable the instrumentation, use the option -tcollect (Linux* OS) or /Qtcollect (Windows* OS) during compilation. For example:

$ mpiicc -tcollect -trace myapp.c

The option accepts an argument to specify the collecting library to link against (see Product Components). For example, for fail-safe tracing select libVTfs as follows: -tcollect=VTfs (VT by default).

To define a particular set of functions to be instrumented, use the -tcollect-filter <file> option. <file> contains a list of functions followed by on|off switcher:

func1 on
func2 off

If a function is marked off, it will not be instrumented.

Using GCC*

Similar function tracing is available in the GNU Compiler Collection (gcc*). Object files that contain functions for tracing are compiled with -finstrument-functions, for example:

$ mpicc -finstrument-functions -trace myapp.c

Intel® Trace Collector should be able to obtain output about functions in the executable. By default, this is done by starting the shell program nm -P, which can be changed with the NMCMD configuration option. See NMCMD.

Folding

Function tracing can generate large amounts of trace data. Use folding to disable tracing of calls within certain functions. It enables you to reduce the trace file size and get information only about events of interest. See Tracing Library Calls for details.

C++ Name Demangling

By default Intel® Trace Collector records function names in their mangled form. The DEMANGLE configuration option enables automatic demangling of C++ names. See DEMANGLE.

Manual Source Code Instrumentation

Intel® Trace Collector provides the API that enables you to control the profiling library and trace user-defined functions, define groups of processes, define performance counters and record their values. All API functions, parameters and macros are declared in the header files VT.h and VT.inc for C/C++ and Fortran, respectively. Include the appropriate header file in your source code when using the Intel® Trace Collector API functions.

Refer to the Intel® Trace Collector API section for detailed description and usage information on the Intel® Trace Collector API.

To compile an application with calls to the Intel® Trace Collector API, pass the header files to the compiler using the -I option. For example: -I$VT_ROOT/include.

Using the Dummy Libraries

If you wish to temporarily disable tracing for the application with calls to the Intel® Trace Collector API, you can use the dummy library libVTnull available in the libraries folder. This way you will not have to remove the API function calls from the source code to run your application without tracing. For instructions on linking, see Tracing Conventional MPI Applications.