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, Wasmtime currently builds with the `vtune` feature
34enabled by default. This ensures the compiled binary understands how to inform
35the `ittapi` library of JIT events. But it must still be enabled at
36runtime--enable runtime support based on how you use Wasmtime:
37
38* **Rust API** - call the [`Config::profiler`] method with
39  `ProfilingStrategy::VTune` to enable profiling of your wasm modules.
40
41* **C API** - call the `wasmtime_config_profiler_set` API with a
42  `WASMTIME_PROFILING_STRATEGY_VTUNE` value.
43
44* **Command Line** - pass the `--vtune` flag on the command line.
45
46
47### Profiling Wasmtime itself
48
49Note that VTune is capable of profiling a single process or all system
50processes. Like `perf`, VTune is capable of profiling the Wasmtime runtime
51itself without any added support. However, the [`ittapi`] APIs also provide an
52interface for marking the start and stop of code regions for easy isolation in
53the VTune Profiler. Support for these APIs is expected to be added in the
54future.
55
56
57### Example: Getting Started
58
59With VTune [properly installed][download], if you are using the CLI execute:
60
61```sh
62$ cargo build
63$ vtune -run-pass-thru=--no-altstack -collect hotspots target/debug/wasmtime --vtune foo.wasm
64```
65
66This command tells the VTune collector (`vtune`) to collect hot spot
67profiling data as Wasmtime is executing `foo.wasm`. The `--vtune` flag enables
68VTune support in Wasmtime so that the collector is also alerted to JIT events
69that take place during runtime. The first time this is run, the result of the
70command is a results diretory `r000hs/` which contains profiling data for
71Wasmtime and the execution of `foo.wasm`. This data can then be read and
72displayed via the command line or via the VTune GUI by importing the result.
73
74
75### Example: CLI Collection
76
77Using a familiar algorithm, we'll start with the following Rust code:
78
79```rust
80fn main() {
81    let n = 45;
82    println!("fib({}) = {}", n, fib(n));
83}
84
85fn fib(n: u32) -> u32 {
86    if n <= 2 {
87        1
88    } else {
89        fib(n - 1) + fib(n - 2)
90    }
91}
92```
93
94We compile the example to Wasm:
95
96```sh
97$ rustc --target wasm32-wasi fib.rs -C opt-level=z -C lto=yes
98```
99
100Then we execute the Wasmtime runtime (built with the `vtune` feature and
101executed with the `--vtune` flag to enable reporting) inside the VTune CLI
102application, `vtune`, which must already be installed and available on the
103path. To collect hot spot profiling information, we execute:
104
105```sh
106$ rustc --target wasm32-wasi fib.rs -C opt-level=z -C lto=yes
107$ vtune -run-pass-thru=--no-altstack -v -collect hotspots target/debug/wasmtime --vtune fib.wasm
108fib(45) = 1134903170
109amplxe: Collection stopped.
110amplxe: Using result path /home/jlb6740/wasmtime/r000hs
111amplxe: Executing actions  7 % Clearing the database
112amplxe: The database has been cleared, elapsed time is 0.239 seconds.
113amplxe: Executing actions 14 % Updating precomputed scalar metrics
114amplxe: Raw data has been loaded to the database, elapsed time is 0.792 seconds.
115amplxe: Executing actions 19 % Processing profile metrics and debug information
116...
117Top Hotspots
118Function                                                                                      Module          CPU Time
119--------------------------------------------------------------------------------------------  --------------  --------
120h2bacf53cb3845acf                                                                             [Dynamic code]    3.480s
121__memmove_avx_unaligned_erms                                                                  libc.so.6         0.222s
122cranelift_codegen::ir::instructions::InstructionData::opcode::hee6f5b6a72fc684e               wasmtime          0.122s
123core::ptr::slice_from_raw_parts::hc5cb6f1b39a0e7a1                                            wasmtime          0.066s
124_$LT$usize$u20$as$u20$core..slice..SliceIndex$LT$$u5b$T$u5d$$GT$$GT$::get::h70c7f142eeeee8bd  wasmtime          0.066s
125```
126
127
128### Example: Importing Results into GUI
129
130Results directories created by the `vtune` CLI can be imported in the VTune GUI
131by clicking "Open > Result". Below is a visualization of the collected data as
132seen in VTune's GUI:
133
134![vtune report output](assets/vtune-gui-fib.png)
135
136
137### Example: GUI Collection
138
139VTune can collect data in multiple ways (see `vtune` CLI discussion above);
140another way is to use the VTune GUI directly. A standard work flow might look
141like:
142
143- Open VTune Profiler
144- "Configure Analysis" with
145  - "Application" set to `/path/to/wasmtime` (e.g., `target/debug/wasmtime`)
146  - "Application parameters" set to `--vtune /path/to/module.wasm`
147  - "Working directory" set as appropriate
148  - Enable "Hardware Event-Based Sampling," which may require some system
149    configuration, e.g. `sysctl -w kernel.perf_event_paranoid=0`
150- Start the analysis
151