Using a Custom Collector

You can extend standard Intel® VTune™ Amplifier performance analysis and launch a custom data collector directly from the VTune Amplifier. Your custom collector can be an application you analyze with the VTune Amplifier or a collector that can be launched with the VTune Amplifier.

To use a custom collector with the VTune Amplifier and correlate the collected data:

Configure the custom collector .
Launch the custom collector.

Configuring the Custom Collector

VTune Amplifier 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 Amplifier

Enables Custom Collector To Do This

AMPLXE_DATA_DIR

Identify a path to the VTune Amplifier analysis result. The custom collector uses this path to save the output csv file and make it accessible for the VTune Amplifier that adds the csv data to the native VTune Amplifier 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 Amplifier.

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 Amplifier.
`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 Amplifier 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 Amplifier 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 Amplifier 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

Launching the Custom Collector

To launch a custom collector from the VTune Amplifier GUI:

Click the Configure Project... toolbar button.

The Choose Target and Analysis Type window opens with the Analysis Target tab active.
In the left pane, make sure the correct target system is selected.
In the right pane, select an analysis target type (an application, process or system-wide profiling) and configure target options, if required.
In the Advanced section, edit the Custom collector field to add a command launching an external collector, for example: python home/my_collectors/custom_collector.py. To add a path to the external collector file or directory, click the Modify button.
Switch to the Analysis Type tab.
From the left pane, select the required analysis type, for example, Algorithm Analysis > Basic Hotspots.

The corresponding configuration pane opens on the right.
Configure available analysis options as you need and click OK to save the analysis.
Click the Start button to launch the VTune Amplifier analysis and collect custom data in parallel.

VTune Amplifier 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 Basic Hotspots analysis and also launches an external script collecting custom statistics for the specified application:

>amplxe-cl -collect hotspots -custom-collector="python /home/my_collectors/custom_collector.py" -- my_app

This example runs VTune Amplifier event-based sampling collector and also uses an external system collector to identify product environment variables:

>amplxe-cl -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 Amplifier 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.

Using a Custom Collector

Configuring the Custom Collector

Note

Launching the Custom Collector

Note

See Also