WARPO employs instrumentation techniques to analyze potential CPU performance issues in code.

Concept

When compiling AssemblyScript to WebAssembly, the --trace-point-mapping-file command-line argument specifies the path to the trace point mapping file. WARPO automatically inserts instrumentation at the entry and exit points in each function inside user code. These instrumentation points correspond to the imported function builtin.tracePoint(id: i32), where the mapping between trace point IDs and corresponding function names is stored in the trace point mapping file.

The WebAssembly execution engine must implement compatibility support for the builtin.tracePoint function, persistently storing the current time point and corresponding trace point ID to local storage media. Subsequent analysis tools can reconstruct the complete code execution timeline through temporal information at function entry and exit points, enabling the generation of visual flame graphs based on this dataset.

Technical Details

insert instrumentation

For CPU performance analysis, WARPO needs to trace function entry and exit points. For easier post-processing, assume function mapped ID is N, WARPO will insert builtin.tracePoint(N) at the entry point of functions, then insert builtin.tracePoint(-N) at the exit point.

Details

Functions will be numbered starting from 0x1'000000.

record during execution

see wasm-compiler documentation: tracing

In short, set environment variable WARP_TRACING_RECORDER_FILE=<trace-point-record-file> to activate the tracing extension.

post-process

The warpo_trace_visualizer is a dedicated tool designed to convert trace records generated by the wasm-compiler into perfetto formatted trace files.

Basic usage: warpo_trace_visualizer --trace-point-mapping-file <trace-point-mapping-file> --trace-point-record-file <trace-point-record-file> --output-pftrace-file <out-file>.

• <trace-point-mapping-file> is a metadata file generated by the compiler during the compilation phase, corresponding to the output path specified via the --trace-point-mapping-file command-line argument.
• <trace-point-record-file> is the binary-formatted file generated by wasm-compiler during execution, corresponding to the output path specified via WARP_TRACING_RECORDER_FILE environment variable.
• --max-slice-count N specifies the maximum number of slices to be processed. A slice is defined as a complete invocation cycle from the host environment to the WASM virtual machine. This parameter can significantly improves post-processing efficiency, particularly when handling large-scale trace records.
  By default it is unlimited.
• --count-to-perfetto-timestamp-rate specifies the ratio between the time values in the <trace-point-record-file> and actual timestamps on the perfetto timeline. Must be provided when the post-process program occurs on a different machine than where wasm-compiler executed.
  By default, it calculates dynamically assuming the CPU frequency during post-processing matches the recording phase.