Profiling with rustc-perf

The Rust benchmark suite provides a comprehensive way of profiling and benchmarking the Rust compiler. You can find instructions on how to use the suite in its manual.

However, using the suite manually can be a bit cumbersome. To make this easier for rustc contributors, the compiler build system (bootstrap) also provides built-in integration with the benchmarking suite, which will download and build the suite for you, build a local compiler toolchain and let you profile it using a simplified command-line interface.

You can use the ./x perf <command> [options] command to use this integration.

You can use normal bootstrap flags for this command, such as --stage 1 or --stage 2, for example to modify the stage of the created sysroot. It might also be useful to configure bootstrap.toml to better support profiling, e.g. set rust.debuginfo-level = 1 to add source line information to the built compiler.

x perf currently supports the following commands:

• benchmark <id>: Benchmark the compiler and store the results under the passed id.
• compare <baseline> <modified>: Compare the benchmark results of two compilers with the two passed ids.
• eprintln: Just run the compiler and capture its stderr output. Note that the compiler normally does not print anything to stderr, you might want to add some eprintln! calls to get any output.
• samply: Profile the compiler using the samply sampling profiler.
• cachegrind: Use Cachegrind to generate a detailed simulated trace of the compiler’s execution.

You can find a more detailed description of the profilers in the rustc-perf manual.

You can use the following options for the x perf command, which mirror the corresponding options of the profile_local and bench_local commands that you can use in the suite:

• --include: Select benchmarks which should be profiled/benchmarked.
• --profiles: Select profiles (Check, Debug, Opt, Doc) which should be profiled/benchmarked.
• --scenarios: Select scenarios (Full, IncrFull, IncrPatched, IncrUnchanged) which should be profiled/benchmarked.

Example profiling diff for external crates

It can be of interest to generate a local diff for two commits of the compiler for external crates. To start, in the rustc-perf repo, build the collector, which runs the Rust compiler benchmarks as follows.

cargo build --release -p collector

The collector can then be run using cargo, specifying the collector binary. It expects the following arguments:

• <PROFILE>: Profiler selection for how performance should be measured. For this example we will use Cachegrind.
• <RUSTC>: The Rust compiler revision to benchmark, specified as a commit SHA from rust-lang/rust. Optional arguments allow running profiles and scenarios as described above. More information regarding the mandatory and optional arguments can be found in the rustc-perf-readme-profilers.

Then, for the case of generating a profile diff for the crate serve_derive-1.0.136, for two commits <SHA1> and <SHA2> from the rust-lang/rust repository, run the following in the rustc-perf repo:

cargo run --release --bin collector profile_local cachegrind +<SHA1> --rustc2 +<SHA2> --exact-match serde_derive-1.0.136 --profiles Check --scenarios IncrUnchanged