User Guide

  • 2020
  • 06/18/2020
  • Public Content
Contents

Use a Custom Collector

Extend a standard
Intel® VTune™
Profiler
performance analysis and launch a custom data collector directly from the
VTune
Profiler
.
Your custom collector can be an application you analyze with the
VTune
Profiler
or a collector that can be launched with the
VTune
Profiler
.
To use a custom collector with the
VTune
Profiler
and correlate the collected data:

Configure the Custom Collector

VTune
Profiler
sets several environment variables that can be used by a custom collector to manage the data collection and collected results:
Environment Variable Provided by
VTune
Profiler
Enables Custom Collector To Do This
AMPLXE_DATA_DIR
Identify a path to the
VTune
Profiler
analysis result. The custom collector uses this path to save the output
csv
file and make it accessible for the
VTune
Profiler
that adds the
csv
data to the native
VTune
Profiler
result.
AMPLXE_HOSTNAME
Identify the full hostname of the machine where data was collected. The hostname is a mandatory part of the
csv
file name
.
AMPLXE_COLLECT_CMD
Manage a custom data collection. The custom collector may receive the values listed below. After any of these commands the custom collector should exit immediately and return control to the
VTune
Profiler
.
For each command, the custom collector will be re-launched.
start
Start custom data collection. If required, the custom collector may create a background process.
stop
Stop data collection (background process), convert data to a
csv
file, copy it to the result directory (specified by
AMPLXE_DATA_DIR
) and return control to the
VTune
Profiler
.
pause
Temporarily pause data collection. This value is optional.
resume
Resume data collection after pause. This value is optional.
AMPLXE_COLLECT_PID
Identify a Process ID of the application to analyze.
VTune
Profiler
sets this environment variable to the PID of the root target process. The custom collector may use it, for example, to filter the data.
VTune
Profiler
sets this variable to the process only when profiling in the Launch Application or Attach to Process mode. For system-wide profiling, the value is empty. When your profiled application spawns a tree of processes, the
AMPLXE_COLLECT_PID
variable points to the PID of the launched or attached process. This is important to know in case of using a script to launch a workload since you may need to use your own means to pass the child process PID to the custom collector.
The templates below demonstrate an interaction between the
VTune
Profiler
and a custom collector:
Example in Python:
import os def main(): cmd = os.environ['AMPLXE_COLLECT_CMD'] if cmd == "start": path = os.environ['AMPLXE_DATA_DIR'] #starting collection of data to the given directory elif cmd == "stop": pass #stopping the collection and making transformation of own data to CSV if necessary main()
Example in Windows CMD shell:
if "%AMPLXE_COLLECT_CMD%" == "start" goto start if "%AMPLXE_COLLECT_CMD%" == "stop" goto stop echo Invalid command exit 1 :start rem Start command in non-blocking mode start <my collector command to start the collection> “%AMPLXE_DATA_DIR%”\data_file.csv exit 0 :stop <my collector command to stop the collection> exit 0

Launch the Custom Collector

To launch a custom collector from the
VTune
Profiler
GUI:
  1. Click the
    Configure Analysis
    button on the toolbar.
    The Configure Analysis window opens.
  2. Make sure the correct target system and target type are selected in the
    WHERE
    and
    WHAT
    panes.
  3. In the
    Advanced
    section of the
    WHAT
    pane, edit the
    Custom collector
    field to add a command launching your external collector, for example:
    • on Windows*:
      python.exe C:\work\custom_collector.py
    • on Linux*:
      python home/my_collectors/custom_collector.py
  4. From the
    HOW
    pane, select the required analysis type, for example,
    Hotspots
    .
  5. Configure available analysis options as you need.
  6. Click the
    Start
    button to launch the
    VTune
    Profiler
    analysis and collect custom data in parallel.
    VTune
    Profiler
    does the following:
    1. Launches the target application, if any, in the suspended mode.
    2. Launches the custom collector in the attach (or system-wide) mode.
    3. Switches the application to the active mode and starts profiling.
    If your custom collector cannot be launched in the attach mode, the collection may produce incomplete data.
To launch a custom collector from the command line:
Use the
-custom-collector=<
string
>
option.
Command Line Examples:
This example runs Hotspots analysis in the default
user-mode sampling
mode and also launches an external script collecting custom statistics for the specified application:
Windows:
vtune
-collect hotspots -custom-collector="python.exe C:\work\custom_collector.py" -- notepad.exe
Linux:
vtune
-collect hotspots -custom-collector="python /home/my_collectors/custom_collector.py" -- my_app
This example runs
VTune
Profiler
event-based sampling collector and also uses an external system collector to identify product environment variables:
Windows:
vtune
-collect-with runsa -custom-collector="set | find \"AMPLXE\"" -- notepad.exe
Linux:
vtune
-collect-with runsa -custom-collector="set | find \"AMPLXE\"" -- my_app
If you use your target application as a custom collector, you do not need to apply the
Custom collector
option but make sure your application uses the following variables:
  • AMPLXE_DATA_DIR
    environment variable to identify a path to the
    VTune
    Profiler
    result directory and save the output
    csv
    file in this location.
  • AMPLXE_HOSTNAME
    environment variable to identify the name of the current host and use it for the
    csv
    file name.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804