Tracing User Defined Events

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 with the compiler
  • Manual source code instrumentation with Intel® Trace Collector API

Automatic Function Instrumentation

Using Intel® Compilers

Intel® compilers can automatically instrument all user functions during compilation. At runtime, Intel® Trace Collector records all function entries and exits in the 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 is not 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 obtains output about functions in the executable. By default, it starts the shell program nm -P to do this, 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

To temporarily disable tracing for the application with calls to the Intel® Trace Collector API, use the dummy library libVTnull available in the libraries folder. This way you do 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.

For more complete information about compiler optimizations, see our Optimization Notice.