tracers - Rust性能监控库

摘要

tracers旨在成为一个易于使用且跨平台的Rust crate，它使得向Rust程序中添加高性能低开销探针变得简单。在其下面，它将使用每个平台的本地探针机制，如Linux上的System Tap、BSD上的DTrace和Windows上的ETW。那些没有支持探针机制的平台将回退到无操作实现。

此crate的关键目标是在任何Rust项目中添加它，在任何合理的地方创建和触发探针，并且始终保留这些探针。当探针在编译时被禁用时，应该没有运行时影响，当探针被编译但在运行时不启用时，探针的影响不应超过一到两条CPU指令。

状态

重要：tracers仍然是实验性的。作者正在内部使用它，但此crate尚未广泛使用，可能包含微妙且关键的错误。

快速入门

在你的Cargo.toml中，你需要添加

[dependencies]
...
tracers = "0.1.0"
tracers-macros = "0.1.0"

[build-dependencies]
...
tracers-build = "0.1.0"

不要忘记将 tracers-build 添加到你的 build-dependencies 中，因为构建时你需要它来执行下一步，即创建一个 src/build.rs 文件（如果你还没有的话），并确保它包含以下内容：

use tracers_build::build;

fn main() {
build();
}

如果你已经有了一个 build.rs 文件，你需要确保在 main 函数中某个地方添加对 tracers_build::build() 的调用，最好是在早期。

到此为止，你已经拥有了定义跟踪器所需的一切。以下是一个简单的示例：

use tracers_macros::{probe, tracer};

#[tracer]
trait SimpleProbes {
fn hello(who: &str);
fn greeting(greeting: &str, name: &str);
fn optional_greeting(greeting: &str, name: &Option<&str>);
}

fn main() {
loop {
    probe!(SimpleProbes::hello("world"));
    probe!(SimpleProbes::greeting("hello", "world"));
    let name = Some("world");
    probe!(SimpleProbes::optional_greeting("hello", &name));
    let name: Option<&str> = None;
    probe!(SimpleProbes::optional_greeting("hello", &name));
}
}

你已经定义了三个探针：hello、greeting 和 optional_greeting。默认情况下，在编译时跟踪是被禁用的，所以当你运行此代码时，所有的探针基础设施都将被优化掉，你将没有任何运行时开销。

要实际启用探针，你需要激活 tracerscrate 中相应的功能。例如，在你的 Cargo.toml 文件中

[dependencies]
...
tracers = { version = "0.1.0", features = [ "force_static_stap"]

将启用 SystemTap 跟踪。如果你再次构建并使用来自 BCC 的工具 tplist，你应该能在二进制文件中看到探针。

注意，#[tracers] 宏为你生成了关于特质的某些有用文档。尝试使用 cargo doc 并在文档中找到你的特质，以获取关于如何使用每个探针的额外提示。

examples/ 目录中有一些简单的示例。

平台

tracers crate 和运行时组件应该在任何受支持的 Rust 平台上编译和运行（尽管目前不支持 no_std）。将 tracers 作为依赖项添加到你的项目中不应该在任何平台上破坏你的项目；如果确实如此，那么这是一个错误，我们鼓励你打开一个 GitHub 问题。

但是，默认情况下，tracers crate 不会实际跟踪任何内容；它编译为无内容。要实际启用跟踪，你需要一个受支持的平台。截至本文写作时，这意味着：

• Linux 与 System Tap（使用 force_static_stap 功能）
• Linux 与 LTT-ng（使用 force_static_lttng 功能）

正在进行支持以下平台的工作：

• Windows（使用 Windows 系统API的事件跟踪）
• FreeBSD 和 macOS（使用 DTrace）

许可证

除非另有说明，否则本项目根据 Apache License, Version 2.0 或 MIT 许可证授权，任选其一。

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

任选其一。

但是，以下 -sys crate 的许可证与它们包装的第三方代码的许可证相对应：

• tracers-libelf-sys - 包装了 elfutils 库，因此许可证为 LGPLv3
• tracers-libstapsdt-sys - 包装了 libstapsdt，因此许可证为 MIT

贡献

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

发布

本节仅适用于维护者。

要发布新版本，必须首先发布依赖的crates。bin/publish.sh 脚本有助于自动化流程，但仍需手动操作。

发布流程

1. 更新所有crates及其依赖的其它 tracers crates 的 version 属性为新目标版本。

2. 确保所有依赖项都既有本地开发的路径依赖，又有发布时的版本依赖。这些必须与新发布的版本保持一致。

3. 更新 documentation 链接以反映当前版本。

crates 必须按以下顺序发布

• tracers-core
• tracers-libelf-sys
• tracers-libstapsdt-sys
• tracers-codegen
• tracers-macros-hack
• tracers-macros
• tracers-dyn-stap
• tracers-dyn-noop
• tracers-build
• tracers