Collection Controls to Minimize Analysis Overhead

Intel® Advisor User Guide

Download

ID 766448

Date 3/31/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-7C06E1C7-8E57-41CC-88E9-689AEAB95103

View Details

Collection Controls to Minimize Analysis Overhead

Issue

Running your target application with the Intel® Advisor can take substantially longer than running your target application without the Intel Advisor. Depending on an accuracy level and analyses you choose for a perspective, different overhead is added to your application execution time. For example:

Runtime Overhead / Analysis	Survey	Characterization	Dependencies	MAP
Target application runtime with Intel® Advisor compared to runtime without Intel® Advisor	1.1x longer	2 - 55x longer	5 - 100x longer	5 - 20x longer

Solutions

Use the following techniques to skip uninteresting parts of your target application, such as the initialization phase, and analyze only interesting parts.

Pause Collection/Resume Collection Using Annotations

Minimize collection overhead.

Applicable analyses: Survey, Dependencies.

Some analysis types recognize the structural annotations typically used in the Threading perspective workflow.

Use when:

Modifying/recompiling your target application is not an issue.
You do not want to analyze one or more uninteresting parts of your target application.
The interesting parts of your target application involve large workloads (because Pause/Resume API call frequency is about 1 Hz, and the operations pause and resume data collection in all processes in the analysis run, with the corresponding collection state notification to the GUI).

To pause collection, add the following annotation to your code:

C++: ANNOTATE_DISABLE_COLLECTION_PUSH
Fortran: call annotate_disable_collection_push()
C#: Annotate.DisableCollectionPush();

To resume collection, add the following annotation to your code:

C++: ANNOTATE_DISABLE_COLLECTION_POP
Fortran: call annotate_disable_collection_pop()
C#: Annotate.DisableCollectionPop();

NOTE:

C# and .NET support is deprecated starting Intel® Advisor 2021.1.

See Pause Collection and Resume Collection Annotations for more information.

Pause Collection/Resume Collection Using API Methods

Minimize collection overhead using the Intel® Instrumentation and Tracing Technology (ITT) API.

TIP:

For MPI applications, you can also use a standard MPI-specific function MPI_Pcontrol(<N>) to pause and resume data collection. This function requires no changes in the application building process, unlike the ITT API calls, which require linking of a static ITT API library. See Control Collection with an MPI_Pcontrol Function.

Applicable analyses: Survey, Characterization with Trip Counts or FLOP collection enabled.

Use when:

Modifying/recompiling your target application is not an issue.
You do not want to analyze one or more uninteresting parts of your target application.
The interesting parts of your target application involve large workloads (because Pause/Resume API call frequency is about 1 Hz, and the operations pause and resume data collection in all processes in the analysis run, with the corresponding collection state notification to the GUI).

Prerequisites:

Add the following statements to every source file you want to instrument:
- C/C++: ittnotify.h
- Fortran: USE ITTNOTIFY
NOTE:
- The ittnotify header file contains definitions of ITT API routines and important macros that provide the correct logic of API invocation from an application.
- The ITT API is designed to incur almost zero overhead when tracing is disabled. If you need completely zero overhead, you can compile out all ITT API calls from an application by defining the INTEL_NO_ITTNOTIFY_API macro in your project at compile time, either on the compiler command line or in your source file prior to including the ittnotify header file.
Configure your build system to reach ITT API header file and libraries, where <install-dir> is the Intel Advisor installation directory.
- Add the appropriate entry to your INCLUDE path:
  - C++: <install-dir>/sdk/include
  - Fortran: <install-dir>/sdk/include/lib32 or <install-dir>/sdk/include/lib64
  - Microsoft Visual Studio* IDE: Project Properties > C/C++ | Fortran > General > Additional Include Directories.
- Add <install-dir>/sdk/lib32 or <install-dir>/sdk/lib64 to your LIBRARIES path.
  
  Visual Studio IDE: Project Properties > C/C++ | Fortran > General > Additional Include Libraries.
