lotabout / cargo-instruments

A cargo plugin to generate Xcode Instruments trace files

cargo-instruments

Easily generate Instruments traces for your rust crate.

cargo-instruments is 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.

Installation

First, ensure that you are running macOS, with Cargo, Xcode, and the Xcode Command Line Tools installed; then install with cargo install cargo-instruments.

Use

basic usage

cargo-instruments requires 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 --bin or --example flags.

Generate a new trace file (by default saved in /target/instruments)

$ cargo instruments [template] [--bin foo | --example bar] [--out out_file]

Open the file in Instruments.app (or pass --open to open automatically)

$ open target/instruments/my_bin_YYYY-MM-DD-THH:MM:SS.trace

Templates

Instruments has the concept of 'templates', which describe sets of dtrace probes that can be enabled. cargo-instruments will use the "Time Profiler", which collects CPU core and thread use.

examples

# profile the main binary with the Allocations template
$ cargo instruments alloc

# profile examples my_example.rs
$ cargo instruments --example my_example

Resources

Instruments Help

WWDC videos

The best source of information about Instruments is likely the various WWDC sessions over the years:

• Profiling in Depth
• Using Time Profiler in Instruments
• System Trace in Depth
• Creating Custom Instruments