wiggle::wasmtime_crate

Struct GuestProfiler

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§

§

impl GuestProfiler

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

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<(), Error>

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<(), Error>

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

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

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

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

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where 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> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where 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.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

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> Pointee for T

Source§

type Pointer = u32

Source§

fn debug( pointer: <T as Pointee>::Pointer, f: &mut Formatter<'_>, ) -> Result<(), Error>

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

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

Source§

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 T
where U: TryFrom<T>,

Source§

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.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more