usdt

用USDT探测给你的Rust项目除灰。

概述

usdt 将静态定义的 DTrace探测 暴露给Rust代码。用户编写一个 provider 定义，可以是D语言或直接在Rust代码中。然后可以将provider的探测编译成触发探测的Rust代码。这些通过 dtrace 命令行工具可见。

将D探测定义转换为Rust有三种机制。

1. 一个 build.rs 脚本
2. 一个类似函数的过程宏，usdt::dtrace_provider。
3. 一个属性宏，usdt::provider。

生成的代码在所有情况下都是相同的，尽管第三种提供比前两种更多的灵活性。有关详细信息，请参见下面，但简要来说，第三种形式支持任何实现了 serde::Seralize 的类型的探测参数。这些不同版本分别在crate probe-test-{build,macro,attr} 中展示。

注意：此软件包使用内联汇编来实现其魔法。有关在 Rust 1.59 之前和 macOS 上 1.66 之前使用方法的讨论，请参阅注释。

示例

本软件包中的 probe-test-build 二进制软件包实现了一个完整的示例，使用构建时代码生成。

起点是一个名为 "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) 工具列出、启用或以其他方式查看探测点。

$ 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_provider!("test.d");

#[derive(serde::Serialize)]
pub struct Arg {
    val: u8,
    data: Vec<String>,
}

#[usdt::provider]
mod my_provider {
    use crate::Arg;
    fn my_probe(_: &Arg) {}
}

dtrace -n 'my_probe* { printf("%s", json(copyinstr(arg0), "ok.val")); }' # prints `Arg::val`.

dtrace -n 'my_probe* { printf("%s", json(copyinstr(arg0), "ok.data[0]")); }' # prints `Arg::data[0]`.

[dependencies]
usdt = { version = "*", optional = true, default-features = false }

# ... later

[features]
usdt-probes = ["usdt/asm"]