Rust USDT插件库的使用：轻量级用户空间数据跟踪与性能分析工具

概述

usdt库为Rust代码提供了静态定义的DTrace探针功能。用户可以使用D语言或直接在Rust代码中编写provider定义，然后将其编译为可以触发探针的Rust代码。这些探针可以通过dtrace命令行工具查看。

有三种方式将D探针定义转换为Rust代码：

1. 使用build.rs构建脚本
2. 使用函数式过程宏usdt::dtrace_provider
3. 使用属性宏usdt::provider

示例

以下是使用构建脚本生成探针的完整示例：

1. 创建D脚本文件(test.d)

provider my_provider {
    probe start_work(uint8_t);
    probe stop_work(char*, uint8_t);
};

2. 创建build.rs构建脚本

use usdt::Builder;

fn main() {
    Builder::new("test.d").build().unwrap();
}

3. 主程序代码

//! 使用`usdt` crate的示例，通过构建脚本生成探针

use std::thread::sleep;
use std::time::Duration;

use usdt::register_probes;

// 包含由构建脚本生成的Rust实现
include!(concat!(env!("OUT_DIR"), "/test.rs"));

fn main() {
    let duration = Duration::from_secs(1);
    let mut counter: u8 = 0;

    // 注意：必须调用此函数才能向DTrace注册探针
    register_probes().unwrap();

    loop {
        // 调用接受u8参数的"start_work"探针
        my_provider::start_work!(|| (counter));

        // 做一些工作
        sleep(duration);

        // 调用接受&str和u8参数的"stop_work"探针
        my_provider::stop_work!(|| ("the probe has fired", counter));

        counter = counter.wrapping_add(1);
    }
}

4. 查看探针

运行程序后，在另一个终端使用以下命令查看探针：

$ sudo dtrace -l -n my_provider*:::

过程宏版本示例

不使用构建脚本，而使用过程宏的版本：

// 使用过程宏定义探针
dtrace_provider!("test.d");

fn main() {
    // ...相同的使用代码...
}

可序列化类型支持

属性宏版本支持任何实现serde::Serialize的类型：

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

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

// 使用示例
my_provider::my_probe!(|| (Arg { val: 42, data: vec!["hello".to_string()] }));

在DTrace脚本中可以这样查看数据：

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

注意事项

1. 必须调用usdt::register_probes()来注册探针
2. 需要Rust 1.59+支持(1.66+在macOS上)
3. 对于库开发者，建议重新导出usdt::register_probes并告知用户调用

完整示例代码

以下是使用属性宏的完整示例：

// 定义可序列化的数据结构
#[derive(serde::Serialize)]
struct WorkInfo {
    id: u64,
    name: String,
    duration_ms: u32,
}

// 使用属性宏定义探针提供者
#[usdt::provider]
mod work_provider {
    use crate::WorkInfo;
    
    /// 开始工作探针
    fn work_start(info: &WorkInfo) {}
    
    /// 完成工作探针
    fn work_done(info: &WorkInfo, result: u32) {}
}

fn perform_work(id: u64, name: &str) -> u32 {
    let start = std::time::Instant::now();
    let info = WorkInfo {
        id,
        name: name.to_string(),
        duration_ms: 0,
    };
    
    // 触发开始工作探针
    work_provider::work_start!(|| (&info));
    
    // 模拟工作
    std::thread::sleep(std::time::Duration::from_millis(100));
    let result = (id % 10) as u32;
    
    // 更新持续时间
    let duration = start.elapsed();
    let info = WorkInfo {
        duration_ms: duration.as_millis() as u32,
        ..info
    };
    
    // 触发完成工作探针
    work_provider::work_done!(|| (&info, result));
    
    result
}

fn main() {
    // 注册探针
    usdt::register_probes().unwrap();
    
    // 执行一些工作
    for i in 0..5 {
        let result = perform_work(i, &format!("task-{}", i));
        println!("Work {} completed with result {}", i, result);
    }
}

这个示例展示了：

1. 定义可序列化的工作信息结构
2. 使用属性宏定义探针提供者
3. 在工作开始和结束时触发探针
4. 包含时间测量等实际性能分析场景中的常见模式

可以通过DTrace命令查看这些探针并分析性能数据。