Struct wasmtime::GuestProfiler

source ·
pub struct GuestProfiler { /* private fields */ }
Expand description

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§

source§

impl GuestProfiler

source

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.

source

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

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().

source

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§

source§

impl Debug for GuestProfiler

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.