ittapi 1.2.1

Python bindings to Intel Instrumentation and Tracing Technology (ITT) API.

ittapi

ittapi is a Python binding to Intel Instrumentation and Tracing Technology (ITT) API. It provides a convenient way to mark up the Python code for further performance analysis using performance analyzers from Intel like Intel VTune or others.

NOTE: For compatibility and smooth migration with earlier versions of Python bindings(itt-python), please replace import itt with import ittapi.compat as itt. For more details about ittapi.compat, visit ittapi.compat page.

ittapi supports following ITT APIs:

• Collection Control API
• Domain API
• Event API
• Id API
• String Handle API
• Task API
• Thread Naming API

Usage

The main goal of the project is to provide the ability to instrument a Python code using ITT API in the Pythonic way. ittapi provides wrappers that simplify markup of Python code.

import ittapi

@ittapi.task
def workload():
  pass

workload()

ittapi.task can be used as a decorator. In this case, the name of a callable object (workload function in this example) will be used as a name of the task and the task will be attributed to a default domain named 'ittapi'. If you want to change the default name and/or other parameters for the task (e.g. task domain), you can pass them as arguments to ittapi.task:

import ittapi

@ittapi.task('My Task', domain='My Task Domain')
def workload():
  pass

workload()

Also, ittapi.task returns the object that can be used as a context manager:

import ittapi

with ittapi.task():
    # some code here...
    pass

If the task name is not specified, the ittapi.task uses call site information (filename and line number) to give the name to the task. A custom name for the task and other task parameters can be specified via arguments for ittapi.task in the same way as for the decorator form.

Installation

ittapi package is available on PyPi and can be installed in the usual way for the supported configurations:

pip install ittapi

Build

The native part of ittapi module is written using C++20 standard, therefore you need a compiler that supports this standard, for example GCC-10 for Linux and Visual Studio 2022 for Windows.

Ubuntu 22.04

1. Install the compiler and Python utilities to build module:

   sudo apt install gcc g++ python3-pip
   

2. Clone the repository:

   git clone https://github.com/intel/ittapi.git
   

3. Build and install ittapi:

   cd python
   pip install .
   

Windows 10/11

1. Install Python 3.8+ together with pip utility.

2. Install Visual Studio 2022. Make sure that "Desktop development with C++" workload is selected.

3. Clone the repository

   git clone https://github.com/intel/ittapi.git
   

4. Build and install ittapi

   cd python
   pip install .
   

References

• Instrumentation and Tracing Technology APIs
• Intel® VTune™ Profiler User Guide - Task Analysis
• Intel® Graphics Performance Analyzers User Guide - Instrumentation and Tracing Technology API Support