#性能 #puffin #分析器 #抽象 #optick #轻薄

ambient_profiling

此crate提供了对其他分析crate的非常薄层的抽象

1 个稳定版本

1.0.9 2023年4月27日

#119分析

Download history 105/week @ 2024-03-12 107/week @ 2024-03-19 166/week @ 2024-03-26 156/week @ 2024-04-02 80/week @ 2024-04-09 137/week @ 2024-04-16 106/week @ 2024-04-23 109/week @ 2024-04-30 115/week @ 2024-05-07 99/week @ 2024-05-14 98/week @ 2024-05-21 99/week @ 2024-05-28 74/week @ 2024-06-04 68/week @ 2024-06-11 128/week @ 2024-06-18 83/week @ 2024-06-25

每月下载量:375
30 个crate(直接使用9个) 使用

MIT/Apache

32KB
267

ambient_profiling

profiling的一个非常小的分支,依赖项版本已更新。

以下是原始README。


为像puffinopticktracysuperluminal-perf这样的分析crate提供了非常薄的抽象。

按如下方式标记代码

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

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

下面是结果的可视化和更多关于暴露的API的详细信息。

友好警告:某些分析器后端在主机应用启动时隐式监听网络端口。如果这令人担忧,请查阅已启用的分析器(s)的文档以获取详细信息!

Puffin

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

Optick

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

Optick

Superluminal

Superluminal

追踪

  • https://crates.io/crates/tracing
  • 跨平台
  • 追踪后端注入与分析宏寿命相匹配的追踪宏span!()。追踪使用回调而不是内联特定的预定义代码,因此比分析(以更多代码和潜在的更高开销为代价)更灵活。这使得现有的和新追踪兼容的处理程序可以与分析一起工作。

Tracing

Tracy

Tracy

用法

目前,只有四个宏

  • profiling::scope!(name: &str, [tag: &str])
    • name: 在分析器中显示的名称
    • tag: 可选额外数据
  • #[profiling::function]
    • 函数上的procmacro,用于快速使用函数名称将其包装在作用域内
  • profiling::register_thread!([name: &str])
    • 名称:可选,默认为 std::thread::current().name,如果未命名则使用 .id
  • profiling::finish_frame!()
    • 许多分析器将“帧”视为工作单元。使用它来指示一个帧结束和下一个帧开始的位置。

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

这是为谁准备的?

  • 希望对他们的代码进行多种分析,但又不想为每个分析器的单独API重复其工具的二进制文件作者。
  • 希望为其最终用户对库进行工具化的库作者。

这个包旨在保持小巧。它不会支持所有可能的用法,只提供基本功能。我愿意添加更多功能,但计划非常慎重,以保持其紧凑性。

启用后,使用宏生成的代码与直接使用包装的分析API生成的代码相同。因此,当这个抽象不支持您想要执行的操作时,直接使用分析器的API是完全可行的。

替代方案

跟踪:与profiling相比,tracing更灵活,但体积更大,并且存在一些潜在的运行时成本。profiling仅适用于已工具化的分析。工具化直接通过宏将内联代码插入到您的代码中,就像您直接使用分析器的包一样。这导致代码更小,没有额外的开销。

直接使用分析器包(例如puffin/optick等)

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

从二进制文件使用

初始化您选择的配置文件分析器由您负责(尽管有些不需要显式初始化并且会立即工作)。示例展示了所有支持的包,但查看您感兴趣使用的分析器的文档也是值得的!profiling如果启用,则重新导出分析器包,简化了您需要修改的 Cargo.toml。

初始化后,您可以混合/匹配您选择的配置文件提供的宏以及此包中的通用宏。例如

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

一次只能启用一个后端!

示例

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

许可证

许可方式为以下之一

任选其一。

示例目录包含 NotoSans-Medium.ttf,在SIL开放字体许可证(OFL)下可用。

贡献

除非您明确声明,否则您有意提交的任何贡献,根据Apache-2.0许可证定义,都应按上述方式双重许可,不附加任何额外条款或条件。

请参阅 LICENSE-APACHELICENSE-MIT

依赖项

~0–28MB
~341K SLoC