User Guide

Contents

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
. For example:
Runtime Overhead / Analysis
Survey
Trip Counts & FLOP
Roofline
Dependencies
MAP
Target application runtime with
Intel Advisor
compared to runtime without
Intel Advisor
1.1x longer
3 - 8x longer
3.1 - 8.1x 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.
This section contains details on using the Intel® Instrumentation and Tracing Technology (ITT) API to minimize analysis overhead. You can find the ITT API documentation at https://github.com/intel/ittapi.

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 Advisor
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();

Pause Collection/Resume Collection Using API Methods

Minimize collection overhead.
Applicable analyses:
Roofline,
Survey,
Trip Counts and FLOP
.
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
    • 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>\include
      • Fortran:
        <install-dir>\include\ia32
        or
        <install-dir>\include\ia64
      • Microsoft Visual Studio* IDE:
        Project Properties
        C/C++ | Fortran
        General
        Additional Include Directories
        .
    • Add
      <install-dir>\lib32
      or
      <install_dir>\lib64
      to your LIBRARIES path.
      Visual Studio IDE:
      Project Properties
      C/C++ | Fortran
      General
      Additional Include Libraries
      .
  • 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 Intel Advisor control: Start Paused
    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:
  • Click the standard run control or the Intel Advisor control: Start Paused
    Start Paused
    control on the
    Workflow
    pane to run the desired analysis.
  • Use the
    advixe-cl
    CLI action
    --collect
    with or without the CLI action option
    --start-paused
    to run the desired analysis. For example:
    advixe-cl --collect=survey --project-dir=./myAdvisorProj -- ./bin/myTargetApplication
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
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.

Start Target Application With Collection Paused

Minimize collection overhead.
Applicable analyses: Survey,
Trip Counts and FLOP
.
Use when you do not want to analyze the early phase(s) of your target application, such as the initialization phase, but you want analysis in
ready mode
.
To implement, do one of the following:
  • Click the associated Intel Advisor control: Start Paused 
				  control on the
    Workflow
    pane to run the desired analysis.
  • Use the
    advixe-cl
    CLI action option
    -start-paused
    when you run the desired analysis. For example:
    advixe-cl --collect=survey --project-dir=./myAdvisorProj --start-paused -- ./bin/myTargetApplication
You can use different techniques to resume collection. The most common is
__itt_resume
.

Start Target Application With Collection Paused/Resume Collection After N Seconds

Minimize collection overhead.
Applicable analyses: Survey,
Trip Counts and FLOP
.
Use when...
  • You do not want to modify/recompile your target application.
  • You do not want to analyze the initialization phase of your target application.
  • You have a good idea of the time interval of interest, but pinpointing the exact beginning of the interesting part of your target application is not important.
  • The interesting part of your target application is more than a few loops.
To implement, do one of the following:
  • Enable the
    Project Properties
    Analysis Target
    [Name] Analysis
    Advanced
    Automatically resume collection after (sec)
    checkbox and supply the desired value.
    Click the standard run control on the
    Workflow
    pane to run the desired analysis. (Collection automatically starts in the paused state.)
  • Use the
    advixe-cl
    CLI action option
    --resume-after=<integer>
    when your run the desired analysis. For example:
    advixe-cl --collect=survey --project-dir=./myAdvisorProj --resume-after=30 -- ./bin/myTargetApplication
Use a value representing seconds in the GUI field and milliseconds in the integer argument.

Stop Collection After N Seconds

Minimize collection overhead.
Applicable analyses:
Roofline,
Survey,
Trip Counts and FLOP
, Dependencies, Memory Access Patterns.
This is the flip side of the
Start target application with collection paused
technique. Use when...
  • You do not want to modify/recompile your target application.
  • You do not want to analyze the end of your target application.
  • You have a good idea of the time interval of interest, but pinpointing the exact end of the interesting part of your target application is not important.
  • The interesting part of your target application is more than a few loops.
To implement, do one of the following:
  • Enable
    Project Properties
    Analysis Target
    [Name] Analysis
    Advanced
    Automatically stop collection after (sec)
    checkbox and supply the desired value.
    Click the standard run control on the
    Workflow
    pane to run the desired analysis.
  • Use the
    advixe-cl
    CLI action option
    --stop-after=<integer>
    when you run the desired analysis. For example:
    advixe-cl --collect=survey --project-dir=./myAdvisorProj --stop-after=30 -- ./bin/myTargetApplication
