A cargo plugin to generate Xcode Instruments trace files
Easily profile your rust crate with Xcode Instruments.
cargo-instrumentsis the glue between Cargo and Xcode's bundled profiling suite. It allows you to easily profile any binary in your crate, generating files that can be viewed in the Instruments app.
This crate only works on macOS because it uses Instruments for profiling and creating the trace file. The benefit is that Instruments provides great templates and UI to explore the Profiling Trace.
To install Xcode Instruments, simply install the Command Line Tools:
$ xcode-select --install
This crate works on macOS 10.13+. In practice, it transparently detects and uses the appropriate Xcode Instruments version based on your macOS version: either
/usr/bin/instrumentson older macOS, or starting with macOS 10.15, the new
The simplest way to install is via Homebrew:
$ brew install cargo-instruments
Alternatively, you can install from source.
First, ensure that you are running macOS, with Cargo, Xcode, and the Xcode Command Line Tools installed; then install with
$ cargo install cargo-instruments
cargo-instrumentsrequires a binary target to run. By default, it will try to build the current crate's
main.rs. You can specify an alternative binary by using the
--exampleflags, or a benchmark target with the
Assuming your crate has one binary target named
mybin, and you want to profile using the
Generate a new trace file (by default saved in
$ cargo instruments -t Allocations
Open the trace file in Instruments.app (or pass
--opento open automatically)
$ open target/instruments/mybin_Allocations_2021-05-09T12:34:56.trace
When profiling the application in release mode the compiler doesn't provide debugging symbols in the default configuration.
To let the compiler generate the debugging symbols even in release mode you can append the following section in your
[profile.release] debug = true
As usual, thanks to Clap, running
cargo instruments -hprints the compact help.
cargo-instruments 0.4.0 Profile a binary with Xcode Instruments.
By default, cargo-instruments will build your main binary.
USAGE: cargo instruments [FLAGS] [OPTIONS] [ARGS]...
FLAGS: -h, --help Prints help information -l, --list-templates List available templates --open Open the generated .trace file after profiling --release Pass --release to cargo -V, --version Prints version information
OPTIONS: --bench Benchmark target to run --bin Binary to run --example Example binary to run --features Features to pass to cargo -t, --template
cargo instruments --helpprovides more detail.
Instruments has the concept of 'templates', which describe sets of dtrace probes that can be enabled. You can ask
cargo-instrumentsto list available templates, including your custom ones (see help above). If you don't provide a template name, you will be prompted to choose one.
Typically, the built-in templates are
built-in abbrev -------------------------- Activity Monitor Allocations (alloc) Animation Hitches App Launch Core Data Counters Energy Log File Activity (io) Game Performance Leaks Logging Metal System Trace Network SceneKit SwiftUI System Trace (sys) Time Profiler (time) Zombies
# View all args and options $ cargo instruments --help
# View all built-in and custom templates $ cargo instruments --list-templates
# profile the main binary with the Allocations template $ cargo instruments -t alloc
# profile examples/my_example.rs, with the Allocations template, # for 10 seconds, and open the trace when finished $ cargo instruments -t Allocations --example my_example --time-limit 10000 --open
The best source of information about Instruments is likely the various WWDC sessions over the years: