Intel® Advisor Help

collect

Run the specified type of analysis and collect data.

GUI Equivalent

See Intel Advisor Menus and Toolbars

Syntax

-collect=<string> [-action-option] [-global-option] [--] <target> [<target options>]

Arguments

<string> type of analysis to run.

survey

Survey the target (your executable application) and collect data about sites in the code that may benefit from parallelism. After examining parallelism candidate sites, annotate sites that deserve further investigation. Synonyms for the survey argument keyword are hotspots and top-down.

tripcounts

Collect about loop iterations statistics and add this data into survey report.

roofline

Special batch mode of data collection. It runs two analyses one by one. There are Survey Analysis and Trip Counts Analysis with FLOP respectively.

suitability

Collect suitability data by executing annotated code to analyze the proposed parallelism opportunities and estimate where performance gains are most likely.

dependencies

Collect Dependencies data from annotated code. Helps to predict and eliminate data sharing problems before adding parallelism. It is generally best to use an application with debug information to collect Dependencies data.

map

Collect memory access patterns information - data about memory access strides.

Default

None. You must specify the analysis type.

Modifiers

Action Options Description
-app-working-dir=<string>

Specify a directory where the application will be run.

-auto-finalize (default)

The collected data is finalized if this option is set. Default value is true.

-benchmark-sync | -no-benchmark-sync (default)

With this option enabled, only one of concurrently executing Advisor instances runs benchmarks. Consider using this option to get accurate Roofline Analysis results for MPI applications.

-callstack-flops | -no-callstack-flops (default)

This option is deprecated, use -stacks option instead.

-callstack-tripcounts | -no-callstack-tripcounts (default)

This option is deprecated, use -stacks option instead.

-data-limit=<integer> (500)

Limit the amount of raw data to be collected. This option is not applicable to hardware event-based analysis types.

-delete-tripcounts | -no-delete-tripcounts (default)

Enables removing old trip counts data when re-running survey analysis. Enabled when the binary changes to remove old data.

-d, -duration=<string>

Specify a duration for collection (in seconds). Required for system-wide collection. Can also be 'unlimited'.

-exclude-files=<string>

Specify the files that should be excluded from annotation scanning. This can be a comma-separated list. Used with --collect.

-executable-of-interest=<string>

Inspect an application that is not the starting application. For example: Inspect an application (identified in this field) called by a script (identified in the Application field).

-filter-by-scope (default) | -no-filter-by-scope

Enables filtering reported stack variables by scope: variables initialized inside the loop are considered as potential dependencies (warning), while variables initialized outside the loop are marked as dependencies (error). Filtering might increase data collection overhead.

-filter-reductions | -no-filter-reductions (default)

Enables reduction variables filtering. After enabling this option all potential reductions should be marked by specific diagnostic. Filtering might increase data collection overhead.

-flop | -no-flop (default)

If -flop is passed, Intel Advisor collects data about floating-point operations, L1 memory traffic, and mask utilization metric for Intel AVX-512 platforms.

-flops-and-masks | -no-flops-and-masks (default)

This option is deprecated, use -flop option instead.

-ignore-app-mismatch | -no-ignore-app-mismatch (default)

Use to ignore mismatched target or application parameters errors.

-ignore-checksums | -no-ignore-checksums (default)

Use to ignore mismatched modules checksums before starting collections.

-interval=<integer> (10)

Specifies the amount of time to wait before collecting each sample.

-loop-call-count-limit=<integer> (0)

Maximum number of instances analyzed for each loop. If value is 0, then analyze all loop instances.

-loops=<string>

Intel Advisor will automatically select for deeper analysis some loops from the Survey report. You can analyze the selected loops with memory access patterns and dependencies tools. You must specify at least one selection criteria (see below).

Usage:

 --loops="criteria1,criteria2,criteria3"
<criteria> might be any of the following:

  • scalar - scalar serial loops only
  • total-time>N - above N% of the total CPU time only
  • has-source - exclude loops without source location
  • has-issue - with "Vector Dependence Prevent Vectorization" compiler diagnostic only (for dependencies) or with "Possible Inefficient Memory Access Pattern" issue only (for map).
  • loop-height=N - selects loops according to the hierarchical position: innermost loops have loop-height=0
-mark-up (default) | -no-mark-up

Use the -no-mark-up option to use source annotations only. By default, mark-up is enabled. Used with --collect for map and dependencies collections.

-mark-up-list=<string>

Use for specifying loops for deeper analysis by map or dependencies collections: --mark-up-list=N1,N2,N3, where "Nx" is a loop's ID from survey report.

-mkl-user-mode (default) | -no-mkl-user-mode

Select to show MKL loops and functions in Advisor reports.

-module-filter=<string>

Specify application (or child application) module(s) to include in or exclude from inspection.

-module-filter-mode=include | exclude (exclude)

