Profile a program

Record a profile

cd MyProject
wax build --profile --output app
WAX_PROFILE_OUT=trace.json ./app

Here wax build --output app selects the artifact file. This differs from wax new --output Generated, which selects the artifact directory stored in a new project. In PowerShell, run the profiled executable with:

$env:WAX_PROFILE_OUT = "trace.json"
.\app.exe

Open trace.json in Perfetto. The timeline shows each Wax function by its qualified name, nested by call stack, with a separate span for every application frame.

--profile adds instrumentation at compile time. WAX_PROFILE_OUT decides whether a run records it. A build without --profile contains no profiler code; a profiled build can still run normally when WAX_PROFILE_OUT is unset.

An ordinary build made with wax build --profile uses the generated C backend. WebAssembly profiling in a browser is not currently supported. Debugger recording profiling, described below, can instead use the debugger's Native or generated C execution path.

Start with selected functions

Instrumenting every small function changes the program and can make hot leaves look more expensive than they are. When possible, select the larger operations you want to measure:

wax build '--profile=MyApp\.Update|MyApp\.Physics'

The value is a regular expression matched against qualified function names. Functions that do not match receive no profiling code. Preview the selection without building an artifact:

cd MyProject
waxc '--profile=MyApp\.Physics' --profile-list

Bare --profile instruments every function. Use it when call counts and call structure matter, but treat timings for tiny, frequently called functions with caution. Instrumentation adds work and prevents an instrumented function from being inlined.

Get a summary

For a quick list of hot functions instead of a timeline:

WAX_PROFILE_OUT=summary.json WAX_PROFILE_SUMMARY=1 ./app

The remaining examples use the POSIX inline environment form. In PowerShell, set each $env: value as above before running .\app.exe.

The JSON output is sorted by self time. selfNs excludes time in callees; totalNs includes it. count is the number of calls.

To exclude warmup or keep a representative frame range:

WAX_PROFILE_OUT=trace.json WAX_PROFILE_FRAMES=2-5 ./app

WAX_PROFILE_FRAMES accepts N, N-M, or N-.

Profile a recorded run

When the behavior is already captured by a deterministic debugger run, create the recording and profile together:

cd MyProject
wax debug init
waxdbg recording create run.wxs --frames 120 --profile

This writes run.wxs and run.wxs.profile.json. Recording profiling supports the debugger's native and C execution paths.

For the complete selection, exclusion, calibration, and trace format controls, run waxc --help.