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] 宏会为你生成的 trait 生成一些有用的文档。尝试 cargo doc 并在文档中查找你的 trait，以获得有关如何使用每个探测点的额外提示。

examples/ 目录中包含一些简单示例。

平台

tracers crate 和运行时组件应该可以在任何受支持的 Rust 平台上编译和运行（尽管 no_std 还不支持）。将 tracers 添加为依赖项不应该在任何平台上破坏你的项目；如果这样做，那就是一个错误，并且鼓励你提交一个 GitHub 问题。

话虽如此，tracers crate 默认实际上并不跟踪任何东西；它编译为空。要实际启用跟踪，你需要一个受支持的平台。截至本文写作，这意味着

• 带有 System Tap 的 Linux（具有 force_static_stap 功能）
• 带有 LTT-ng 的 Linux（具有 force_static_lttng 功能）

正在进行工作以支持

• 带有 Windows（具有 Windows 系统API的事件跟踪）
• FreeBSD 和 macOS（具有 DTrace）

许可证

除非另有说明，否则此项目根据以下任一许可证进行许可

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

任选其一。

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

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

贡献

除非你明确声明，否则你提交给 tracers 项目的任何贡献，根据 Apache-2.0 许可证的定义，应作为上述双重许可，不附加任何其他条款或条件。

发布

本节仅适用于维护者。

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

发布流程

1. 更新所有crate及其对其他tracers crate的依赖的version属性，到新目标版本。

2. 确保所有依赖项都具有本地开发的路径依赖关系和发布版本依赖关系。这些必须与新版本发布的内容保持一致。

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

crate必须按以下顺序发布

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

lib.rs:

简单地重新导出tracers-codegen中的构建相关函数。