Struct wasmtime::GuestProfiler
source · pub struct GuestProfiler { /* private fields */ }runtime only.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
impl GuestProfiler
sourcepub fn new(
module_name: &str,
interval: Duration,
modules: Vec<(String, Module)>
) -> Self
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.
sourcepub fn sample(&mut self, store: impl AsContext, delta: Duration)
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.
sourcepub fn finish(self, output: impl Write) -> Result<()>
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/.