1# Using `VTune` on Linux
2
3[VTune][help] is a popular performance profiling tool that targets both 32-bit
4and 64-bit x86 architectures. The tool collects profiling data during runtime
5and then, either through the command line or GUI, provides a variety of options
6for viewing and analyzing that data. VTune Profiler is available in both
7commerical and free options. The free, downloadable version is available
8[here][download] and is backed by a community forum for support. This version is
9appropriate for detailed analysis of your Wasm program. Note that for JIT
10support, Wasmtime only supports VTune profiling on Linux platforms but other
11platforms are expected to be enabled in the future.
12
13VTune support in Wasmtime is provided through the JIT profiling APIs from the
14[`ittapi`] library. This library provides code generators (or the runtimes that
15use them) a way to report JIT activities. The APIs are implemented in a static
16library (see [`ittapi`] source) which Wasmtime links to when VTune support is
17specified through the `vtune` Cargo feature flag; this feature is not enabled by
18default. When the VTune collector is run, the `ittapi` library collects
19Wasmtime's reported JIT activities. This connection to `ittapi` is provided by
20the [`ittapi-rs`] crate.
21
22For more information on VTune and the analysis tools it provides see its
23[documentation].
24
25[help]: https://software.intel.com/en-us/vtune-help
26[download]: https://software.intel.com/en-us/vtune/choose-download#standalone
27[documentations]: https://software.intel.com/en-us/vtune-help
28[`ittapi`]: https://github.com/intel/ittapi
29[`ittapi-rs`]: https://crates.io/crates/ittapi-rs
30
31### Turn on VTune support
32
33For JIT profiling with VTune, first build with the `vtune` feature enabled:
34
35```sh
36$ cargo build --features=vtune
37```
38
39Then, enable runtime support based on how you use Wasmtime:
40
41* **Rust API** - call the [`Config::profiler`] method with
42  `ProfilingStrategy::VTune` to enable profiling of your wasm modules.
43
44* **C API** - call the `wasmtime_config_profiler_set` API with a
45  `WASMTIME_PROFILING_STRATEGY_VTUNE` value.
46
47* **Command Line** - pass the `--vtune` flag on the command line.
48
49
50### Profiling Wasmtime itself
51
52Note that VTune is capable of profiling a single process or all system
53processes. Like `perf`, VTune is capable of profiling the Wasmtime runtime
54itself without any added support. However, the [`ittapi`] APIs also provide an
55interface for marking the start and stop of code regions for easy isolation in
56the VTune Profiler. Support for these APIs is expected to be added in the
57future.
58
59
60### Example: Getting Started
61
62With VTune [properly installed][download], if you are using the CLI execute:
63
64```sh
65$ cargo build --features=vtune
66$ vtune -run-pass-thru=--no-altstack -collect hotspots target/debug/wasmtime --vtune foo.wasm
67```
68
69This command tells the VTune collector (`vtune`) to collect hot spot
70profiling data as Wasmtime is executing `foo.wasm`. The `--vtune` flag enables
71VTune support in Wasmtime so that the collector is also alerted to JIT events
72that take place during runtime. The first time this is run, the result of the
73command is a results diretory `r000hs/` which contains profiling data for
74Wasmtime and the execution of `foo.wasm`. This data can then be read and
75displayed via the command line or via the VTune GUI by importing the result.
76
77
78### Example: CLI Collection
79
80Using a familiar algorithm, we'll start with the following Rust code:
81
82```rust
83fn main() {
84    let n = 45;
85    println!("fib({}) = {}", n, fib(n));
86}
87
88fn fib(n: u32) -> u32 {
89    if n <= 2 {
90        1
91    } else {
92        fib(n - 1) + fib(n - 2)
93    }
94}
95```
96
97We compile the example to Wasm:
98
99```sh
100$ rustc --target wasm32-wasi fib.rs -C opt-level=z -C lto=yes
101```
102
103Then we execute the Wasmtime runtime (built with the `vtune` feature and
104executed with the `--vtune` flag to enable reporting) inside the VTune CLI
105application, `vtune`, which must already be installed and available on the
106path. To collect hot spot profiling information, we execute:
107
108```sh
109$ rustc --target wasm32-wasi fib.rs -C opt-level=z -C lto=yes
110$ vtune -run-pass-thru=--no-altstack -v -collect hotspots target/debug/wasmtime --vtune fib.wasm
111fib(45) = 1134903170
112amplxe: Collection stopped.
113amplxe: Using result path /home/jlb6740/wasmtime/r000hs
114amplxe: Executing actions  7 % Clearing the database
115amplxe: The database has been cleared, elapsed time is 0.239 seconds.
116amplxe: Executing actions 14 % Updating precomputed scalar metrics
117amplxe: Raw data has been loaded to the database, elapsed time is 0.792 seconds.
118amplxe: Executing actions 19 % Processing profile metrics and debug information
119...
120Top Hotspots
121Function                                                                                      Module          CPU Time
122--------------------------------------------------------------------------------------------  --------------  --------
123h2bacf53cb3845acf                                                                             [Dynamic code]    3.480s
124__memmove_avx_unaligned_erms                                                                  libc.so.6         0.222s
125cranelift_codegen::ir::instructions::InstructionData::opcode::hee6f5b6a72fc684e               wasmtime          0.122s
126core::ptr::slice_from_raw_parts::hc5cb6f1b39a0e7a1                                            wasmtime          0.066s
127_$LT$usize$u20$as$u20$core..slice..SliceIndex$LT$$u5b$T$u5d$$GT$$GT$::get::h70c7f142eeeee8bd  wasmtime          0.066s
128```
129
130
131### Example: Importing Results into GUI
132
133Results directories created by the `vtune` CLI can be imported in the VTune GUI
134by clicking "Open > Result". Below is a visualization of the collected data as
135seen in VTune's GUI:
136
137![vtune report output](assets/vtune-gui-fib.png)
138
139
140### Example: GUI Collection
141
142VTune can collect data in multiple ways (see `vtune` CLI discussion above);
143another way is to use the VTune GUI directly. A standard work flow might look
144like:
145
146- Open VTune Profiler
147- "Configure Analysis" with
148  - "Application" set to `/path/to/wasmtime` (e.g., `target/debug/wasmtime`)
149  - "Application parameters" set to `--vtune /path/to/module.wasm`
150  - "Working directory" set as appropriate
151  - Enable "Hardware Event-Based Sampling," which may require some system
152    configuration, e.g. `sysctl -w kernel.perf_event_paranoid=0`
153- Start the analysis
154