Struct GuestProfiler

pub struct GuestProfiler { /* private fields */ }

Available on crate features profiling and runtime only.

Collects basic profiling data for a single WebAssembly guest.

This profiler can’t provide measurements that are as accurate or detailed as a platform-specific profiler, such as perf on Linux. On the other hand, this profiler works on every platform that Wasmtime supports. Also, as an embedder you can use this profiler selectively on individual guest instances rather than profiling the entire process.

To use this, you’ll need to arrange to call GuestProfiler::sample at regular intervals while the guest is on the stack. The most straightforward way to do that is to call it from a callback registered with Store::epoch_deadline_callback().

Accuracy

The data collection granularity is limited by the mechanism you use to interrupt guest execution and collect a profiling sample.

If you use epoch interruption, then samples will only be collected at function entry points and loop headers. This introduces some bias to the results. In addition, samples will only be taken at times when WebAssembly functions are running, not during host-calls.

It is technically possible to use fuel interruption instead. That introduces worse bias since samples occur after a certain number of WebAssembly instructions, which can take different amounts of time.

You may instead be able to use platform-specific methods, such as setitimer(ITIMER_VIRTUAL, ...) on POSIX-compliant systems, to sample on a more accurate interval. The only current requirement is that the guest you wish to profile must be on the same stack where you call sample, and executing within the same thread. However, the GuestProfiler::sample method is not currently async-signal-safe, so doing this correctly is not easy.

Security

Profiles produced using this profiler do not include any configuration details from the host, such as virtual memory addresses, or from any WebAssembly modules that you haven’t specifically allowed. So for example, these profiles should be safe to share with untrusted users who have provided untrusted code that you are running in a multi-tenancy environment.

However, the profile does include byte offsets into the text section of the compiled module, revealing some information about the size of the code generated for each module. For user-provided modules, the user could get the same information by compiling the module for themself using a similar version of Wasmtime on the same target architecture, but for any module where they don’t already have the WebAssembly module binary available this could theoretically lead to an undesirable information disclosure. So you should only include user-provided modules in profiles.

Implementations

impl GuestProfiler

pub fn new( module_name: &str, interval: Duration, modules: Vec<(String, Module)>, ) -> Self

Begin profiling a new guest. When this function is called, the current wall-clock time is recorded as the start time for the guest.

The module_name parameter is recorded in the profile to help identify where the profile came from.

The interval parameter should match the rate at which you intend to call sample. However, this is used as a hint and not required to exactly match the real sample rate.

Only modules which are present in the modules vector will appear in stack traces in this profile. Any stack frames which were executing host code or functions from other modules will be omitted. See the “Security” section of the GuestProfiler documentation for guidance on what modules should not be included in this list.

pub fn sample(&mut self, store: impl AsContext, delta: Duration)

Add a sample to the profile. This function collects a backtrace from any stack frames for allowed modules on the current stack. It should typically be called from a callback registered using Store::epoch_deadline_callback().

The delta parameter is the amount of CPU time that was used by this guest since the previous sample. It is allowed to pass Duration::ZERO here if recording CPU usage information is not needed.

pub fn call_hook(&mut self, store: impl AsContext, kind: CallHook)

Add a marker for transitions between guest and host to the profile. This function should typically be called from a callback registered using Store::call_hook(), and the kind parameter should be the value of the same type passed into that hook.

pub fn finish(self, output: impl Write) -> Result<()>

When the guest finishes running, call this function to write the profile to the given output. The output is a JSON-formatted object in the Firefox “processed profile format”. Files in this format may be visualized at https://profiler.firefox.com/.

Trait Implementations

impl Debug for GuestProfiler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.