Use a Custom Collector
Extend a standard
Intel® VTune™
performance analysis and launch a custom data collector directly from the
Profiler
VTune
.
Profiler
Your custom collector can be an application you analyze with the
VTune
or a collector that can be launched with the
Profiler
VTune
.
Profiler
To use a custom collector with the
VTune
and correlate the collected data:
Profiler
Configure the Custom Collector
VTune
sets several environment variables that can be used by a custom collector to manage the data collection and collected results:
Profiler
Environment Variable Provided by
VTune
Profiler | Enables Custom Collector To Do This
| ||||||||
---|---|---|---|---|---|---|---|---|---|
AMPLXE_DATA_DIR | Identify a path to the
VTune
analysis result. The custom collector uses this path to save the output
Profiler csv file and make it accessible for the
VTune
that adds the
Profiler csv data to the native
VTune
result.
Profiler | ||||||||
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.
| ||||||||
AMPLXE_COLLECT_PID | Identify a Process ID of the application to analyze.
VTune
sets this environment variable to the PID of the root target process. The custom collector may use it, for example, to filter the data.
Profiler VTune
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
Profiler 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
and a custom collector:
Profiler
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
GUI: Profiler
- Click theConfigure Analysisbutton on the toolbar.The Configure Analysis window opens.
- Make sure the correct target system and target type are selected in theWHEREandWHATpanes.
- In theAdvancedsection of theWHATpane, edit theCustom collectorfield 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 theHOWpane, select the required analysis type, for example,Hotspots.
- Configure available analysis options as you need.
- Click theStartbutton to launch theVTuneanalysis and collect custom data in parallel.ProfilerVTunedoes the following:Profiler
- 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=<
option.
string
>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
event-based sampling collector and also uses an external system collector to identify product environment variables:
Profiler
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_DIRenvironment variable to identify a path to theVTuneresult directory and save the outputProfilercsvfile in this location.
- AMPLXE_HOSTNAMEenvironment variable to identify the name of the current host and use it for thecsvfile name.