knob

Set configuration options for the specified analysis type or collector type.

Syntax

-knob | -k <knob-name>=<knob-value>

Arguments

knob-name

An analysis type or collector type may have one or more configuration options (knobs) that provide additional instructions for performing the specified type of analysis. To use a knob, you must specify the knob name and knob value.

Multiple knob options are allowed and can be followed by additional action-options, as well as global-options, if needed.

knob-value

There are values available for each knob. In most cases this is a Boolean value, so for Boolean knobs, specify <knob-name>=true to enable the knob.

Note

Knob behavior may vary depending on the analysis type or collector type.
VTune Amplifier for Systems provides GPU analysis only on Android* systems running on processors with Intel® HD Graphics and Intel® Iris™ Graphics.

Knobs applicable to all analysis types:

<knob_name>	Value	Description
`enable-user-sync`	`true \| false`. Default: `false`	Collect synchronization data via the User-Defined Synchronization API.
`enable-user-tasks`	`true \| false`. Default: `false`	Analyze tasks, events and counters specified in your application via the Task API. This option causes higher overhead and increases result size.
`cpu-samples-mode`	`off \| stack \| nostack`. Default: `off`	Enable to periodically sample the application. Samples can be collected with or without stacks.
`signals-mode`	`off \| objects \| stack \| nostack`. Default: `off`	Enable to view synchronization transitions in the timeline and signalling call stacks for associated waits. The collector instruments signalling APIs, which causes higher overhead and increases result size.
`waits-mode`	`off \| stack \| nostack`. Default: `off`	Enable to identify where threads are waiting or compute thread concurrency. The collector instruments APIs, which causes higher overhead and increases result size.
`io-mode`	`off \| stack \| nostack`. Default: `off`	Enable to identify where threads are waiting or compute thread concurrency. The collector instruments APIs, which causes higher overhead and increases result size.
`stackwalk-mode`	`online \| offline`. Default: `offline`	Choose between online (during collection) and offline (after collection) modes to analyze stacks. Offline mode reduces analysis overhead and is typically recommended.
`stack-stitching`	`true \| false`. Default: `true`	For Intel TBB-based applications, restructure the call flow to attach stacks to a point introducing a parallel workload.
`enable-gpu-usage`	`true \| false`. Default: `false`	Analyze frame rate and usage of Intel HD Graphics and Intel Iris Graphics engines and identify whether your application is GPU or CPU bound.
`enable-gpu-runtimes`	`true \| false`. Default: `false`	Analyze execution of OpenCL™ kernels and Intel® Media SDK programs on Intel HD Graphics and Intel Iris Graphics. This option may affect the performance of your application on the CPU side. Note OpenCL kernels analysis is currently supported for Windows and Linux target systems with Intel HD Graphics and Intel Iris Graphics. Intel Media SDK program analysis is supported for Linux targets only.
`gpu-sampling-interval`	A number (in microseconds) between 1 and 1000. Default: 1000us	Specify an interval between GPU samples.
`gpu-counters-mode`	`none`, `overview`, `global-local-accesses`, `compute-extended`	Analyze performance data from Intel HD Graphics and Intel Iris Graphics based on the preset counter sets: `overview` - track general GPU memory accesses such as Memory Read/Write Bandwidth, GPU L3 Misses, Sampler Busy, Sampler Is Bottleneck, and GPU Memory Texture Read Bandwidth. These metrics can be useful for both graphics and compute-intensive applications. `global-local-accesses` - include metrics that distinguish accessing different types of data on a GPU: Untyped Memory Read/Write Bandwidth, Typed Memory Read/Write Transactions, SLM Read/Write Bandwidth, Render/GPGPU Command Streamer Loaded, and GPU EU Array Usage. This metrics are useful for compute-intensive workloads on the GPU. `compute-extended` - analyze GPU activity on the Intel processor code name Broadwell. This metrics set is disabled for other systems.
`sampling-interval`	For user-mode sampling and tracing types: a number (in milliseconds) between 1 and 1000. Default: 10 For hardware event-based sampling types: a number (in milliseconds) between 0.01 and 1000. Default: 1.	Specify an Sampling Interval (in milliseconds) between CPU samples.
`analyze-loops`	`true \| false`. Default: `false`	Extend loop analysis to collect advanced loops information such as instruction set usage and display analysis results by loops and functions.
`analyze-openmp`	`true \| false`. Default: `true` for the HPC Performance Characterization analysis; `false` for other analysis types.	Instrument the OpenMP* Analysis in your application to group performance data by regions/work-sharing constructs and detect inefficiencies such as imbalance, lock contention, or overhead on performing scheduling, reduction, and atomic operations. Using this option may cause higher overhead and increase the result size. Note This knob is available for the following analysis types: Basic Hotspots Advanced Hotspots Concurrency HPC Performance Characterization General Exploration Memory Access

Knobs for User-Mode Sampling and Tracing Collection (predefined and custom) only:

