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.

Single-Module Trace Visualization

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 <path> specifies 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 <path> specifies the binary-formatted file generated by wasm-compiler during execution, corresponding to the output path specified via the WARP_TRACING_RECORDER_FILE environment variable.
• --output-pftrace-file <path> specifies the output path for the Perfetto trace protobuf file (.pftrace / .pb).
• --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 improve post-processing efficiency, particularly when handling large-scale trace records.
  By default it is unlimited.
• --count-to-perfetto-timestamp-rate <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.

Multi-Module Trace Visualization

When running multiple Wasm modules concurrently or cooperatively, trace records contain events from different moduleIds. Use --trace-point-mapping-json-file to provide module-to-mapping configuration:

warpo_trace_visualizer --trace-point-mapping-json-file <trace-mapping.json> --trace-point-record-file <trace-point-record-file> --output-pftrace-file <out-file>

Note that --trace-point-mapping-file and --trace-point-mapping-json-file are mutually exclusive.

JSON Configuration Format

The mapping JSON must be an array of objects where each item defines a module mapping:

[
  {
    "moduleId": 1,
    "moduleName": "ModuleA",
    "mappingFile": "path/to/moduleA/trace_points.txt"
  },
  {
    "moduleId": "0x10",
    "moduleName": "ModuleB",
    "mappingFile": "path/to/moduleB/trace_points.txt"
  }
]

Fields:

• moduleId (required, integer or string): The 64-bit module identifier (supports decimal integer, decimal string, or hexadecimal string with 0x prefix).
• mappingFile (required, string): Path to the trace_points.txt file for this module (absolute or relative to the JSON file).
• moduleName (optional, string): Display name for the track in Perfetto UI. Defaults to "Module <moduleId>".

The JSON schema is available at tools/trace_visualizer/trace-mapping.schema.json.