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