profiling

为像 puffin、optick、tracy 和 superluminal-perf 这样的已部署性能分析crate提供了一个非常薄的抽象层。

像这样标记你的代码

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

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

见下文以获取生成的可视化效果和更多关于暴露的API的详细信息。

友好的警告：一些性能分析后端在宿主应用启动时隐式地监听网络端口。如果这令你担忧，请查阅已启用的性能分析器（s）文档以获取详细信息！

Puffin

• 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。

Superluminal

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

跟踪

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

Tracy

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

使用方法

目前，只有六个宏

• profiling::作用域!(名称: &字符串, [标签: &字符串])
  • 名称：作用域将在分析器中以该名称显示
  • 标签：可选额外数据
• #[profiling::函数]
  • 将此宏放置在函数上，以便快速使用函数名将其包装在作用域内
• #[profiling::所有函数]
  • 将此宏放置在结构体实现块上，以将 #[profiling::function] 应用到该结构体实现块下的每个函数
• #[profiling::跳过]
  • 与 #[profiling::all_functions] 一起使用，将此宏放置在函数上以避免 #[profiling::all_functions] 应用的操作
• profiling::注册线程!([名称: &字符串])
  • 名称：可选，默认为 std::thread::current().name，如果未命名，则为 .id
• profiling::完成帧!()
  • 许多分析器都有“帧”的概念，它是工作单元。使用此功能可指示一个帧结束和下一个帧开始的位置。

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

这是给谁的？

• 希望对他们的代码进行性能分析的二进制文件作者，但不想为每个分析器的API重复他们的仪器一次。
• 希望为最终用户对他们的crate进行仪器化的库作者。

这个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");

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

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

}

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

我建议将您想要使用的后端功能添加到您的二进制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夜间更快。（见python/mozboot/mozboot/util.py中的MINIMUM_RUST_VERSION）

许可

根据以下任一许可进行许可：

• Apache License，版本2.0，(LICENSE-APACHE或http://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可(LICENSE-MIT或http://opensource.org/licenses/MIT）

由你选择。

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

贡献

除非你明确说明，否则你提交的任何有意包含在作品中的贡献，根据Apache-2.0许可定义，应如上双许可，无需任何额外条款或条件。

见LICENSE-APACHE和LICENSE-MIT。