17个版本
| 0.5.0 | 2024年1月24日 |
|---|---|
| 0.4.1 |
|
| 0.3.5 | 2022年12月15日 |
| 0.3.4 | 2022年11月22日 |
| 0.1.12 | 2021年3月26日 |
#16 in 性能分析
9,743 每月下载量
用于 5 个crate（3个直接使用）
220KB
3.5K SLoC
usdt
使用USDT探针给你的Rust除尘。
概述
usdt将静态定义的DTrace探针暴露给Rust代码。用户编写一个提供者定义，可以使用D语言或直接在Rust代码中。然后，提供者的探针可以编译成触发探针的Rust代码。这些可以通过dtrace命令行工具看到。
将D探针定义转换为Rust有三种机制。
- 一个
build.rs脚本 - 一个类似函数的过程宏，
usdt::dtrace_provider。 - 一个属性宏，
usdt::provider。
生成的代码在所有情况下都是相同的，尽管第三种比前两种提供更多的灵活性。有关更多详细信息，请参阅下面，但简要地说，第三种形式支持任何实现了serde::Seralize类型的探针参数。这些不同版本分别在crate probe-test-{build,macro,attr}中展示。
注意：此crate使用内联汇编来实现其魔法。有关在Rust 1.59之前以及macOS 1.66之前的用法，请参阅说明。
示例
此包中的probe-test-build二进制crate实现了一个完整的示例，使用构建时代码生成。
起始点是名为 "test.d" 的 D 脚本。它看起来像这样：
provider my_provider {
probe start_work(uint8_t);
probe stop_work(char*, uint8_t);
};
此脚本定义了一个名为 test 的单一提供者，具有两个探针 start 和 stop，它们具有不同的参数集。（目前支持整数原始类型、整数类型的指针以及 &str。请注意，char* 用于表示 Rust 风格的 UTF-8 字符串。如果您需要一个字节数组，请使用 uint8_t* 或 int8_t*。）
此提供者定义必须转换为 Rust 代码，这可以通过一个简单的构建脚本完成。
use usdt::Builder;
fn main() {
Builder::new("test.d").build().unwrap();
}
这将在 OUT_DIR 目录中生成一个文件，该文件包含启动探针的生成 Rust 宏。除非更改，否则该文件将与提供者定义文件同名，因此在此例中为 test.rs。
在 Rust 代码中使用探针看起来如下，它位于 probe-test-build/src/main.rs。
//! An example using the `usdt` crate, generating the probes via a build script.
use std::thread::sleep;
use std::time::Duration;
use usdt::register_probes;
// Include the Rust implementation generated by the build script.
include!(concat!(env!("OUT_DIR"), "/test.rs"));
fn main() {
let duration = Duration::from_secs(1);
let mut counter: u8 = 0;
// NOTE: One _must_ call this function in order to actually register the probes with DTrace.
// Without this, it won't be possible to list, enable, or see the probes via `dtrace(1)`.
register_probes().unwrap();
loop {
// Call the "start_work" probe which accepts a u8.
my_provider::start_work!(|| (counter));
// Do some work.
sleep(duration);
// Call the "stop_work" probe, which accepts a &str and a u8.
my_provider::stop_work!(|| ("the probe has fired", counter));
counter = counter.wrapping_add(1);
}
}
注意：在 1.59（以及 macOS 上的 1.66）之前，需要夜间功能。请参阅 注释 了解讨论。
还可以看到，Rust 代码是通过 include! 宏直接包含的。探针定义被转换为 Rust 宏，以提供者的名称命名模块，并使用探针命名的宏。在我们的例子中，第一个探针被转换为宏 my_provider::start_work!。
重要：请注意，应用程序 必须 调用
usdt::register_probes()才能将探针点实际注册到 DTrace。不这样做不会影响应用程序的功能，但如果没有这个，将无法使用dtrace(1)工具列出、启用或以其他方式查看探针。
我们可以通过运行示例并按名称列出预期探针来看到这是如何与 DTrace 连接的。
$ cargo run
在另一个终端中，使用以下内容列出匹配的探针：
$ sudo dtrace -l -n my_provider*:::
ID PROVIDER MODULE FUNCTION NAME
2865 test14314 probe-test-build _ZN16probe_test_build4main17h906db832bb52ab01E [probe_test_build::main::h906db832bb52ab01] start_work
2866 test14314 probe-test-build _ZN16probe_test_build4main17h906db832bb52ab01E [probe_test_build::main::h906db832bb52ab01] stop_work
探针参数
可以看到，探针宏是通过闭包而不是直接通过探针参数调用的。这有两个目的。
首先，它表明探针参数可能不会被评估。DTrace 为定义的探针生成 "is-enabled" 探针，这是一种简单的方法来检查探针是否当前已启用。只有在探针启用的情况下，才会展开参数，因此用户 必须 不要依赖于副作用。闭包有助于表明这一点。
其次，这是关于效率。同样，如果探针未启用，则不会评估参数。闭包仅在探针被验证为启用后内部评估，这避免了如果探针未启用，则进行参数打包的无效工作。
过程宏版本
此 crate 的过程宏版本可以在 probe-test-macro 示例中看到，它与上面的示例几乎相同。然而，没有 build.rs 脚本，因此，在 include! 宏的位置，我们可以找到过程宏。
dtrace_provider!("test.d");
此宏生成与上面看到的相同的宏，但在源代码本身编译时进行。这可能对某些用例来说更容易，因为没有构建脚本。然而，过程宏也有缺点。理解它们的内部结构可能很困难，尤其是在出错时。此外，即使在提供者定义没有更改的情况下，宏也会在每次编译时运行。对于小的提供者定义来说，这可能可以忽略不计，但当定义了许多探针时，用户可能会注意到编译时间明显增加。
可序列化类型
如上所述，定义提供者的三种形式几乎是等效的。唯一的区别在于支持实现 serde::Serialize 的类型。这使用了 DTrace 的 JSON 功能 -- 任何可序列化的类型都会通过 serde_json::to_string() 序列化为 JSON，并且可以使用 json 函数在 DTrace 脚本中解包和检查字符串。例如，假设我们有一个类型
#[derive(serde::Serialize)]
pub struct Arg {
val: u8,
data: Vec<String>,
}
以及一个探针定义
#[usdt::provider]
mod my_provider {
use crate::Arg;
fn my_probe(_: &Arg) {}
}
类型为 Arg 的值可用于生成的探针宏。在一个 DTrace 脚本中，可以查看参数中的数据，如下所示
dtrace -n 'my_probe* { printf("%s", json(copyinstr(arg0), "ok.val")); }' # prints `Arg::val`.
json 函数还支持嵌套对象和数组索引，因此也可以做
dtrace -n 'my_probe* { printf("%s", json(copyinstr(arg0), "ok.data[0]")); }' # prints `Arg::data[0]`.
有关详细信息和使用方法，请参阅 probe-test-attr 示例。
序列化可能会失败
请注意，在上面的示例中，正在访问的 JSON 块的第一个键是 "ok"。这是因为 serde_json::to_string 函数可能会失败，返回一个 Result。它以自然的方式映射到 JSON 中
Ok(_) => {"ok": _}Err(_) => {"err": _}
在错误情况下，返回的 Error 是通过其 Display 实现来格式化的。这不是一个学术问题。很容易构建那些在编译时成功，但在运行时无法序列化的类型，即使是在那些 #[derive(Serialize)] 的类型中。有关详细信息，请参阅 此问题。
关于注册的说明
请注意，上面的示例中在 main 的顶部调用了 usdt::register_probes() 函数。这种方法是实际将探针注册到 DTrace 内核模块所必需的。这对于希望对其代码进行度量的库开发人员来说提出了一个难题，因为库的消费者可能会忘记（或选择不）调用此函数。这个问题有潜在的工作方案（init-sections，其他魔法），但每个都有显著的权衡。因此，目前的建议是
鼓励库开发人员重新导出
usdt::register_probes（或调用它的函数），并向用户说明应该调用此函数以确保探针已注册。
备注
usdt 库需要 内联汇编，这是在 Rust 1.59 版本中稳定的功能。在该版本之前，需要 nightly 工具链才能导入此功能。出于对遗留兼容性的考虑，库中包含了一个空的无操作实现，它会生成所有相同的探测宏，但体为空（因此不需要内联汇编）。可以通过在构建库时传递 --no-default-features 标志或在使用 [dependencies] 表中的 default-features = false 来选择此功能。
库开发者可以将 usdt 作为可选依赖项使用，通过特性进行控制，例如命名为 usdt-probes 或类似名称。此特性将意味着 usdt/asm 特性，但 usdt 库可以使用默认的无操作实现。例如，您的 Cargo.toml 可能包含以下内容：
[dependencies]
usdt = { version = "*", optional = true, default-features = false }
# ... later
[features]
usdt-probes = ["usdt/asm"]
这允许用户在适合的新的工具链或启用了 asm 特性的旧 nightly 工具链上选择探针。
Rust asm 特性
在 1.59 版本之前的工具链上，如果没有启用特性，则内联汇编不可用。这适用于调用探针宏的代码，以及实现探针宏的 usdt。这些生成的探针宏必须位于一个使用 >=1.59 工具链构建的模块中，或者在该模块中存在 feature(asm) 配置。
工具链版本和 asm_sym 特性
在 macOS（在 USDT 探针创建中涉及链接器）上，在 1.66 版本之前的工具链中，需要 asm_sym 特性（除了在 2021 年 11 月之前的 nightly 工具链中的 asm；见 此问题）。对于此类工具链，此功能可以仅包含在 macOS 上，例如使用 #![cfg_attr(target_os = "macos", feature(asm_sym))]，或者在所有平台上无条件使用。
asm_sym 特性的添加带来一个不幸的问题。不再可能使用在该特性添加之前和之后添加特性的工具链来编译 usdt 库（或任何定义探针的库）。在前一种情况下，如果包含 asm_sym 特性，我们会得到有关未知特性的错误，如果我们省略了特性，则后续编译器的功能门控错误会引发错误。
幸运的是，由于在 1.66 中稳定了 asm_sym，使用此库应该会变得更加简单。
参考资料
依赖项
~5.5MB
~104K SLoC