Profiling Turbopack

On macOS

Install cargo-instruments (opens in a new tab)

cargo install cargo-instruments

Make sure you have all the prerequisites (opens in a new tab) for running cargo-instruments.

Run the profiler

By default, turbopack-cli dev will keep watching for changes to your application and never exit until you manually interrupt it. However, cargo-instruments (opens in a new tab) waits for your program to exit before building and opening the trace file. For this purpose, we've added a profile feature to turbopack-cli which exits the program if no updates are detected within a given time frame and there are no pending tasks.

To profile turbopack-cli, run the following command:

cargo instruments -t time --bin turbopack-cli --release --features profile [-- [...args]]

You can also run other templates (opens in a new tab) than the time profiler.

Once the program exits, the profiler will open the trace file in Instruments. Refer to the learning resources (opens in a new tab) to learn how to use Instruments.

An example trace from the time profiler.


Memory usage

# Install `heaptrack` and `heaptrack_gui`
sudo apt install heaptrack heaptrack_gui
# Compile with debug info but without the alternative allocator:
CARGO_PROFILE_RELEASE_DEBUG=1 cargo build --bin turbopack-cli --release --no-default-features --features native-tls
# Run the binary with heaptrack (it will be much slower than usual)
heaptrack target/release/turbopack-cli [...]
# Stop it anytime
# Open the GUI and open the heaptrack.turbopack-cli.XXX.gz file

On other platforms

We currently don't have a guide for profiling Turbopack on other platforms.