ambient_profiling

是profiling的一个非常小的分支，具有更新的依赖版本。

以下是原始的README。

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

像这样标记你的代码

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

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

下面是结果的可视化以及关于公开API的更多详细信息。

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

Puffin

• https://github.com/EmbarkStudios/puffin
• 跨平台
• 与其他后端不同，puffin依赖于你的应用程序提供一个imgui窗口来在进程中绘制UI。下面的截图显示了一个具有可见puffin imgui窗口的分析应用程序。

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）

用法

目前，只有四个宏

• 性能分析::作用域!(名称: &字符串, [标签: &字符串])
  • 名称：在性能分析器中，作用域将显示为此名称
  • 标签：可选的额外数据
• #[性能分析::函数]
  • procmacro 放置在函数上，以便快速使用函数名将其包装在作用域中
• 性能分析::register_thread!([名称: &字符串])
  • 名称：可选，默认为 std::thread::current().name，如果未命名则为 .id
• 性能分析::finish_frame!()
  • 许多性能分析器都有“帧”这一概念，作为工作单元。使用此功能可指示一个帧的结束和下一个帧的开始。

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

这是给谁的？

• 那些希望为他们的二进制文件提供多个性能分析选项，但又不想为每个性能分析器的单独API重复仪器测量的作者。
• 那些希望为他们的库对最终用户进行测量的作者。

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

启用时，使用宏产生的代码与直接使用包装的性能分析API产生的代码相同。因此，当此抽象不支持您想做的事情时，直接使用性能分析器的API是完全可行的。

替代方案

跟踪：与 profiling 相比，tracing 更灵活，但体积更大，并且可能有一些潜在的运行时成本。 profiling 仅适用于已测量的性能分析。仪器是直接通过宏插入到您的代码中，就像您直接使用性能分析器的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中。这允许您可选地编译设置和配置后端的代码。

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

一次只能启用一个后端！

示例

• 简单：展示了进行一些简单检测分析所需的最小要求。一旦运行，您可以使用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"

许可证

许可权根据以下任一项

• Apache许可证，版本2.0，(LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT许可证 (LICENSE-MIT 或 https://open-source.org.cn/licenses/MIT)

您选择。

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

贡献

除非您明确声明，否则您有意提交以供包括在您的工作中的任何贡献，如Apache-2.0许可证中定义，将如上双许可，无需任何额外的条款或条件。

请参阅 LICENSE-APACHE 和 LICENSE-MIT。