Instrumentation and Tracing Technology (ITT) API Reference Collector

This is a reference implementation of the ITT API dynamic part that performs tracing data from ITT API function calls to log files.

To use this solution, build the collector as a shared library and point the full library path to the INTEL_LIBITTNOTIFY64 environment variable.

Building

There are two ways to build the ITT API reference collector shared library.

Standalone — run this single CMake build command from this directory (the library is written into the ./build directory):

cmake -B build && cmake --build build --config Release

From the ittapi repository — use the buildall.py script in the repository root (the library is written into the build_linux/bin or build_win/bin directory):

python buildall.py --refcol

Resulting library name:

Usage

Point the INTEL_LIBITTNOTIFY64 environment variable to the full path of the library you built above (adjust the path to your build directory).

On Linux

export INTEL_LIBITTNOTIFY64=<build_dir>/libittnotify_refcol.so

On Windows

set INTEL_LIBITTNOTIFY64=<build_dir>\libittnotify_refcol.dll

By default, log files are saved in the current working directory. To change the location, use the INTEL_LIBITTNOTIFY_LOG_DIR environment variable:

On Linux

export INTEL_LIBITTNOTIFY_LOG_DIR=<log_dir>

On Windows

set INTEL_LIBITTNOTIFY_LOG_DIR=<log_dir>

This implementation adds logging of some of the ITT API function calls. Adding logging of other ITT API function calls is welcome. The solution provides 4 functions with different log levels that take printf format for logging:

LOG_FUNC_CALL_INFO(const char *msg_format, ...);
LOG_FUNC_CALL_WARN(const char *msg_format, ...);
LOG_FUNC_CALL_ERROR(const char *msg_format, ...);
LOG_FUNC_CALL_FATAL(const char *msg_format, ...);

JSON format trace generation

As an alternative to the default text log, the collector can produce a trace in JSON format (Perfetto). This mode is disabled by default.

To enable it, set the INTEL_LIBITTNOTIFY_GEN_JSON environment variable to 1:

On Linux

export INTEL_LIBITTNOTIFY_GEN_JSON=1

On Windows

set INTEL_LIBITTNOTIFY_GEN_JSON=1

When enabled, the collector writes a libittnotify_refcol_<timestamp>.json file into the log directory. The file can be opened directly in the Perfetto UI.