tracers - Rust 仪器库

摘要

tracers 旨在成为一个易于使用且跨平台的 Rust 包，它使得将高性能低开销的探针添加到 Rust 程序变得容易。在底层，它将使用每个平台的本地探针机制，例如 Linux 上的 System Tap，BSD 上的 DTrace 和 Windows 上的 ETW。没有支持探针机制的平台将回退到无操作实现。

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

状态

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

快速入门

在您的 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。默认情况下，追踪在编译时被禁用，所以当您运行此代码时，所有的探针基础设施都将被优化掉，您将没有任何运行时开销。

要实际启用探针，您需要激活 tracers 风格库中的一个相应功能。例如，在您的 Cargo.toml

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

将启用 SystemTap 追踪。如果您重新构建并使用 BCC 中的 tplist 工具，您应该能够在二进制文件中看到探针。

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

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

平台

tracers 风格库和运行时组件应该可以在任何受支持的 Rust 平台上编译和运行（尽管 no_std 目前还不受支持）。将 tracers 添加为依赖项不应该在任何平台上破坏您的项目；如果是这样，那是一个错误，您被鼓励在 GitHub 上打开一个问题。

尽管如此，tracers 风格库默认实际上并不追踪任何内容；它编译成空。要实际启用追踪，您需要一个受支持的平台。截至本文撰写时，这意味着

• Linux 与 SystemTap（具有 force_static_stap 功能）
• Linux 与 LTT-ng（具有 force_static_lttng 功能）

正在进行工作以支持

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

许可证

除非另有说明，否则本项目根据您的选择，受以下任一许可证的约束

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

。

但是，以下 -sys 风格库具有与它们封装的第三方代码相对应的许可证

• tracers-libelf-sys - 封装 elfutils 库，因此受 LGPLv3 许可证的约束
• tracers-libstapsdt-sys - 封装 libstapsdt，因此受 MIT 许可证的约束

贡献

除非您明确表示，否则根据 Apache-2.0 许可证定义的，您提交给 tracers 的任何有意贡献，都将按照上述方式双许可，没有任何额外的条款或条件。

发布

本节仅适用于维护者。

为了发布新版本，必须首先发布依赖的crate。脚本bin/publish.sh帮助自动化此过程，但过程仍然相当手动。

发布过程

1. 将所有crate以及所有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