profiling.h File Reference

API for Wasmtime guest profiler. More...

#include <wasm.h>
#include <wasmtime/error.h>

Go to the source code of this file.

Data Structures
struct	wasmtime_guestprofiler_modules
	Tuple of name and module for passing into wasmtime_guestprofiler_new. More...

Typedefs
typedef struct wasmtime_guestprofiler	wasmtime_guestprofiler_t
	Collects basic profiling data for a single WebAssembly guest. More...
typedef struct wasmtime_guestprofiler_modules	wasmtime_guestprofiler_modules_t
	Alias to wasmtime_guestprofiler_modules.

Functions
void	wasmtime_guestprofiler_delete (wasmtime_guestprofiler_t *guestprofiler)
	Deletes profiler without finishing it. More...
wasmtime_guestprofiler_t *	wasmtime_guestprofiler_new (const wasm_name_t *module_name, uint64_t interval_nanos, const wasmtime_guestprofiler_modules_t *modules, size_t modules_len)
	Begin profiling a new guest. More...
void	wasmtime_guestprofiler_sample (wasmtime_guestprofiler_t *guestprofiler, const wasmtime_store_t *store, uint64_t delta_nanos)
	Add a sample to the profile. More...
wasmtime_error_t *	wasmtime_guestprofiler_finish (wasmtime_guestprofiler_t *guestprofiler, wasm_byte_vec_t *out)
	Writes out the captured profile. More...

Detailed Description

API for Wasmtime guest profiler.

Typedef Documentation

wasmtime_guestprofiler_t

typedef struct wasmtime_guestprofiler wasmtime_guestprofiler_t

Collects basic profiling data for a single WebAssembly guest.

To use this, you’ll need to arrange to call wasmtime_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 wasmtime_store_epoch_deadline_callback.

For more information see the Rust documentation at: https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html

Function Documentation

wasmtime_guestprofiler_delete()

void wasmtime_guestprofiler_delete

(

wasmtime_guestprofiler_t *

guestprofiler

)

Deletes profiler without finishing it.

Parameters

guestprofiler

profiler that is being deleted

wasmtime_guestprofiler_finish()

wasmtime_error_t * wasmtime_guestprofiler_finish	(	wasmtime_guestprofiler_t *	guestprofiler,
		wasm_byte_vec_t *	out
	)

Writes out the captured profile.

Parameters

guestprofiler	the profiler which is being finished and deleted
out	pointer to where wasm_byte_vec_t containing generated file will be written

Returns

Returns wasmtime_error_t owned by the caller in case of error, NULL otherwise.

This function takes ownership of guestprofiler, even when error is returned. Only when returning without error out is filled with wasm_byte_vec_t owned by the caller.

For more information see the Rust documentation at: https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.finish

wasmtime_guestprofiler_new()

wasmtime_guestprofiler_t * wasmtime_guestprofiler_new	(	const wasm_name_t *	module_name,
		uint64_t	interval_nanos,
		const wasmtime_guestprofiler_modules_t *	modules,
		size_t	modules_len
	)

Begin profiling a new guest.

Parameters

module_name	name recorded in the profile
interval_nanos	intended sampling interval in nanoseconds recorded in the profile
modules	modules and associated names that will appear in captured stack traces, pointer to the first element
modules_len	count of elements in modules

Returns

Created profiler that is owned by the caller.

This function does not take ownership of the arguments.

For more information see the Rust documentation at: https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.new

wasmtime_guestprofiler_sample()

void wasmtime_guestprofiler_sample	(	wasmtime_guestprofiler_t *	guestprofiler,
		const wasmtime_store_t *	store,
		uint64_t	delta_nanos
	)

Add a sample to the profile.

Parameters

guestprofiler	the profiler the sample is being added to
store	store that is being used to collect the backtraces
delta_nanos	CPU time in nanoseconds that was used by this guest since the previous sample

Zero can be passed as delta_nanos if recording CPU usage information is not needed. This function does not take ownership of the arguments.

For more information see the Rust documentation at: https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.sample