Rust性能测量与指标收集库measured-derive使用指南

measured-derive是一个Rust宏库，用于简化性能测量和指标收集的实现。它通过派生宏自动为你的类型添加度量功能，让你可以轻松收集和报告应用程序的性能指标。

主要特性

• 自动为结构体实现度量功能
• 支持自定义度量指标
• 高性能低开销的测量
• 灵活的指标聚合方式
• 与常见监控系统兼容

基本使用方法

1. 添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
measured-derive = "0.5"
measured = "0.5"

2. 基本示例

use measured_derive::measured;

#[measured]
fn process_data(input: &str) -> String {
    // 模拟耗时操作
    std::thread::sleep(std::time::Duration::from_millis(100));
    input.to_uppercase()
}

fn main() {
    let result = process_data("hello");
    println!("Result: {}", result);
    
    // 获取并打印度量结果
    let metrics = measured::global_collector().lock().unwrap().snapshot();
    println!("Metrics: {:?}", metrics);
}

3. 结构体度量

use measured_derive::measured;

#[measured]
struct DataProcessor {
    cache: Vec<String>,
}

impl DataProcessor {
    #[measured]
    fn process(&mut self, input: &str) -> String {
        let result = input.to_uppercase();
        self.cache.push(result.clone());
        result
    }
    
    #[measured(histogram = true)] // 使用直方图记录耗时分布
    fn batch_process(&self, inputs: &[&str]) -> Vec<String> {
        inputs.iter().map(|&s| s.to_uppercase()).collect()
    }
}

fn main() {
    let mut processor = DataProcessor { cache: Vec::new() };
    let result = processor.process("test");
    println!("Processed: {}", result);
    
    let batch = processor.batch_process(&["a", "b", "c"]);
    println!("Batch: {:?}", batch);
    
    // 获取度量数据
    let metrics = measured::global_collector().lock().unwrap().snapshot();
    println!("{:#?}", metrics);
}

高级用法

自定义指标名称

#[measured(metric = "custom.metric.name")]
fn my_function() {
    // ...
}

多维度度量

#[measured(tags = ["env:production", "region:us-west"])]
fn api_handler() {
    // ...
}

错误计数

#[measured]
fn fallible_operation() -> Result<(), String> {
    // 自动记录错误计数
    if rand::random() {
        Err("Something went wrong".into())
    } else {
        Ok(())
    }
}

指标导出

measured库支持将收集的指标导出到各种监控系统：

use measured::TextEncoder;

fn export_metrics() {
    let collector = measured::global_collector();
    let metrics = collector.lock().unwrap().snapshot();
    
    // 导出为Prometheus格式
    let mut buffer = Vec::new();
    let encoder = TextEncoder::new();
    encoder.encode(&metrics, &mut buffer).unwrap();
    
    println!("Prometheus Metrics:\n{}", String::from_utf8(buffer).unwrap());
}

配置选项

你可以在全局或单个测量点配置各种参数：

use measured::{Collector, MetricParams};

fn configure_collector() {
    let collector = Collector::new();
    collector.configure_metric(
        "my_metric",
        MetricParams::new()
            .with_histogram_enabled(true)
            .with_histogram_buckets(vec![0.1, 0.5, 1.0, 2.5, 5.0]),
    );
    
    measured::set_global_collector(collector);
}

性能考虑

measured-derive设计时考虑了性能：

• 使用原子操作进行计数
• 采样而不是全量记录
• 延迟初始化昂贵的资源
• 允许禁用特定环境下的度量

实际应用场景

1. Web服务端点监控
2. 批处理任务性能分析
3. 算法性能比较
4. 系统资源使用跟踪
5. 业务指标收集

完整示例demo

下面是一个结合多种特性的完整示例：

use measured_derive::measured;
use measured::{Collector, MetricParams, TextEncoder};
use std::thread;
use std::time::Duration;

// 配置全局收集器
fn setup_collector() {
    let collector = Collector::new();
    collector.configure_metric(
        "api_processing_time",
        MetricParams::new()
            .with_histogram_enabled(true)
            .with_histogram_buckets(vec![0.1, 0.5, 1.0, 2.5, 5.0]),
    );
    measured::set_global_collector(collector);
}

// 带有自定义指标名称和标签的API处理器
#[measured(metric = "api_processing_time", tags = ["api:v1", "method:data"])]
fn api_data_processor(input: &str) -> Result<String, String> {
    // 模拟处理时间
    let delay_ms = match input.len() {
        0..=5 => 100,
        6..=10 => 300,
        _ => 800,
    };
    thread::sleep(Duration::from_millis(delay_ms));
    
    // 随机模拟错误
    if rand::random::<f32>() < 0.2 {
        Err("Processing failed".into())
    } else {
        Ok(input.to_uppercase())
    }
}

// 度量结构体
#[measured]
struct DataService {
    requests_processed: usize,
}

impl DataService {
    #[measured]
    fn handle_request(&mut self, input: &str) -> Result<String, String> {
        self.requests_processed += 1;
        api_data_processor(input)
    }
}

fn main() {
    // 初始化收集器
    setup_collector();
    
    // 创建服务实例
    let mut service = DataService { requests_processed: 0 };
    
    // 模拟请求处理
    let inputs = ["hello", "world", "rust", "performance", "measurement"];
    for input in inputs.iter() {
        match service.handle_request(input) {
            Ok(result) => println!("Processed: {}", result),
            Err(e) => println!("Error: {}", e),
        }
    }
    
    // 导出指标
    let collector = measured::global_collector();
    let metrics = collector.lock().unwrap().snapshot();
    
    let mut buffer = Vec::new();
    let encoder = TextEncoder::new();
    encoder.encode(&metrics, &mut buffer).unwrap();
    
    println!("\n=== Metrics ===\n{}", String::from_utf8(buffer).unwrap());
}

这个完整示例展示了：

1. 全局收集器配置
2. 自定义指标名称和标签
3. 自动错误计数
4. 结构体和方法级别的度量
5. 指标导出功能
6. 直方图分布记录

运行此程序将输出处理结果以及收集的指标数据，包括调用次数、耗时分布和错误计数等信息。