Need help with cargo-instruments?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

cmyr
354 Stars 14 Forks MIT License 53 Commits 7 Opened issues

Description

A cargo plugin to generate Xcode Instruments trace files

Services available

!
?

Need anything else?

Contributors list

# 8,822
Rust
Python
Tensorf...
watchos
48 commits
# 147,007
HTML
Homebre...
Heroku
green-t...
2 commits
# 400,382
Emacs
nord
emacs-l...
Rust
1 commit
# 227,507
Rust
Shell
pdf-doc...
Electro...
1 commit
# 364,222
Rust
JavaScr...
jmeter
Ansible
1 commit
# 530,339
cargo
C
webrtc-...
webrtc
1 commit
# 318,644
Redis
redis-c...
connect...
cpp11
1 commit

cargo-instruments

Easily profile your rust crate with Xcode Instruments.

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

Instruments Time Profiler Instruments System Trace

Pre-requisites

Xcode Instruments

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

Compatibility

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/instruments
on older macOS, or starting with macOS 10.15, the new
xcrun xctrace
.

Installation

brew

The simplest way to install is via Homebrew:

$ brew install cargo-instruments

Alternatively, you can install from source.

Building 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

Usage

Basic

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, or a benchmark target with the
--bench
flag.

Assuming your crate has one binary target named

mybin
, and you want to profile using the
Allocations
Instruments template:

Generate a new trace file (by default saved in

target/instruments
)
$ cargo instruments -t Allocations

Open the trace file in Instruments.app (or pass

--open
to open automatically)
$ open target/instruments/mybin_Allocations_2021-05-09T12:34:56.trace

Profiling application in release mode

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

Cargo.toml
.
[profile.release]
debug = true

All options

As usual, thanks to Clap, running

cargo instruments -h
prints 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

And

cargo instruments --help
provides more detail.

Templates

Instruments has the concept of 'templates', which describe sets of dtrace probes that can be enabled. You can ask

cargo-instruments
to 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

Examples

# 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

Resources

Instruments Help

WWDC videos

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.