1# Using `VTune` on Linux
2
3[`VTune Profiler`](https://software.intel.com/en-us/vtune-help) is a popular performance profiling tool that targets both 32-bit and 64-bit x86 architectures. The tool collects profiling data during runtime and then either through command line or gui, provides a variety of options for viewing and doing anaysis on that data. VTune Profiler is available in both commerical and free options. The free download version backed by a community forum for support, is available [`here`](https://software.intel.com/en-us/vtune/choose-download#standalone). This version is appropriate for detailed analysis of your WASM program. Note for jit support, Wasmtime only supports VTune profiling on linux platforms but other platforms are expected to be enabled in the future.
4
5VTune support in wasmtime is provided through the jit profiling APIs at [`https://github.com/intel/ittapi`](https://github.com/intel/ittapi). These APIs are provided for code generators (or the runtimes that use them) to report jit activities. These APIs are implemented in a shared library (built from the same [`ittapi`](https://github.com/intel/ittapi) project) which wasmtime pulls in and links to when vtune support is specified through the `vtune` cargo feature flag. This feature is not enabled by default. When the VTune collector is run, it links to this same shared library to handle profiling request related to the reported jit activities. Specifically, Wasmtime pulls in the ittapi-rs system crate which provides the shared library and Rust interface to the jit profiling APIs.
6
7For jit profiling with VTune Profiler, first you want to make sure the `vtune` feature is enabled. After that, enabling runtime support is based on how you are using Wasmtime:
8
9* **Rust API** - you'll want to call the [`Config::profiler`] method with
10  `ProfilingStrategy::VTune` to enable profiling of your wasm modules.
11
12* **C API** - you'll want to call the `wasmtime_config_profiler_set` API with a
13  `WASMTIME_PROFILING_STRATEGY_VTUNE` value.
14
15* **Command Line** - you'll want to pass the `--vtune` flag on the command
16  line.
17
18After profiling is complete, a results folder will hold profiling data that can then be read and analyzed with VTune.
19
20Also note, VTune is capable of profiling a single process or system wide. As such, and like perf, VTune is plenty capable of profiling the wasmtime runtime itself without any added support. However, APIs [`here`](https://github.com/intel/ittapi) also support an interface for marking the start and stop of code regions for easy isolatation in the VTune Profiler. Support for these APIs are expected to be added in the future.
21
22Take the following example: with VTune properly installed, if you're using the CLI you'll execute with:
23
24```sh
25$ cargo build --features=vtune
26$ amplxe-cl -run-pass-thru=--no-altstack -collect hotspots target/debug/wasmtime --vtune foo.wasm
27```
28
29This command tells the VTune collector (amplxe-cl) to collect hotspot profiling data on wasmtime that is executing foo.wasm. The --vtune flag enables VTune support in wasmtime so that the collector is also alerted to jit events that take place during runtime. The first time this is run, the result of the command is a results diretory r000hs/ which contains hotspot profiling data for wasmtime and the execution of foo.wasm. This data can then be read and displayed via the command line or via the VTune gui by importing the result.
30
31### `VTune` example
32
33Running through a familiar algorithm, first we'll start with the following wasm:
34
35```rust
36fn main() {
37    let n = 45;
38    println!("fib({}) = {}", n, fib(n));
39}
40
41fn fib(n: u32) -> u32 {
42    if n <= 2 {
43        1
44    } else {
45        fib(n - 1) + fib(n - 2)
46    }
47}
48```
49
50Profiling data using vtune can be collected a number of ways and profiling data can be collected to focus
51on certain types of analysis. Below we show a command line executable option using amplxe-cl, which is
52installed and in our path, to help find hotspots in our wasm module. To collect  profiling information then,
53we'll simply execute:
54
55```sh
56$ rustc --target wasm32-wasi fib.rs -C opt-level=z -C lto=yes
57$ amplxe-cl -run-pass-thru=--no-altstack -v -collect hotspots target/debug/wasmtime --vtune fib.wasm
58fib(45) = 1134903170
59amplxe: Collection stopped.
60amplxe: Using result path /home/jlb6740/wasmtime/r000hs
61amplxe: Executing actions  7 % Clearing the database
62amplxe: The database has been cleared, elapsed time is 0.239 seconds.
63amplxe: Executing actions 14 % Updating precomputed scalar metrics
64amplxe: Raw data has been loaded to the database, elapsed time is 0.792 seconds.
65amplxe: Executing actions 19 % Processing profile metrics and debug information
66...
67...
68Top Hotspots
69Function                                                                                      Module          CPU Time
70--------------------------------------------------------------------------------------------  --------------  --------
71h2bacf53cb3845acf                                                                             [Dynamic code]    3.480s
72__memmove_avx_unaligned_erms                                                                  libc.so.6         0.222s
73cranelift_codegen::ir::instructions::InstructionData::opcode::hee6f5b6a72fc684e               wasmtime          0.122s
74core::ptr::slice_from_raw_parts::hc5cb6f1b39a0e7a1                                            wasmtime          0.066s
75_$LT$usize$u20$as$u20$core..slice..SliceIndex$LT$$u5b$T$u5d$$GT$$GT$::get::h70c7f142eeeee8bd  wasmtime          0.066s
76```
77Note again, wasmtime must be built with the `vtune` feature flag enabled. From here you there are several options for further analysis. Below is an example view of the collected as seen in VTune's gui with it's many options.
78
79![vtune report output](assets/vtune-gui-fib.png)
80
81For more information on VTune and the analysis tools it provides see the docs [`here`](https://software.intel.com/en-us/vtune-help).