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

要实际上启用探测，您需要在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带有System Tap（force_static_stap功能）
• Linux带有LTT-ng（force_static_lttng功能）

正在进行工作以支持

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

许可证

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

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

。

然而，以下-sys存储库的许可证与它们封装的第三方代码的许可证相对应

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

贡献

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

发布

本节仅适用于维护者。

要发布新版本，必须首先发布依赖项存储库。bin/publish.sh脚本能帮助自动化此过程，但仍相当手动。

发布流程

1. 将所有存储库及其对其他tracers存储库的依赖项的version属性更新为新目标版本。

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

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

存储库必须按照以下顺序发布

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