About Instrumentation and Tracing Technology (ITT) APIs

The instrumentation and tracing technology (ITT) APIs provided by the Intel® VTune™Amplifier enables your application to generate and control the collection of trace data during its execution. ITT APIs have the following features:

  • Application performance overhead can be controlled based on the amount of traces that you collect.
  • Enables trace collection without recompiling your application.
  • Supports applications in C/C++ environments.
  • Automatically traces data from Microsoft DirectX* applications.
  • Automatically traces data from OpenGL* ES v1, v2, and v3 APIs on Android* OS applications.
  • Supports instrumentation for tracing application code.

This document describes how to add basic instrumentation to your application, and also includes examples of several advanced instrumentation topics.

User applications/modules linked to the static ITT API library do not have a runtime dependency on a dynamic library. Therefore, they can be executed without VTune Amplifier or other Intel® Parallel Studio XE tools.

To use the ITT APIs, do the following:

  1. Include ittnotify.h, located at <install_dir>\include, in your code.
  2. Insert __itt_* notifications in your code, in appropriate places.
  3. Link to the libittnotify.lib file located at <install_dir>\lib

<install_dir> is the Intel® VTune™Amplifier installation directory.

Note

The ITT APIs are a set of pure C/C++ functions. There are no Java or .NET APIs. If you need runtime environment support, you can use a JNI, or C/C++ function call from the managed code. If the collector causes significant overhead or data storage, you can pause the analysis to reduce the overhead.

Note

To be able to see user tasks in your results, enable the Analyze user tasks checkbox in analysis settings.

Unicode Support

All API functions that take parameters of type __itt_char follow the Windows OS unicode convention. If UNICODE is defined when compiling on a Windows OS, __itt_char is wchar_t, otherwise it is char. The actual function names are suffixed with A for the ASCII APIs and W for the unicode APIs. Both types of functions are defined in the DLL that implements the API.

Strings that are all ASCII characters are internally equivalent for both the unicode and the ASCII API versions. For example, the following strings are equivalent:

__itt_sync_createA( addr, "OpenMP Scheduler", "Critical Section", 0); 
__itt_sync_createW( addr, L"OpenMP Scheduler", L"Critical Section", 0); 

Conditional Compilation

For best performance in the release version of your code, use conditional compilation to turn off annotations. Define the macro INTEL_NO_ITTNOTIFY_API before you include ittnotify.h during compilation to eliminate all __itt_* functions from your code.

You can also remove the static library from the linking stage by defining this macro.

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