User Guide

Intel® VTune™ Profiler User Guide

ID 766319
Date 12/16/2022
Public

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

Document Table of Contents

Web Server Interface

Use Intel® VTune™ Profiler in a web server mode to get an easy on-boarding experience, benefit from a collaborative multi-user environment, and access a common repository of collected performance results.

The web server interface helps you quickly get started with the tool since you do not need to install VTune Profiler as a desktop application on every client system. You can use the VTune Profiler Server to configure and control analysis on arbitrary target systems and view collected results.

To run an analysis via a web interface:

  1. (Personal mode) Run the VTune Profiler Server to get a URL to access the web interface.

    (Reverse proxy/SAML SSO modes) Get the server URL from your admin.

  2. Access the server via the URL.

  3. Deploy the VTune Profiler Agent

  4. Select your target system:

  5. Run the analysis

To control VTune Profiler agents, use the Administrator Dashboard.

Run VTune Profiler Server

Prerequisite: VTune Profiler Server is installed with VTune Profiler GUI.

In the personal/evaluation usage mode, run the VTune Profiler Server as follows:

  1. Start the VTune Profiler Server:

    <vtune-install-dir>/bin64/vtune-backend

    If you want the VTune Profiler Server to access a specific TCP port, specify it with the --web-port option. For example:

    vtune-backend --web-port=8080

    VTune Profiler Server outputs a URL to access the GUI. For the first run, the URL includes a one-time token. For example:

    Serving GUI at https://127.0.0.1:64880?one-time-token=0160852eeff593e0ab0a0f90991b4efa

    Optionally, you can specify a working directory for VTune Profiler Server using the --data-directory option. For example:

    vtune-backend --web-port=8080 --data-directory="C:\vtune-results"
    NOTE:
    Additional command-line options are available to make the usage of VTune Profiler Server in containers more convenient. See Use VTune Profiler Server in Containers for details.

    VTune Profiler Server allows you to create a directory with a custom hierarchy, organized to best fit your needs. Once you point VTune Profiler Server to this directory using the --data-directory option, users will be able to access all projects and results, regardless of folder names and levels of nesting. This can be especially useful if you're using an HPC scheduler to regularly collect VTune Profiler performance data and put it into a shared folder on the network for later examination. For example, you can organize your results folder by users and their workloads:

    NOTE:
    • By default, access to the VTune Profiler Server is limited to the local host only. To enable access from remote client and target systems, restart the server with the --allow-remote-access option.
    • By default, server host profiling is not enabled. To enable the server host profiling, restart the server with the --enable-server-profiling option.

  2. Open the URL with the provided one-time token.

    NOTE:

    If you start the VTune Profiler Server in the personal/evaluation mode with no signed TLS certificate provided, your web browser warns you that the default self-signed server certificate is not trusted and asks for your confirmation to proceed.

  3. Set a passphrase in the Set Passphrase dialog box.

In the reverse proxy or SAML SSO usage modes, use the URL provided by your admin to access the VTune Profiler Server instance installed in a lab.

Deploy the VTune Profiler Agent

You can choose between automated and manual deployment of the VTune Profiler Agent.

Deploy the Agent automatically

NOTE:

VTune Profiler Server uses SSH for automated agent deployment. Running an SSH server on the target machine is required for automated deployment.

To deploy the Agent automatically:

  1. Enter the target machine username.

  2. Enter the credentials for target machine:

    • For Public key authentication, add your public SSH key to the authorized_keys file on the target system for the user account that you specify in the Username field. Then, select the Private key file on your client machine. If your private key is encrypted, specify the Private key passphrase.

    • Alternatively, switch to Password authentication and provide the username and password.
  3. Optionally, specify the deployment directory.

  4. Click the Deploy Agent button.

Deploy VTune Profiler Agent

Deploy the Agent manually