<knob_name>	Value	Description
`cpu-samples-mode`	`off \| stack \| nostack`. Default: `off`	Enable to periodically sample the application. Samples can be collected with or without stacks.
`accurate-cpu-time-detection`	`true \| false`. Default: `true`	Collect more accurate CPU time data. This option requires additional disk space and post-processing time. Administrator privileges are required. Note This option is supported with the VTune Amplifier XE only.
`waits-mode`	`off \| stack \| nostack`. Default: `off`	`waits-mode` Enable to identify where threads are waiting or compute thread concurrency. The collector instruments APIs, which causes higher overhead and increases result size.
`signals-mode`	`off \| objects \| stack \| nostack`. Default: `off`	Enable to view synchronization transitions in the timeline and signalling call stacks for associated waits. The collector instruments signalling APIs, which causes higher overhead and increases result size.
`io-mode`	`off \| stack \| nostack`. Default: `off`	Enable to identify where threads are waiting or compute thread concurrency. The collector instruments APIs, which causes higher overhead and increases result size.
`enable-user-sync`	`true \| false`. Default: `false`	Collect synchronization data via the User-Defined Synchronization API.
`stackwalk-mode`	`online \| offline`. Default: `offline`	Choose between online (during collection) and offline (after collection) modes to analyze stacks. Offline mode reduces analysis overhead and is typically recommended.
`stack-stitching`	`true \| false`. Default: `true`	For Intel TBB-based applications, restructure the call flow to attach stacks to a point introducing a parallel workload.
`no-altstack`	`true \| false`. Default: `false`	Disable using alternative stacks for signal handlers. Consider this option for profiling standard Python 3 code on Linux.
`mrte-type`	`java,dotnet \| java,dotnet,python \| python`. Default: `java,dotnet`	Specify a type of managed runtime to analyze. Available values: combined Java* and .NET* analysis, combined Java, .NET and Python* analysis, and Python only.

Knobs for Hardware Event-based Sampling Collection (predefined and custom) only:

<knob_name>	Value	Description
`collection-detail`	`hotspots-sampling`	Identify application hotspots based on such basic hardware events as Clockticks and Instructions Retired. Note This knob is available only for the Advanced Hotspots analysis.
	`stack-sampling`	Identify hardware hotspots, explore statistically reconstructed call flow of your program and analyze thread scheduling.
	`stack-and-callcount`	Identify hardware hotspots, analyze thread scheduling, explore call stacks and statistically approximated number of calls to sampled functions.
	`stack-call-and-tripcount`	Extend the `stack-and-callcount` collection with an analysis of loop trip count statistically estimated using the hardware events.
