Intel® VTune™ Profiler User Guide

User Guide

Contents

Run VTune Profiler in a Container

Install a Docker* image with
Intel® VTune™
Profiler
 and profile native or Java* applications running inside the same container or outside the container.

Prerequisites

  • Configure a Docker image:
    1. For the pre-installed Intel® oneAPI Base Toolkit including
      VTune
      Profiler
      , you may pull an existing Docker image from the Docker Hub repository: 
      host> image=amr-registry.caas.intel.com/oneapi/oneapi:base-dev-ubuntu18.04
host> docker pull "$image"
    2. To enable profiling from the container and have all host processes visible from the container, run your Docker image with
      --pid=host
       as follows: 
      host> docker run --pid=host --cap-add=SYS_ADMIN --cap-add=SYS_PTRACE -it "$image"
      where the
      SYS_ADMIN
       value adds a capability to run hardware event-based sampling analysis; the
      SYS_PTRACE
       value enables user-mode sampling analysis.
  • To profile a target application running in the same container where
    VTune
    Profiler
     is installed, do the following:
    1. Copy your application to the running Docker container. For example: 
      host> docker cp /home/samples/matrix.tar 98fec14f0c08:/var/local
      where
      98fec14f0c08
       is your container ID.
    2. Compile your target in the container, if required.

Install and Run
VTune
Profiler
 in a Container

These steps are NOT required if you use a Docker image with pre-installed Intel oneAPI Base Toolkit.
  1. Install the command-line interface of
    VTune
    Profiler
     inside your Docker container.
    Make sure to select the
    [2] Custom installation
     >
    [3] Change components to install
     and de-select components that are not required in the container environment:
    [3] Graphical user interface
    and
    [4] Platform Profiler
    .
  2. After installation, set up environment variables for the
    VTune
    Profiler
    . For example, for
    VTune
    Profiler
     in Intel oneAPI Base Toolkit: 
    container> source /opt/intel/oneapi/vtune/version/env/vars.sh

Run Analysis for Your Container Target

Set up your analysis for a target running in the container, using the following supported target and analysis types:
Target Type
Analysis Type
  • Launch Application
  • Attach to Process
  • Profile System (not supported for Java* targets)
  • User-Mode Sampling Hotspots
  • Hardware Event-Based Sampling Hotspots
  • Microarchitecture Exploration
To run an analysis, enter:
vtune -collect <
analysis_type
> [
options
] -- [
container_target
]
For example: 
container> vtune -collect hotspots -knob sampling-mode=hw -- /home/samples/matrix

Run Analysis for Your Host Target

Set up your analysis for a target running on the host, using the following supported target and analysis types:
Target Type
Analysis Type
  • Attach to Process
  • Profile System (not supported for Java targets)
  • User-Mode Sampling Hotspots
  • Hardware Event-Based Sampling Hotspots
  • Microarchitecture Exploration
To run an analysis, enter:
vtune -collect <
analysis_type
> [
options
] -- [
host_target
]
For example: 
container> vtune -collect hotspots -target-process java
Known Issues:
  1. Issue:
     Function-level analysis is not available by default.
    VTune
    Profiler
     maps the samples to the binaries from user target app but it cannot resolve the functions because the binaries from the host are not available from the container.
    Solution:
     Run the Docker container with the mounted host folder containing the binaries and specify a search directory as an argument to the
    vtune
     command.
  2. Issue:
    VTune
    Profiler
     is run in the container by the root user while the app on the host is run by a non-root user. As a result, User-Mode Sampling Hotspots analysis fails to run with an error "
    Both target and VTune Profiler should be run by the same user
    ".
    Solution:
     Make sure the same user runs
    VTune
    Profiler
     in the container and the target app outside the container.

Product and Performance Information

1

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