Intel® Inspector User Guide for Windows* OS

ID 767798
Date 3/22/2024
Public

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

Document Table of Contents

Collecting Result Data from the Command Line

You can use the Intel Inspectorinspxe-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. 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.

TIP:
  • 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 command prompt window and use the following command to run the script that establishes Intel Inspector environment settings: C:\"Program Files (x86)"\Intel\oneAPI\setvars.bat.

  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=C:\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.

    NOTE:

    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=C:\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.