Rspack Sftrace

Overview

Use sftrace (LLVM XRay) to trace rspack's Rust function calls and convert them to perfetto protobuf format for performance analysis and troubleshooting.

Default workflow: run inside the target example directory (for example examples/react) and store all trace artifacts in that directory (not /tmp).

Workflow

1) Build sftrace tools

sh
1git clone https://github.com/quininer/sftrace
2cd sftrace
3cargo build --release
4mkdir "$(./target/release/sftrace record --print-solib-install-dir)"
5cp ./target/release/libsftrace.so "$(./target/release/sftrace record --print-solib-install-dir)/"

2) Build sftrace-enabled profiling binding (once per code change)

sh
1SFTRACE=1 pnpm build:binding:profiling

3) Optional: Generate a filter file from symbols

sftrace filter works on function symbols from an object file (for rspack, the binding .node file).

sh
1# Enter the target example directory first
2cd examples/react
3
4# Prefer the locally built profiling binding from the monorepo
5BINDING_NODE="$(realpath ../../crates/node_binding/rspack.linux-x64-gnu.node)"
6
7# Regex mode
8sftrace filter -p "$BINDING_NODE" -r 'finish_modules|FlagDependencyExportsPlugin' -o sftrace.filter
9
10# List mode (one regex per line)
11# sftrace filter -p "$BINDING_NODE" --list symbols.list -o sftrace.filter

If your binding file name differs by platform, replace the .node path accordingly.

4) Record sftrace (example: build in examples/react)

Run from the target example directory and keep outputs local to that example.

sh
1cd examples/react
2
3TRACE_DIR="sftrace-$(date +%Y%m%d-%H%M%S)"
4mkdir -p "$TRACE_DIR"
5
6# Full trace
7sftrace record -o "$TRACE_DIR/sf.log" -- pnpm build
8
9# Filtered trace (requires sftrace.filter from step 3)
10sftrace record -f sftrace.filter -o "$TRACE_DIR/sf.filtered.log" -- pnpm build

5) Analyze sf.log

Convert sftrace log to perfetto protobuf format.

sh
1cd examples/react
2TRACE_DIR="sftrace-YYYYMMDD-HHMMSS" # replace with your run directory
3sftrace convert "$TRACE_DIR/sf.filtered.log" -o "$TRACE_DIR/sf.filtered.pb.gz"

6) Optional: Visualization using viztracer

sh
1vizviewer --use_external_processor "$TRACE_DIR/sf.filtered.pb.gz"

Use this only for visualization.

Filtering Notes

• sftrace filter matches function symbols by regex/list. It is not a first-class crate-path/module-path filter.
• Filtering does not automatically keep all descendants. If a child function symbol does not match your filter, it may disappear from the trace.
• Cross-thread relationships (for example via rayon) are not reconstructed as a single uninterrupted call chain.
• For complete call stacks, record without filter (or with a broad filter) and narrow down during analysis.