iroh-metrics

iroh-metrics 是用于 iroh 项目的指标收集库。它提供了必要的"粘合剂"来暴露定义的指标以供收集：一个 HTTP 服务器，可以暴露被跟踪的指标，供 Prometheus 等服务进行轮询记录。

iroh 中的几乎所有指标都记录为简单的计数器。

许可证

本项目采用以下任一许可证：

• Apache License, Version 2.0
• MIT license

贡献

除非您明确声明，否则任何有意提交包含在本项目中的贡献，如 Apache-2.0 许可证中所定义的，都将按照上述双重许可，不附加任何额外条款或条件。

安装

在项目目录中运行以下 Cargo 命令：

cargo add iroh-metrics

或在 Cargo.toml 中添加以下行：

iroh-metrics = "0.35.0"

完整示例代码

以下是内容中提供的示例代码：

use iroh_metrics::inc;
use iroh_metrics::core::{Core, Metric};
use std::net::SocketAddr;

// 定义你的指标类型
#[derive(Metric)]
struct MyMetrics {
    // 计数器指标
    requests: Counter,
    // 带有标签的计数器
    errors: CounterVec<&'static str>,
}

// 初始化指标
let metrics = MyMetrics {
    requests: Counter::new("requests_total", "Total number of requests").unwrap(),
    errors: CounterVec::new("errors_total", "Total number of errors", &["type"]).unwrap(),
};

// 注册指标
Core::register(metrics);

// 模拟一些指标更新
inc!(metrics.requests);
inc!(metrics.errors.with_label("timeout"));

// 启动HTTP服务器暴露指标
let addr: SocketAddr = "0.0.0.0:9090".parse().unwrap();
iroh_metrics::serve(addr).expect("Failed to start metrics server");

println!("Metrics server running at http://{}", addr);

这个示例展示了：

1. 如何定义自定义指标类型
2. 如何初始化计数器指标
3. 如何注册指标
4. 如何更新指标值
5. 如何启动 HTTP 服务器来暴露指标

扩展完整示例

以下是一个更完整的示例，展示如何在实际应用中使用 iroh-metrics：

use iroh_metrics::{
    inc, dec,
    core::{Core, Metric},
    latency::Histogram
};
use std::net::SocketAddr;
use std::time::Instant;

// 定义应用指标
#[derive(Metric)]
struct AppMetrics {
    // 请求计数器
    http_requests: Counter,
    // 错误计数器（带类型标签）
    http_errors: CounterVec<&'static str>,
    // 请求处理时间直方图（单位：毫秒）
    request_duration: Histogram,
    // 当前活跃连接数
    active_connections: Gauge,
}

impl AppMetrics {
    fn new() -> Self {
        AppMetrics {
            http_requests: Counter::new("http_requests_total", "Total HTTP requests").unwrap(),
            http_errors: CounterVec::new(
                "http_errors_total", 
                "Total HTTP errors by type",
                &["status_code"]
            ).unwrap(),
            request_duration: Histogram::new(
                "http_request_duration_ms",
                "HTTP request duration in milliseconds",
                vec![50.0, 100.0, 200.0, 500.0, 1000.0]
            ).unwrap(),
            active_connections: Gauge::new(
                "active_connections",
                "Current number of active connections"
            ).unwrap(),
        }
    }
}

fn main() {
    // 初始化指标
    let metrics = AppMetrics::new();
    Core::register(metrics);
    
    // 启动指标服务器
    let addr: SocketAddr = "127.0.0.1:9090".parse().unwrap();
    iroh_metrics::serve(addr).expect("Failed to start metrics server");
    
    // 模拟应用行为
    simulate_application(&metrics);
}

fn simulate_application(metrics: &AppMetrics) {
    // 新连接建立
    inc!(metrics.active_connections);
    
    // 处理请求
    let start = Instant::now();
    inc!(metrics.http_requests);
    
    // 模拟请求处理
    std::thread::sleep(std::time::Duration::from_millis(120));
    
    // 记录请求持续时间
    let duration = start.elapsed().as_millis() as f64;
    metrics.request_duration.observe(duration);
    
    // 模拟偶尔出现的错误
    if rand::random::<f32>() > 0.8 {
        inc!(metrics.http_errors.with_label("500"));
    }
    
    // 连接关闭
    dec!(metrics.active_connections);
}

这个扩展示例展示了：

1. 更复杂的指标类型定义（包括计数器、直方图和量表）
2. 如何封装指标初始化逻辑
3. 如何在真实场景中记录请求持续时间和错误
4. 如何使用带标签的指标
5. 如何增加和减少量表值