Intel® Inspector User Guide for Linux* OS

User Guide

  • 2021.4
  • 09/27/2021
  • Public Content
Contents

Collecting Result Data from the Command Line

You can use the
Intel Inspector
inspxe-cl
 command to perform analysis and collect data as a background or automated task, which is particularly useful when the estimated collection time is lengthy, or when you want analysis and report generation to be part of your regularly scheduled processes.
This documentation uses the terms
analysis
 and
data collection
 as synonyms for the same process. When you initiate analysis, there are
collectors
 that perform analysis based on your specified
analysis type
 or
knob
 values. The collected analysis data is packaged into a result.
The result is not directly viewable, but can be opened in the GUI or used to generate one or more kinds of reports. Some additional analysis occurs when reports are generated, so report generation may require source files in addition to the result.

Getting Started with Analysis on the Command Line

Here are the basic steps you would follow the first time you inspect your application for memory and threading issues.
  1. Set up your command line environment. See the following Process Example section for details.
  2. Invoke the
    inspxe-cl
     command with the
    collect
     action, specifying one of the lower-level memory error analysis types to inspect your application for memory issues.
  3. Next, use the
    collect
     action with one of the threading error analysis types to inspect your application for threading issues.
  4. After each analysis, you can read the Summary report, and then open your result for viewing in the GUI, or use the
    report
     action to generate a report from the analysis result.
  • Collections that use lower-level analysis types take less time to complete than collections that use higher-level analysis types, and provide more of an overview, which are two reasons why you generally want to begin testing with the lowest-level analysis types.
  • To duplicate an analysis performed in the
    Intel Inspector
     GUI: Use the
    Command Line
     button on the
    Analysis Type
     window panes to copy the exact command to the clipboard.

How the Collection Process Works

There are two actions that you can use to initiate analysis and data collection:
collect
 and
collect-with
. These actions are very similar, as both perform the same basic collection process. The
collect
 action provides a variety of predefined analysis types from which to select. If none of these predefined analysis types meet your specific needs, you can use the
collect-with
 action and specify your own knob options.
By default, the collection process:
  • Performs the specified type of analysis.
  • Collects data and writes it to a result file in a result directory.
  • Finalizes the result and generates a summary of all detected problems, writes the Summary to
    stdout
     and also saves it to an XML file in the result directory.
  • Creates a log for troubleshooting purposes, and saves it in the result directory.
  • Returns an exit code.

How to Perform Analysis on the Command Line

Here is a general example of how to perform analysis using the
inspxe-cl
 command tool.
  1. You can open a terminal and use the following commend to run the script that establishes
    Intel Inspector
     environment settings:
    source <install-dir>/inspxe-vars.sh
    For
    Intel® oneAPI HPC Toolkit
     or
    Intel® oneAPI IoT Toolkit
     installations, the script is named
    env\vars
     rather than inspxe-vars.
    Add the
    bin64
     (or
    bin32
    ) directory (located in the installation directory) to your PATH environment variable.
  2. To inspect the
    myApp
     application for memory leak problems, use the
    collect
     action with the
    mi1
     (
    Detect Leaks
    ) analysis type, and specify the search directory where all the source, binary and symbol files are stored.
    inspxe-cl
     -collect mi1 -search-dir all=
    /myProject
     -- myApp
    By default, the result is written to a result directory under the default current working directory. Assuming this is the first result directory, it will be named
    r000mi1
    . A Summary is sent to
    stdout
    , and saved in the result directory as
    inspxe-cl.xml
    .
    If you do not supply an absolute pathname for the application, system path environment settings are used to locate it.
  3. Next, inspect the
    myApp
     application for deadlock and data races, using the
    collect
     action with the
    ti2
     (
    Detect Deadlocks and Data Races
    ) analysis type, and specify the same search directories that you used for the memory analysis.
    inspxe-cl
    -collect ti2 -search-dir all=
    /myProject
     -- myApp
    By default, the result is written to a result directory under the current working directory. Assuming this is the first result directory, it will be named
    r000ti2
    . The summary is sent to
    stdout
    , and saved in the
    r000ti2
     result directory as
    inspxe-cl.xml
    .

Next Steps

  1. Review the Summary of detected problems in each of the
    inspxe-cl.xml
     files.
  2. If one of the summaries contains anything other than 0 new problems, you can enter
    inspxe-gui
     to launch the result in the standalone GUI so you can view details and have easy access to your code editor and other tools. You can also use the
    report
     action to generate a report.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.