Use a Custom Collector

Intel® VTune™ Profiler

User Guide

Download PDF

ID 766319

Date 6/24/2024

Version

Public

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

Visible to Intel only — GUID: GUID-1B216ED5-1ECA-44B3-B21B-20B60CB46914

View Details

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 .
Launch the custom collector.

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.

NOTE:

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:

Click the Configure Analysis button on the toolbar.

The Configure Analysis window opens.
Make sure the correct target system and target type are selected in the WHERE and WHAT panes.
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
From the HOW pane, select the required analysis type, for example, Hotspots.
Configure available analysis options as you need.
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

NOTE:

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.

Parent topic: Import External Data

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

User Guide

Use a Custom Collector

Configure the Custom Collector

Launch the Custom Collector

See Also