性能分析

为像 puffin、optick、tracy 和 superluminal-perf 这样的受测分析器crate提供了非常薄的抽象层。

请按照以下方式标记你的代码

#[profiling::function]
fn some_function() {
    burn_time(5);

    for i in 0..5 {
        profiling::scope!("Looped Operation");
    }
}

下面展示了结果的可视化以及暴露的API的更多详细信息。

友情提示：某些分析器后端在启动主机应用时会隐式监听网络端口。如果你对此有顾虑，请查看已启用的分析器(们)的文档以获取详细信息！

海豚

• https://github.com/EmbarkStudios/puffin
• 跨平台
• 你需要每帧至少调用一次 profiling::finish_frame!()
• 要显示火焰图，你需要使用 puffin_http 和 puffin_viewer，或者如果你在编写一个 egui 应用，使用 puffin_egui。

Optick

• https://github.com/bombomby/optick
• 上游crate仅提供Windows的二进制文件。但是，通过手动构建optick捕获代码并链接到它，可能使其工作。UI仅限Windows。

超光速

• https://superluminal.eu
• 仅限Windows

跟踪

• https://crates.io/crates/tracing
• 跨平台
• 跟踪后端注入与性能分析宏生命周期匹配的跟踪宏 span!()。跟踪使用回调而不是内联预定义的特定代码，因此比性能分析更灵活（但代价是代码行数更多，可能产生更高的开销）。这允许现有的和新颖的跟踪兼容处理程序与性能分析一起工作。

Tracy

• https://github.com/wolfpld/tracy
• 跨平台（Windows，macOS，Linux）

用法

目前，只有六个宏

• 性能分析::scope!(name: &str, [tag: &str])
  • name: 在分析器中显示此名称的名称
  • tag: 可选的额外数据
• #[性能分析::function]
  • procmacro 放在函数上，用于快速使用函数名称将其封装在作用域内
• #[性能分析::all_functions]
  • procmacro 放在结构体实现块上，以在该结构体实现块下的每个函数上应用 #[profiling::function]
• #[性能分析::skip]
  • 与 #[profiling::all_functions] 一起使用，将此 procmacro 放在函数上，以避免应用 #[profiling::all_functions] 的操作
• 性能分析::register_thread!([name: &str])
  • name: 可选，默认为 std::thread::current().name，如果未命名，则为 .id
• 性能分析::finish_frame!()
  • 许多分析器都有“框架”的概念，作为工作单元。使用此宏来指示一个框架结束和下一个框架开始的位置。

可以通过功能标志打开或关闭对个别分析器的支持。默认情况下，它们都关闭，结果是没有依赖关系或运行时代码。

这是为谁准备的？

• 编写希望对代码进行多种分析选项的二进制文件的开发者，但不想在分析器的每个API中重复使用其工具。
• 希望为其最终用户对库进行工具化的库的开发者。

此crate旨在保持小型。它不会支持所有可能的用法，仅支持基本功能。我愿意添加更多功能，但我计划非常谨慎，以保持其体积较小。

启用时，使用宏生成的代码与直接使用封装的性能分析API生成的代码相同。因此，当抽象不支持您想要执行的操作时，可以直接使用分析器的API。

替代方案

跟踪：跟踪比 性能分析 更灵活，但体积更大，并且可能产生一些潜在的运行时成本。仅适用于已进行工具化的性能分析。工具化是直接通过宏将工具插入到您的代码中，就像您直接使用分析器crate一样。这导致代码更小，没有额外的开销。

直接使用性能分析crate（例如，puffin/optick等）

• 对于二进制文件的作者，您可能仍需要使用这些crate上的API来入门。但在对代码进行测试时，可以在函数内部使用profiling::scope!("Scope Name")，或者在函数上使用#[profiling::function]来测试所有支持的由特定分析器定制的crate。如果您想利用它们提供的自定义API来展示额外数据，可以直接使用这些crate。
• 对于上游库的作者，这个crate允许您一次实现简单的测试。希望这能让社区从测试分析中受益，即使代码库的大部分是上游crate。

从二进制文件中使用