Use a value representing seconds in both the GUI field and integer argument.

Stop Collection

Minimize collection overhead.
Applicable analyses:
Roofline,
Survey,
Trip Counts and FLOP
, Dependencies, Memory Access Patterns.
Use when...
  • You do not want to modify/recompile your target application.
  • You do not want to analyze the end of your target application.
  • You can detect the time interval of interest based on target application output.
  • The interesting part of your target application is more than a few loops.
To implement, do one of the following:
  • Click the associated Intel Advisor control: Stop analysis and display result collected thus far 
				  control on the
    Workflow
    pane when running the desired analysis.
    If running a Dependencies or Memory Access Patterns analysis, use the
    Site Coverage
    bar to determine when all marked loops are analyzed at least once:
    Intel Advisor: Site coverage bar
  • Use the
    advixe-cl
    CLI action
    -command=stop
    when you run the desired analysis. For example:
    advixe-cl --command=stop --result-dir=./myAdvisorResult

Manually Pause Collection/Manually Resume Collection

Minimize collection overhead.
Applicable analyses: Survey,
Trip Counts and FLOP
.
Use when...
  • You can detect the time interval of interest based on target application output.
  • Your need to pause or resume is unplanned and spontaneous.
To implement, do one of the following to pause analysis data collection (the target application continues running, but analysis data collection stops):
  • Click the associated Intel Advisor control: Pause collection manually 
				  control on the
    Workflow
    pane when running the desired analysis.
  • Use the
    advixe-cl
    CLI action
    --command=pause
    when you run the desired analysis. For example:
    advixe-cl --command=pause --result-dir ./myAdvisorResult
Do one of the following to resume analysis data collection:
  • Click the associated Intel Advisor control: Resume collection 
				  control on the
    Workflow
    pane.
  • Use the
    advixe-cl
    CLI action
    --command=resume
    . For example:
    advixe-cl --command=resume --result-dir=./myAdvisorResult

Attach to Process/Detach from Process

Minimize collection overhead.
Applicable analyses: Survey,
Trip Counts and FLOP
without call stacks.
This technique is similar to the
Start target application with collection paused
technique, except you can attach to an already running process. This is particularly beneficial if:
  • The process is a service that runs forever.
  • The launching infrastructure is relatively complicated, such as a sequence of scripts that must be modified to embed a
    launch collection
    command.
GUI:
  1. Choose
    Project Properties
    Analysis Target
    [Name] Analysis
    > Launch Application
    drop-down list
    > Attach to Process
    .
  2. Disable the
    Inherit settings from Survey Hotspots Analysis Type
    checkbox.
  3. Choose the
    Process name
    or
    PID
    option and identify a process.
  4. Supply other information as desired and close the
    Project Properties
    dialog box.
  5. Click the standard run control on the
    Workflow
    pane to run the desired analysis.
CLI: Use the
advixe-cl
CLI action option
--target-pid=<unsigned integer>
or
--target-process=<string>
to attach to a process when running the desired analysis. For example:
advixe-cl --collect=survey --project-dir=./myAdvisorProj --result-dir=./myAdvisorResult --target-process=myProcess
Do one of the following to stop collecting analysis data on a process (the process continues running but analysis data collection stops):
  • Click the associated Intel Advisor control: Stop analysis and display result collected thus far 
				  control on the
    Workflow
    pane.
  • Use the
    advixe-cl
    CLI action
    --command=detach
    . For example:
    advixe-cl --command=detach --result-dir=./myAdvisorResult
  • Ensure call stacks are disabled (which is the default setting) if you run the
    Trip Counts and FLOP
    analysis:
    • Disable the
      Project Properties
      Analysis Target
      Trip Counts and FLOP Analysis
      Advanced
      Collect stacks
      checkbox.
    • Add the
      advixe-cl
      CLI action option
      --no-stacks
      to the
      --collect
      command, or simply omit a
      --stacks
      action option on the
      --collect
      command.
  • Using the
    advixe-cl
    CLI action
    --command=stop
    kills the process (which also stops analysis data collection).

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804