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
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.
Identify the full hostname of the machine where data was collected. The hostname is a mandatory part of the csv file name.
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.
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:
Launches the target application, if any, in the suspended mode.
Launches the custom collector in the attach (or system-wide) mode.
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:
vtune -collect hotspots -custom-collector="python.exe C:\work\custom_collector.py" -- notepad.exe
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:
vtune -collect-with runsa -custom-collector="set | find \"AMPLXE\"" -- notepad.exe
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.