Potentially speed up collection by limiting application (or child application) module(s) for inspection. Include only the following module(s)/include = limit by inclusion. Exclude the following module(s)/exclude = limit by exclusion.

-mrte-mode=auto | native | mixed | managed (auto)

Select a profilig mode. The Native mode does not attribute data to managed source. The Mixed mode attributes data to managed source where appropriate. The Managed mode tries to limit attribution to managed source when available.

-option-file=<string>

Specify the PATH/name of an option file. Can be used to avoid typing many options.

-profile-python | -no-profile-python (default)

Select to show Python loops and functions in Advisor reports.

-project-dir=<string>

Designate the project directory. This is the top-level directory where the data collections will be saved.

-record-mem-allocations (default) | -no-record-mem-allocations

Select to report heap allocated variables for which access strides were detected. Selecting this checkbox may increase analysis overhead.

-record-stack-frame (default) | -no-record-stack-frame

Select to report stack variables for which access strides were detected. Selecting this checkbox may increase analysis overhead.

-refinalize-survey | -no-refinalize-survey (default)

Refinalize survey result collected with a previous Advisor version.

-resume-after=<integer>

Specify time (in milliseconds) to delay data collection after the application starts. This option implicitly sets -start-paused. Available only for Survey and Suitability.

-return-app-exitcode | -no-return-app-exitcode (default)

Return the target exit code instead of the command line interface exit code.

-search-dir=<string>

<all | bin | src | sym[:<p | r>]>=<directory>. <directory> is the name of the search directory for binaries (bin), sources (src), symbols (sym), or all these file types (all). Use ':r' to perform a recursive search of all subdirectories. Use ':p' to indicate highest priority search directories (directories that should be searched prior to others, including environment paths and absolute paths). You can use these options together as ':rp'.

-spill-analysis | -no-spill-analysis (default)

This option enables register flow analysis that calculates the amount of consecutive load/store operations in registers and related memory traffic in bytes.

-stack-stitching (default) | -no-stack-stitching

Restructure the call flow to attach stacks to a point introducing a parallel workload.

-stacks | -no-stacks (default)

Enable advanced collection of call stacks.

-stackwalk-mode=online | offline (offline)

Choose between online (during collection) and offline (after collection) modes to analyze stacks. Offline mode reduces analysis overhead and is typically recommended.

-start-paused

Start data collection paused.

-static-instruction-mix | -no-static-instruction-mix (default)

This option enables the instruction mix analysis, which statically calculates the number of specific instructions present in the binary.

-stop-after=<integer> (0)

Set the duration of data collection in seconds starting from the target run.

-strategy=<string>

Specify details for parent and child processes analysis.

Format:<process_name1>:<profiling_mode>,<process_ name2>:<profiling_mode>,... Available profiling mode values are: trace:trace, trace:notrace, notrace:notrace, notrace:trace.

-support-multi-isa-binaries | -no-support-multi-isa-binaries (default)

If checked, Intel Advisor collects the following data for loops that reside in non-executed code paths:

  • loop assembly
  • instruction set architecture
  • vector length, and so on
The feature is available only for the binaries compiled using the Intel Compiler with the -ax option specified.

-target-pid=<unsigned integer>

Attach collection to a running process specified by process ID.

-target-process=<string>

Attach collection to a running process specified by process name.

-trace-mode=full | linear | fibo

Specify how to trace loop iterations (map collection only).

-trace-mpi | -no-trace-mpi

Configure collectors to trace MPI code, and determine MPI rank IDs in case of a non-Intel MPI library implementation.

-track-stack-variables (default) | -no-track-stack-variables

Enables parallel data sharing analysis for stack variables. Might increase data collection overhead if selected.

-trip-counts (default) | -no-trip-counts

If checked, Intel Advisor collects data about loops trip counts

Global Options Description
-q, -quiet

Suppress non-essential messages

-v, -verbose

Print additional information

Description

Use the collect action to run the specified type of analysis. Before performing an analysis, see Targets.

Example

1) Survey the application to determine hotspots.

advixe-cl --collect survey --project-dir ./advi --search-dir src:r=./src -- ./bin/myApplication

2) Collect memory access patterns data with specified loops for analysis.

advixe-cl --collect map --mark-up-list=5,10,12 --project-dir ./advi --search-dir src:r=./src -- ./bin/myApplication

3) Collect survey data on 4 nodes of MPI cluster into the shared ./advi project directory.

mpirun -n 4 advixe-cl --project-dir ./advi --collect survey
-- <PATH>/mpi-sample/1_mpi_sample_serial

4) Collect dependencies data for all loops that are both innermost and hold above 2% of the total CPU time.

advixe-cl --collect dependencies --project-dir ./advi --loops="loop-height=0,total-time>2" -- ./bin/myApplication

See Also