`enable-stack-collection`	`true \| false`. Default: `false`	Enable Hardware Event-based Sampling Collection with Stacks.
`stack-size`	A number between 0 and 2147483647. Default is 0 (unlimited stack size).	Reduce the collection overhead and limit the stack size (in bytes) processed by the VTune Amplifier.
`stack-type`	`software \| lbr`. Default: `software`	Choose between software stack and hardware LBR-based stack types. Software stacks have no depth limitations and provide more data while hardware stacks introduce less overhead. Typically, software stack type is recommended unless the collection overhead becomes significant. Note that hardware LBR stack type may not be available on all platforms.
`enable-call-counts`	`true \| false`. Default: `false`	Obtain statistical estimation of call counts based on hardware events.
`enable-trip-counts`	`true \| false`. Default: `false`	Obtain statistical estimation of loop trip counts based on hardware events.
`event-config`	`<event_name1>,<event_name2>,...`	Configure PMU events to collect with the hardware event-based sampling collector. Multiple events can be specified as a comma-separated list (no spaces). Note To display a list of events available on the target PMU, enter: `$ amplxe-cl -collect-with runsa -knob event-config=? <target>` The command returns names and short descriptions of available events. For more information on the events, use Intel Processor Events Reference
`chipset-event-config`	`"event1,event2,..."`	Specify a comma-separated list of Android chipset events (up to 5 events) to monitor with the hardware event-based sampling collector.
`enable-system-cswitch`	`true \| false`. Default: `false`	Analyze detailed scheduling layout for all threads on the system and identify the nature of context switches for a thread (preemption or synchronization). Note This knob is available only for the Custom Analysis.
`dram-bandwidth-limits`	`true \| false`. Default: `true` for the HPC Performance Characterization and General Exploration analysis with `collect-memory-bandwidth` knob enabled; `true` for the Memory Access analysis.	Evaluate maximum achievable local DRAM bandwidth before the collection starts. This data is used to scale bandwidth metrics on the timeline and calculate thresholds. Note The knob available only for the HPC Performance Characterization Analysis , General Exploration Analysis and Memory Access Analysis analysis types.
`collect-memory-bandwidth`	`true \| false`. Default: `false`	Collect data to identify where your application is generating significant bandwidth to DRAM. To view collected data in GUI, enable the Interpreting Memory Usage Data.
`analyze-mem-objects`	`true \| false`. Default: `false`	Enable the instrumentation of memory allocation/de-allocation and map hardware events to memory objects.
`mem-object-size-min-thres`	Default: 1024 bytes	Specify a minimal size of memory allocations to analyze. This option helps reduce runtime overhead of the instrumentation.
`event-mode`	`all \| user \| os`. Default: `all`	Limit event-based sampling collection to OS or USER mode.
`atrace-config`	Available events are `gfx, input, view, webview, wm, am, audio, video, camera, hal, res, dalvik`.	Collect Android framework events from Systrace*. Note This option is supported with the VTune Amplifier for Systems only.
`ftrace-config`	Available events are `freq, idle, sched, disk, filesystem, irq, kvm, workq, softirq, sync`. Default for Linux targets: `sched,freq,idle,workq,irq,softirq` Default for Android targets: `sched,freq,idle,workq,filesystem, irq,softirq,sync,disk`	Collect Linux Ftrace* framework events. This option is supported for Linux target systems only. On some systems, Linux Ftrace events collection is possible only for the root user. Note This option is supported with the VTune Amplifier for Systems only.
`enable-cache-metrics`	`true \| false`. Default: `true`	Analyze the data locality. Good data accessibility makes your code efficient and helps benefit from vectorization. This analysis includes only L1 metrics since L2 and FILL events on the Intel® Xeon Phi™ coprocessor are counting both demand loads and stores as well as multiple types of prefetches. Since other events do not count all of the prefetches accurately, the formulas cannot be adjusted to calculate real demand L2 hits or misses. Note This knob is available only for the General Exploration analysis on the Intel Xeon Phi™ coprocessor.
`enable-l2-events`	`true \| false`. Default: `true`	Extend cache analysis with adding the L2_DATA_READ/WRITE_MISS_CACHE_FILL and L2_DATA_READ/WRITE_MISS_MEM_FILL events for some insight into L2 data locality. The general ratio of these events may indicate remote cache accesses that have as high a latency as memory accesses and should be avoided if possible. Note This knob is available only for the General Exploration analysis on the Intel Xeon Phi coprocessor.
`enable-tlb-metrics`	`true \| false`. Default: `false`	Translation Lookaside Buffer (TLB) is a cache used for mapping virtual address to physical ones. Analyze the rate of TLB misses to identify performance problems. Note This knob is available only for the General Exploration analysis on Intel Xeon Phi coprocessor.
`enable-vpu-metrics`	`true \| false`. Default: `false`	Identify whether the level of vectorization usage (instruction-level parallelism) in your program is sufficient. Note This knob is available only for the General Exploration analysis on Intel Xeon Phi coprocessor.
`analysis-step`	`cycles \| aborts`. Default: `cycles`	Specify a step for analyzing Intel Transactional Synchronization Extensions behavior. Typically, you start with measuring transactional success (`cycles`) and then, if the aborts rate is high, you run the TSX Exploration to analyze for `aborts`. Note This knob is available only for theTSX Exploration Analysis analysis for the Intel microarchitecture code name Haswell.
`collect-memory-bandwidth`	`true \| false`. Default: `false`	Collect the data required for computing memory bandwidth. Note The knob available only for the HPC Performance Characterization Analysis and General Exploration Analysis analysis types.
`enable-context-switches`	`true \| false`. Default: `false`	Analyze detailed scheduling layout for all threads in your application, explore time spent on a context switch and identify the nature of context switches for a thread (preemption or synchronization). Note This knob is available only for the Custom Analysis.
`analyze-fpu`	`true \| false`. Default: `false`	Analyze how intensively the Floating Point Unit (FPU) is used by your program.

Actions Modified

collect collect-with

Description

Use the knob action-option to configure knob settings for a collect (predefined analysis types) or collect-with (custom analysis types) action where the analysis type supports one or more knobs. Each analysis type or collector type supports a specific set of knobs, and each knob requires a value. In most cases the knob value is Boolean, so you would use True to enable the knob.

To see all knobs available for a predefined analysis type:

$ amplxe-cl -help collect <analysis_type>

To see knobs for a custom analysis type:

$ amplxe-cl -help collect-with <analysis_type>

Example

This example returns a list of knobs for the Locks and Waits analysis type:

$ amplxe-cl -help collect locksandwaits

This example runs a custom event-based sampling data collection on an Android system enabling collection of Android framework and chipset events (applicable to the VTune Amplifier for Systems only).

$ amplxe-cl -collect-with runss -target-system=android -knob sampling-interval=2 -knob cpu-samples-mode=stack -knob ftrace-config=gfx,dalvik -knob chipset-event-config="GMCH_PARTIAL_WR_DRAM.ANY,GMCH_CORE_CLKS" --target-process com.intel.tbb.example.tachyon

This example configures and runs a custom event-based sampling data collection with the stack size limited to 8192 bytes:

$ amplxe-cl -collect-with runsa -knob enable-stack-collection=true -knob stack-size=8192 -knob enable-call-counts=true -knob event-config=CPU_CLK_UNHALTED.REF_TSC:sa=1800000,CPU_CLK_UNHALTED

knob

Syntax

Arguments

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Note

Actions Modified

Description

Example

See Also