logging

Documentation

Overview

Example (NewHostLoggingListenerFactory)

This is a very basic integration of listener. The main goal is to show how it is configured.

package main

import (
	"context"
	"log"
	"os"

	_ "embed"
	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/wazero/experimental"
	"github.com/tetratelabs/wazero/experimental/logging"
	"github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
)

// listenerWasm was generated by the following:
//
//	cd testdata; wat2wasm --debug-names listener.wat
//
//go:embed testdata/listener.wasm
var listenerWasm []byte

func main() {
	// Set context to one that has an experimental listener that logs all host functions.
	ctx := experimental.WithFunctionListenerFactory(context.Background(),
		logging.NewHostLoggingListenerFactory(os.Stdout, logging.LogScopeAll))

	r := wazero.NewRuntime(ctx)
	defer r.Close(ctx) // This closes everything this Runtime created.

	wasi_snapshot_preview1.MustInstantiate(ctx, r)

	mod, err := r.InstantiateWithConfig(ctx, listenerWasm,
		wazero.NewModuleConfig().WithStdout(os.Stdout))
	if err != nil {
		log.Panicln(err)
	}

	_, err = mod.ExportedFunction("rand").Call(ctx, 4)
	if err != nil {
		log.Panicln(err)
	}

	// We should see the same function called twice: directly and indirectly.

}

Output:

--> listener.rand(len=4)
	==> wasi_snapshot_preview1.random_get(buf=4,buf_len=4)
	<== errno=ESUCCESS
	==> wasi_snapshot_preview1.random_get(buf=8,buf_len=4)
	<== errno=ESUCCESS
<--

Example (NewLoggingListenerFactory)

This example shows how to see all function calls, including between host functions.

package main

import (
	"context"
	"log"
	"os"

	_ "embed"
	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/wazero/experimental"
	"github.com/tetratelabs/wazero/experimental/logging"
	"github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
)

// listenerWasm was generated by the following:
//
//	cd testdata; wat2wasm --debug-names listener.wat
//
//go:embed testdata/listener.wasm
var listenerWasm []byte

func main() {
	// Set context to one that has an experimental listener
	ctx := experimental.WithFunctionListenerFactory(context.Background(), logging.NewLoggingListenerFactory(os.Stdout))

	r := wazero.NewRuntime(ctx)
	defer r.Close(ctx) // This closes everything this Runtime created.

	wasi_snapshot_preview1.MustInstantiate(ctx, r)

	mod, err := r.InstantiateWithConfig(ctx, listenerWasm,
		wazero.NewModuleConfig().WithStdout(os.Stdout))
	if err != nil {
		log.Panicln(err)
	}

	_, err = mod.ExportedFunction("rand").Call(ctx, 4)
	if err != nil {
		log.Panicln(err)
	}

	// We should see the same function called twice: directly and indirectly.

}

Output:

--> listener.rand(len=4)
	--> listener.wasi_rand(len=4)
		==> wasi_snapshot_preview1.random_get(buf=4,buf_len=4)
		<== errno=ESUCCESS
		==> wasi_snapshot_preview1.random_get(buf=8,buf_len=4)
		<== errno=ESUCCESS
	<--
<--

Index

• Constants
• func NewHostLoggingListenerFactory(w Writer, scopes logging.LogScopes) experimental.FunctionListenerFactory
• func NewLoggingListenerFactory(w Writer) experimental.FunctionListenerFactory
• type LogScopes
• type Writer

Examples

• Package (NewHostLoggingListenerFactory)
• Package (NewLoggingListenerFactory)

Constants

const (
	// LogScopeNone means nothing should be logged
	LogScopeNone = logging.LogScopeNone
	// LogScopeClock enables logging for functions such as `clock_time_get`.
	LogScopeClock = logging.LogScopeClock
	// LogScopeProc enables logging for functions such as `proc_exit`.
	//
	// Note: This includes functions that both log and exit. e.g. `abort`.
	LogScopeProc = logging.LogScopeProc
	// LogScopeFilesystem enables logging for functions such as `path_open`.
	//
	// Note: This doesn't log writes to the console.
	LogScopeFilesystem = logging.LogScopeFilesystem
	// LogScopeMemory enables logging for functions such as
	// `emscripten_notify_memory_growth`.
	LogScopeMemory = logging.LogScopeMemory
	// LogScopePoll enables logging for functions such as `poll_oneoff`.
	LogScopePoll = logging.LogScopePoll
	// LogScopeRandom enables logging for functions such as `random_get`.
	LogScopeRandom = logging.LogScopeRandom
	// LogScopeSock enables logging for functions such as `sock_accept`.
	LogScopeSock = logging.LogScopeSock
	// LogScopeAll means all functions should be logged.
	LogScopeAll = logging.LogScopeAll
)

Functions

func NewHostLoggingListenerFactory

func NewHostLoggingListenerFactory(w Writer, scopes logging.LogScopes) experimental.FunctionListenerFactory

NewHostLoggingListenerFactory is an experimental.FunctionListenerFactory that logs exported and host functions to the writer.

This is an alternative to NewLoggingListenerFactory, and would weed out guest defined functions such as those implementing garbage collection.

For example, "_start" is defined by the guest, but exported, so would be written to the w in order to provide minimal context needed to understand host calls such as "args_get".

The scopes parameter can be set to LogScopeAll or constrained.

func NewLoggingListenerFactory

func NewLoggingListenerFactory(w Writer) experimental.FunctionListenerFactory

NewLoggingListenerFactory is an experimental.FunctionListenerFactory that logs all functions that have a name to the writer.

Use NewHostLoggingListenerFactory if only interested in host interactions.

Types

type LogScopes

type LogScopes = logging.LogScopes

LogScopes is a bit flag of host function groups to log. e.g. LogScopeRandom.

To specify all scopes, use LogScopeAll. For multiple scopes, OR them together like this:

scope = logging.LogScopeRandom | logging.LogScopeFilesystem

Note: Numeric values are not intended to be interpreted except as bit flags.

type Writer

type Writer interface {
	io.Writer
	io.StringWriter
}