cargo-instruments

使用 Xcode Instruments 轻松分析您的 Rust 库。

cargo-instruments 是 Cargo 和 Xcode 内置分析套件之间的粘合剂。它允许您轻松分析库中的任何二进制文件，生成可以在 Instruments 应用中查看的文件。

先决条件

Xcode Instruments

此库仅在 macOS 上工作，因为它使用 Instruments 进行分析并创建跟踪文件。好处是 Instruments 提供了很好的模板和用户界面来探索分析跟踪。

要安装 Xcode Instruments，只需安装命令行工具即可

$ xcode-select --install

兼容性

此库在 macOS 10.13+ 上工作。实际上，它透明地检测并使用基于您的 macOS 版本的适当 Xcode Instruments 版本：在旧版 macOS 上为 /usr/bin/instruments，从 macOS 10.15 开始为新 xcrun xctrace。

安装

brew

最简单的方法是使用 Homebrew 安装

$ brew install cargo-instruments

或者，您可以从源代码安装。

从源代码构建

首先，请确保您正在运行 macOS，并且已安装 Cargo、Xcode 和 Xcode 命令行工具。

如果已安装 OpenSSL（例如，通过 brew），则可以使用以下命令安装：

$ cargo install cargo-instruments

如果未安装 OpenSSL 或如果 cargo install 安装失败并显示以 "无法找到 OpenSSL 安装目录" 开头的错误消息，则可以使用以下命令安装：

$ cargo install --features vendored-openssl cargo-instruments

在 nix 上从源代码构建

如果您正在使用 nix，则此命令应提供所有依赖项并从源代码构建 cargo-instruments

$ nix-shell --command 'cargo install cargo-instruments' --pure -p \
	darwin.apple_sdk.frameworks.SystemConfiguration \
	darwin.apple_sdk.frameworks.CoreServices \
	rustc cargo sccache libgit2 pkg-config libiconv \
	llvmPackages_13.libclang openssl

用法

基本

cargo-instruments 需要一个二进制目标来运行。默认情况下，它将尝试构建当前crate的 main.rs。您可以通过使用 --bin 或 --example 标志来指定一个替代的二进制文件，或者使用 --bench 标志来指定一个基准目标。

假设您的crate有一个名为 mybin 的二进制目标，并且您想使用 Allocations Instruments模板进行性能分析

生成一个新的跟踪文件（默认保存在 target/instruments）

$ cargo instruments -t Allocations

手动在Instruments.app中打开跟踪文件

默认情况下，跟踪文件将立即使用 Instruments.app 打开。如果您不希望这种行为，请使用 --no-open 标志。

$ open target/instruments/mybin_Allocations_2021-05-09T12_34_56.trace

如果有多个包，您可以使用 --package 标志来指定要分析的性能的包。

例如，您使用Cargo的workspace来管理多个包。要分析包 foo 中的bin bar

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

在许多情况下，一个包只有一个二进制文件。在这种情况下，--package 的行为与 --bin 相同。

在发布模式下分析应用程序

在发布模式下分析应用程序时，编译器不会在默认配置中提供调试符号。

要让编译器即使在发布模式下也生成调试符号，您可以在您的 Cargo.toml 中追加以下部分。

[profile.release]
debug = true

所有选项

通常，由于Clap，运行 cargo instruments -h 会打印紧凑的帮助信息。

cargo-instruments 0.4.8
Profile a binary with Xcode Instruments.

By default, cargo-instruments will build your main binary.

USAGE:
    cargo instruments [FLAGS] [OPTIONS] --template <TEMPLATE> [ARGS]...

FLAGS:
    -h, --help                   Prints help information
    -l, --list-templates         List available templates
        --no-open                Do not open the generated trace file in Instruments.app
        --release                Pass --release to cargo
    -V, --version                Prints version information
        --all-features           Activate all features for the selected target
        --no-default-features    Do not activate the default features for the selected target

OPTIONS:
        --bench <NAME>                 Benchmark target to run
        --bin <NAME>                   Binary to run
        --example <NAME>               Example binary to run
        --features <CARGO-FEATURES>    Features to pass to cargo
        --manifest-path <PATH>         Path to Cargo.toml
    -p, --package <NAME>               Specify package for example/bin/bench
        --profile <NAME>               Pass --profile NAME to cargo
    -t, --template <TEMPLATE>          Specify the instruments template to run
        --time-limit <MILLIS>          Limit recording time to the specified value (in milliseconds)
    -o, --output <PATH>                Output .trace file to the given path

ARGS:
    <ARGS>...    Arguments passed to the target binary

EXAMPLE:
    cargo instruments -t time    Profile main binary with the (recommended) Time Profiler.

而 cargo instruments --help 会提供更多细节。

模板

Instruments有“模板”的概念，它描述了一组可以启用的dtrace探测。您可以要求 cargo-instruments 列出可用的模板，包括您的自定义模板（见上面的帮助）。如果您没有提供模板名称，您将被提示选择一个。

通常，内置的模板包括

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

资源

Instruments帮助

WWDC视频

有关Instruments的最佳信息来源可能是多年来各种WWDC会议

• 深度分析
• 在Instruments中使用时间分析器
• 系统跟踪深度
• 创建自定义Instruments