User Guide

Intel® VTune™ Profiler User Guide

ID 766319
Date 11/07/2023
Public

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

Document Table of Contents

Import Results from Command Line

You can collect performance data remotely with the Intel® VTune™ Profiler collectors (for example, SEP collector or Intel SoC Watch collector) or Linux* Perf* collector, import this data to the VTune Profiler project, and view the data in the graphical or command line interface. Use the import action to import data collection files. Currently the following data formats are supported:

  • *.tb6/*.tb7 (sampling raw data files collected with the low-level SEP collector)
  • *.perf (Perf data files)
  • *.csv ( External Data Import files in the predefined format)
  • *.pwr (processed Intel SoC Watch files with energy analysis data)

Prerequisites for Importing a *.perf File

To import a *.perf file with hardware event-based sampling data collected by the Linux* Perf tool, make sure to run the Perf collection with the predefined command line options:

  • For application analysis:

    $ perf record -o <trace_file_name>.perf -call-graph dwarf -e cpu-cycles,instructions <application_to_launch>

  • For process analysis:

    $ perf record -o <trace_file_name>.perf -call-graph dwarf -e cpu-cycles,instructions <application_to_launch> -p <PID> sleep 15

where the -e option is used to specify a list of events to collect as -e <list of events>; -call-graph option (optional) configures samples to be collected together with the thread call stack at the moment a sample is taken. See Linux Perf documentation on possible call stack collection options (for example, dwarf) and its availability in different OS kernel versions.

NOTE:

The Linux* kernel exposes Perf API to the Perf tool starting from version 2.6.31. Any attempts to run the Perf tool on kernels prior to this version lead to undefined results or even crashes. See Linux Perf documentation for more details.

Import Performance Profiler results and view data

  1. Copy the result directory to your local system.
  2. Use the import action to import the required file, setting the imported result directory as a search directory:

    vtune -import <result_path> -source-search-dir <search_path> -r <result_dir>

    If you do not use the result-dir option, the VTune Profiler creates a new directory with the default name in the current working directory.

    NOTE:

    To import a CSV file with external data, use the -result-dir option and specify the name of an existing directory of the result that was collected by the VTune Profiler in parallel with the external collection. VTune Profiler adds the externally collected statistics to the result and provides integrated data in the Timeline pane.

  3. You can use the command line to display the imported result in the VTune Profiler GUI, or generate a report to view it.
    • In the GUI:

      vtune-gui <result_dir>/<result>.vtune

    • In the CLI:

      vtune -report <report_type> -result-dir <result_dir>/<result>.vtune

    NOTE:
    • Use the search-dir action-option to specify symbol and binary files locations for module resolution.

    • For Linux targets, make sure to generate the debug information for your binary files using the -g option for compiling and linking. This enables the VTune Profiler to collect accurate performance data.

    • To minimize the size of the result, you may use the discard-raw-data action-option, but this will prevent re-finalizing the result.

    • Imported result files may not have all the fields that are present in the VTune Profiler result files, so some types of data may be missing from the report.

Import energy analysis results and view data

Run the following command to create a VTune Profiler project with the Intel SoC Watch trace data:

vtune –import <path_to_file> -result-dir <project_folder>

where <project_folder> is the VTune Profiler project directory, for example, r001, or the full path to the result directory, for example, on Linux: /root/intel/vtune/projects/my_project/r001

NOTE:
  • <project_folder> must be a non-existing folder, or you will get an error.

  • The energy analysis data file has an extension of .pwr.

You may include a path with the project name to create the project in a directory other than the current directory.

VTune Profiler should start up and automatically open your project in the Platform Power Analysis viewpoint.

Examples

This command imports the /home/import/r001.tb6 data collection file on Linux, searching the same directory for binary and symbol information. The result is output to the current working directory.

vtune -import /home/Import/r001.tb6 -search-dir /home/import/r001hs

Generate the callstacks report from the imported r001hs Hotspots result, searching the /home/import/r001hs directory for binary and symbol information.

vtune -report callstacks -result-dir /home/import/r001hs -search-dir /home/import/binaries