NOTE:
The ITT API headers, static libraries, and Fortran modules previously located at <install-dir>/include and <install-dir>/[lib32 | lib64] folders were moved to the <install-dir>/sdk/include and <install-dir>/sdk/[lib32 | lib64] folder. Copies of these files are retained at their old locations for backward compatibility and these copies should not be used for new projects.
Link your target application to the static library libittnotify.a (Linux* OS) or libittnotify.lib (Windows* OS) by passing -littnotify to your compiler. If tracing is enabled, this static library loads the ITT API implementation and forwards ITT API instrument data to the Intel Advisor. If tracing is disabled, the static library ignores ITT API calls, providing nearly zero instrumentation overhead.

Visual Studio IDE: Project Properties > Linker > Input > Additional Dependencies
Insert _itt_pause (C/C++) or CALL ITT_PAUSE (Fortran) before uninteresting parts of your target application and the _itt_resume (C/C++) or CALL ITT_RESUME (Fortran) before interesting parts of your target application.

Example 1: The following snippet plus the standard run control collects analysis data twice - at the beginning and the middle of the snippet:
```
#include <ittnotify.h>
int main(int argc, char* argv[])
{
// Do work here
__itt_pause();
// Do uninteresting work here
__itt_resume();
// Do work here
__itt_pause();
// Do uninteresting work here
return 0;
}
```
Example 2: The following snippet plus the standard run control collects analysis data only once - in the middle of the snippet:
```
#include <ittnotify.h>
int main(int argc, char* argv[])
{
__itt_pause();
// Do uninteresting work here
__itt_resume();
// Do work here
__itt_pause();
// Do uninteresting work here
return 0;
}
```
Example 3: The following snippet plus the standard run control collects analysis data only once - at the end of the snippet:
```
#include <ittnotify.h>
int main(int argc, char* argv[])
{
__itt_pause();
// Do uninteresting work here
__itt_resume();
// Do work here
return 0;
}
```
Example 4: The following snippet plus the Start Paused control collects analysis data only once - at the end of the snippet:
```
#include <ittnotify.h>
int main(int argc, char* argv[])
{
// Do uninteresting work here
__itt_resume();
// Do work here
return 0;
}
```

After performing the prerequisites and recompiling, do one of the following:

Note: In the commands below, make sure to replace the myApplication with your application executable path and name before executing a command. If your application requires additional command line options, add them after the executable name.

Click the standard run control or the Start Paused control on the Analysis Workflow pane to run the desired analysis.
Use the advisor CLI action --collect with or without the CLI action option --start-paused to run the desired analysis. For example:
```
advisor --collect=survey --project-dir=./advi_results -- ./myApplication
```

To attach ITT APIs to a launched application, that is, to collect API data on an application that is already launched, point the target application to the ittnotify_collector library using an environment variable:

Windows* OS:

set INTEL_LIBITTNOTIFY32=<install_dir>\bin32\runtime\ittnotify_collector.dll

set INTEL_LIBITTNOTIFY64=<install_dir>\bin64\runtime\ittnotify_collector.dll
Linux* OS:

export INTEL_LIBITTNOTIFY32=<install_dir>/lib32/runtime/libittnotify_collector.so

export INTEL_LIBITTNOTIFY64=<install_dir>/lib64/runtime/libittnotify_collector.so

NOTE:

Use the full path to the library without quotations marks.

After you complete configuration, start the instrumented application in the correct environment. Intel® Advisor collects API data even if the application is launched before the Intel® Advisor is launched.

You can find the ITT API documentation at https://github.com/intel/ittapi.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Advisor User Guide

Collection Controls to Minimize Analysis Overhead

Issue

Solutions

Pause Collection/Resume Collection Using Annotations

Pause Collection/Resume Collection Using API Methods

Start Targ