初始化您选择的测试crate由您自己决定（尽管有些不需要显式初始化并且会立即生效）。示例为所有支持的crate展示了这一点，但查看您感兴趣使用的分析器的文档也很值得！profiling如果已启用，会重新导出分析器crate，简化了您需要修改的Cargo.toml。

初始化后，您可以混合使用您选择的分析器提供的宏和本crate中提供的通用宏。例如

// This may map to something like:
// - puffin::profile_scope!("Scope Name")
// - optick::event!("Scope Name")
// - tracing::span!(tracing::Level::INFO, "Scope Name")
// - superluminal_perf::begin_event("Scope Name")
profiling::scope!("Scope Name");

// This may map to something like:
// - puffin::profile_scope_data!("Scope Name", "extra data")
// - optick::event!("Scope Name"); optick::tag!("tag", "extra data");
// - tracing::span!(tracing::Level::INFO, "Scope Name", tag = "extra data")
// - superluminal_perf::begin_event_with_data("Scope Name", "extra data", 0)
profiling::scope!("Scope Name", "extra data");

还有一个用于装饰函数的过程宏

#[profiling::function]
fn my_function() {

}

查看以下有用的宏的代码：register_thread!()和finish_frame!()。

我建议将每个想要在二进制crate中使用的后端的功能添加到您的binary crate中。这允许您可选地编译设置和配置后端的代码。

[dependencies]
profiling = "1.0"

[features]
profile-with-puffin = ["profiling/profile-with-puffin"]
profile-with-optick = ["profiling/profile-with-optick"]
profile-with-superluminal = ["profiling/profile-with-superluminal"]
profile-with-tracing = ["profiling/profile-with-tracing"]
profile-with-tracy = ["profiling/profile-with-tracy"]

• 您可以使用默认功能快速/临时启用某些功能：default = ["profile-with-optick"]
• cargo run --features=profile-with-optick也适用！

从库中使用

将测试crate添加到Cargo.toml

[dependencies]
profiling = "1.0"

现在您可以使用通过profiling crate公开的API来测试您的库。

如果您的库的最终用户不使用测试，这个crate中的宏将不会产生任何代码。

功能标志

• profile-with-puffin: 启用puffin crate
• profile-with-optick: 启用optick crate
• profile-with-superluminal: 启用superluminal-perf crate
• profile-with-tracing: 启用tracing crate。 (这是一个抽象层 - 您想将其连接到做某事！)
• profile-with-tracy: 启用tracy-client crate。

一次只能启用一个后端！

示例

• simple: 显示进行一些简单测试的最基本要求。一旦运行，您就可以使用optick/tracy/superluminal连接到该进程。其中一些仅在Windows上运行！

run --example simple --features="profile-with-optick"
run --example simple --features="profile-with-tracy"
run --example simple --features="profile-with-puffin"
run --example simple --features="profile-with-superluminal"

• puffin: 使用imgui集成启动一个基本应用程序，显示puffin UI。这个应该可以在支持imgui的所有地方运行。

cargo run --example puffin --features="profile-with-puffin"

MSRV

该项目将努力保持保守的MSRV，但实际上这很可能是受上游crate MSRV的限制。可能某些后端将支持比其他后端更低的MSRV。

由于MSRV的实际值取决于启用的功能，因此不会在cargo.toml中设置MSRV。否则，这个crate将只能使用所有可能的上游分析后端中最不保守的MSRV进行编译。

作为参考，目前最流行的依赖分析crate是wgpu，其MSRV被限制在Firefox夜间构建的MSRV。因此，这个crate的MSRV（不考虑后端）不应比wgpu和firefox夜间版本更新更快。（参见 MINIMUM_RUST_VERSION 在 python/mozboot/mozboot/util.py）

许可证

根据您选择的以下之一许可：

• Apache License，版本 2.0，（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT 许可证（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

任选其一。

示例目录包含在SIL开源字体许可证（OFL）下可用的 NotoSans-Medium.ttf。

贡献

除非您明确说明，否则根据Apache-2.0许可证定义，您提交的任何有意包含在作品中的贡献都将根据上述方式双许可，没有额外的条款或条件。

请参阅 LICENSE-APACHE 和 LICENSE-MIT。