cargo-instruments

You can install cargo-instruments using Homebrew or by building from source.

Via Homebrew

brew install cargo-instruments

Via Cargo (Building from Source)

If you have OpenSSL installed (e.g., via brew):

cargo install cargo-instruments

If you encounter OpenSSL errors (e.g., Could not find directory of OpenSSL installation...), use the vendored-openssl feature:

cargo install --features vendored-openssl cargo-instruments

cargo-instruments allows you to profile binary targets, examples, or benchmarks using Xcode Instruments templates.

Basic Usage

By default, it profiles the crate's main.rs. To profile a specific target, use --bin, --example, or --bench.

To profile the Allocations template for the main binary:

cargo instruments -t Allocations

Workspace and Specific Targets

To profile a specific binary (bar) within a specific package (foo) in a workspace:

cargo instruments --package foo --template alloc --bin bar

Profiling in Release Mode

To see debugging symbols when profiling in release mode, you must enable them in your Cargo.toml:

[profile.release]
debug = true

cargo-instruments requires macOS and a full installation of Xcode (not just Command Line Tools) to use the Instruments profiling suite.

1. Install Xcode from the App Store.
2. Verify installation by running xctrace. It should print help output.
3. Check developer directory: Run xcode-select --print-path. It should return /Applications/Xcode.app/Contents/Developer.
4. Fix path if necessary: If the path is incorrect, reset it using:

sudo xcode-select --reset

The library abstracts the differences between the modern xctrace tool and the legacy instruments binary.

When using xctrace, the tool constructs a command using xcrun xctrace record with flags like --template, --time-limit, and --output. It also attempts to redirect stdin/stdout to the current TTY to ensure interactive compatibility.

When using the legacy instruments binary, it uses flags like -t for templates, -D for the destination path, and -l for the time limit.

The tool can target specific binaries, examples, or benchmarks. When a specific target is provided, cargo-instruments uses Cargo's compilation logic to build only that unit, minimizing build time.

Supported target types include:

• Binaries: Standard executable targets.
• Examples: Targets located in the examples/ directory.
• Benchmarks: Benchmark targets (e.g., using criterion).

If multiple targets are found for a single command, the tool will return an error to prevent ambiguous profiling.

The cargo instruments command profiles a Rust binary using Xcode Instruments. It uses templates to define which instrument to run (e.g., Time Profiler, Allocations).

To see a list of available templates, use the --list-templates flag.

Note on Target Arguments: To pass arguments directly to your target binary, use the -- separator. Everything following -- is treated as an argument for the binary being profiled, not for cargo-instruments.

# Profile the main binary with the Time Profiler
cargo instruments -t time

# Profile a specific example with arguments passed to the example
cargo instruments -t alloc -- --example-arg

Instruments uses 'templates' to define sets of dtrace probes. You can list all available templates (including custom ones) using the --list-templates flag. If you don't provide a template name when running a profile, you will be prompted to choose one.

Common built-in templates include:

• Time Profiler (time)
• Allocations (alloc)
• System Trace (sys)
• File Activity (io)
• Leaks

cargo instruments --list-templates

The XcodeInstruments::detect() method determines which profiling tool is available on the system. It checks the macOS version to decide between the modern xctrace tool or the legacy instruments binary.

• XcTrace: Used on macOS 10.15 and newer if Xcode or Command Line Tools are installed.
• InstrumentsBinary: The legacy tool used on older macOS versions.

If neither is found, it returns an error indicating that Xcode or Xcode Command Line Tools must be installed.

let instruments_version = XcodeInstruments::detect()?;
match instruments_version {
    XcodeInstruments::XcTrace => println!("Using xctrace"),
    XcodeInstruments::InstrumentsBinary => println!("Using legacy instruments"),
}

You can retrieve a list of available profiling templates (both standard and custom) using the available_templates() method on an XcodeInstruments instance. This returns a TemplateCatalog containing two vectors: standard_templates and custom_templates.

To display these templates in a human-readable format with abbreviations, use render_template_catalog().

let instruments = XcodeInstruments::detect()?;
let catalog = instruments.available_templates()?;
println!("{}", render_template_catalog(&catalog));