To deploy the Agent manually:

  1. Click the Download Agent Manually button In the WHERE pane of the Configure Analysis window or access the http://<VTune Profiler Server URL>/api/collection-agent/download URL to download the Agent.

    NOTE:

    You can use tools such as wget to download the Agent directly to the target system.

  2. Extract the Agent archive with your tool of choice and copy its contents to the target system.

  3. Run the vtune-agent executable on the target system and specify the agent owner using the -owner <vtune-user-id> option.

    NOTE:

    You can find your VTune Profiler user ID in the About dialog.

  4. Compare the Agent key fingerprint in the WHERE pane of the Configure Analysis window with the fingerprint printed out by the agent upon startup. If they match, click the Admit Agent button.

Shared Agents

You can run a shared VTune Profiler Agent. In this case, the Agent will be available to all users of an instance of VTune Profiler Server. This means that any user of this VTune Profiler Server instance will be able to run data collection using this agent. It is recommended to only run shared agents using dedicated faceless accounts.

To deploy a shared agent, check the Share the agent with all VTune Profiler users checkbox in the WHERE pane of the Configure Analysis dialog, or use the --shared command line option when deploying an agent manually.

Select a Client System

To profile a client system, which is the same machine that you use to access the VTune Profiler Server via a web browser, do the following:

  1. Click New Project and specify a name for the new project.

    VTune Profiler opens the project configuration with your localhost pre-selected as a target system.

  2. Configure your analysis target and analysis type.

Select a Remote System

To profile a remote target system, do the following:

  1. In the WHERE pane of the Configure Analysis window, click the down arrow to see available target systems.

  2. Select Add new remote target....

    NOTE:

    VTune Profiler maintains a list of used remote systems, if any, and displays it under Remote Targets.

  3. Enter the hostname or IP address.

Run the Analysis

Once the Agent is running, the Configure Analysis pane displays information that VTune Profiler is detecting the device configuration.

The Agent downloads the collectors and the target package, which is approximately 100MB in size. Once the target package is downloaded, the Agent analyzes the target system configuration and displays the applicable analysis types.

To run an analysis:

  1. Install the Intel sampling drivers manually by running these commands:

    On Windows* OS:

    <vtune-agent-dir>\bin64\amplxe-sepreg.exe

    On Linux* OS:

    <vtune-agent-dir>/sepdk/src/build-driver

    <vtune-agent-dir>/sepdk/src/insmod-sep

    The <vtune-agent-dir> is the <vtune_profiler_<version>> installation folder created on the client system by VTune Profiler.

  2. Configure your analysis target and analysis type.
  3. Click the Start button to run the analysis.

Analyze Process Running Under Arbitrary Account (Linux* OS)

VTune Profiler Server provides a way to analyze a process that is running under an arbitrary user account. A common example is analyzing a process in Attach to Process mode that was previously started under an arbitrary user account. The account running the process is not necessarily the same as the account the VTune Profiler Agent was deployed for.

To enable this functionality, provide the following wrapper script in the Advanced Options section of the WHAT pane:

#!/bin/sh
#Run VTune collector as the target process owner
sudo -C 65000 -A -u <target process owner> "$@"

The sudo command call runs the VTune Profiler collector under the account specified under <target process owner>. Replace this placeholder with the account name under which the target process is running.

If the target workload or the collector request a sudo elevation during the analysis, VTune Profiler Server requests this password interactively in the Web Interface:


NOTE:
  • The interactive sudo elevation requires that the VTune Profiler Agent is deployed under an account that has sudo privileges. To achieve that, ensure that the Username that you provide during deployment belongs to an account with sudo privileges.
  • VTune Profiler provides the password directly to the target system and does not store the password.

Control VTune Profiler Agents

The Administrator Dashboard feature of VTune Profiler Server enables you to monitor and manage one or multiple agents from a single point.

To open the Administrator Dashboard:

  1. Open the VTune Profiler Server interface in your browser.

  2. In the main toolbar, open the drop-down menu and select Administrator Dashboard.

    The dashboard opens in a new tab and shows all agents that are related to this instance of VTune Profiler Server. This includes both connected and disconnected agents.

The dashboard enables you to:

  • View information related to this agent:

    • Target system IP address and hostname

    • The username of the agent's user.

    • Current connection status.

  • Admit or stop one or multiple agents. To admit or stop multiple agents, select the agents by ticking the checkboxes and click Admit selected or Stop selected.

See Also