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 crate 中的相应功能之一。例如，在您的 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，版本 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 许可

贡献

除非您明确表示，否则您提交给 tracers 以供包含的贡献，根据 Apache-2.0 许可证的定义，将作为上述双重许可，没有任何附加条款或条件。

发布

本节仅适用于维护者。

要发布新版本，必须首先发布依赖项。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-dyn-stap
• tracers-dyn-noop
• tracers构建
• 追踪器