itt-python

Includes Python bindings to instrumentation and tracing technology (ITT) APIs.

The ITT API is used by Intel(R) VTune(TM) Profiler, permitting user to control tracing and instrumentation that it performs.

Intel VTune Profiler works great on Python code. This package exposes some limited features of the ITT API in Python to help focus analysis. Right now it only has the collection and control API and some of the user task API.

Synopsis

Collection and Control

import itt
# ... uninteresting code
itt.resume()
# ... very interesting code
itt.pause()
# ... boring stuff again
itt.resume()
# ... interesting code
itt.detach()
# ... uninteresting code like writing output (sheesh)

Here one would actually run

> amplxe-cl -start-paused ... python script.py ...

So execution begins with collection paused and only the interesting code is profiled.

User Task Labels

import itt
# ... 
domain = itt.domain_create("domain")
itt.task_begin(domain, "awesome")
# ... do the awesome ...
itt.task_end(domain)

To get the user task labels into your VTune timeline you need to add enable-user-task knob

> amplxe-cl -collect hotspots -knob enable-user-tasks ... python script.py

Installation

This package leverages Intel(R) Instrumentation and Tracing Technology (ITT). This built-time dependency can be met by installing ittapi conda package, or by using ITT library vendored in the VTune installation.

Provide the build_ext step with the path to the root VTune install directory. For instance, on Linux:

export ITT_INCLUDE_DIR=$VTUNE_PROFILER_DIR/include
export ITT_LIBRARY_DIR=$VTUNE_PROFILER_DIR/lib64
python setup.py install

The build assumes:

$VTUNE_PROFILER_DIR/include
$VTUNE_PROFILER_DIR/lib64/libittnotify.a

If ittapi is installated in the build environment, e.g. conda install conda-forge::ittapi, the project can be built using simpler command:

python setup.py install

Functions

pause()

Run without collecting data. Reduces overhead from collection.

resume()

Resume data collection.

detach()

Detaches all collectors from all processes. Application continues to work but no data is collected for the running collection.

domain_create(name)

Create domain with the given name name. URI naming style is recommended. No mechanism to destroy domain (expected to be static over execution). Returns a domain, which is just a Capsule.

task_begin(domain, name)

Create task instance on a thread called name. Becomes current task instance for that thread. Call task_end() on same thread to end current task instance.

task_begin_fn()

Not implemented.

task_end(domain)

End a task instance on a thread.

ITT API for Anomaly Detection

itt_pt_region_create(name)

Create itt pt region with the given name name. URI naming style is recommended. No mechanism to destroy region (expected to be static over execution). Returns a region integer value

itt_pt_region_begin(region)

Create pt region instance instance on a thread. Becomes current pt region instance for that thread. Call itt_pt_region_end() on same thread to end current pt region instance.

itt_pt_region_end(region)

References

• Intel Developer Zone page on the ITT Collection Control API
• Performance Analysis of Python with Intel VTune Amplifier
• Intel Distribution for Python
• ITT Task API Reference

Related projects

Intel(R) Instrumentation and Tracing API project now provides Python bindings in pyitt package available on PyPI. It provides pyitt.compatibility_layers.itt_python submodule which fully implements the public API of itt-python.

Users of itt are advised to transition to using pyitt.

Thanks

• Sergey Maidanov and Vasilij Litvinov at Intel
• Rollin Thomas, Brian Friesen, and Brandon Cook at NERSC
• Parent repo of this fork: https://github.com/NERSC/itt-python