Rust结构化日志库structured-logger使用指南

介绍

structured-logger是一个Rust的结构化日志记录库，它提供了高效、灵活的日志记录功能，特别适合需要结构化日志输出的应用程序。与传统的文本日志不同，结构化日志以键值对的形式记录数据，便于后续的日志分析和处理。

主要特性

• 支持结构化日志记录
• 高性能日志记录
• 可定制的日志格式
• 支持异步日志记录
• 多种日志级别控制
• 易于与现有日志系统集成

安装

在Cargo.toml中添加依赖：

[dependencies]
structured-logger = "0.4"
log = "0.4"

基本使用方法

1. 初始化日志记录器

use structured_logger::{async_json::new_writer, Builder};
use log::LevelFilter;

fn init_logger() {
    // 使用Builder创建日志记录器，设置日志级别为Info
    // 将所有目标的日志输出到标准输出(stdout)
    Builder::with_level(LevelFilter::Info)
        .with_target_writer("*", new_writer(std::io::stdout()))
        .init();
}

2. 记录日志

use log::{info, warn, error};

fn main() {
    // 初始化日志记录器
    init_logger();
    
    // 记录结构化日志
    info!(target: "my_app",
        event = "startup",  // 自定义字段
        version = env!("CARGO_PKG_VERSION"),  // 获取Cargo版本号
        "Application starting");  // 日志消息
    
    // 记录警告日志
    warn!(
        user_id = 12345,
        action = "login",
        "User attempted login with expired token"
    );
    
    // 记录错误日志
    error!(
        error = "Database connection failed",
        retry_count = 3,
        "Critical operation failed"
    );
}

3. 输出示例

上述代码会产生类似如下的结构化日志：

{
  "timestamp": "2023-05-15T12:34:56.789Z",
  "level": "INFO",
  "target": "my_app",
  "message": "Application starting",
  "event": "startup",
  "version": "1.0.0"
}

{
  "timestamp": "2023-05-15T12:34:56.790Z",
  "level": "WARN",
  "message": "User attempted login with expired token",
  "user_id": 12345,
  "action": "login"
}

高级用法

自定义日志格式

use structured_logger::{Builder, unix_ms};

fn init_custom_logger() {
    // 创建自定义格式的日志记录器
    Builder::with_level("info")
        .with_default_writer(|_| {
            Box::new(|record| {
                // 自定义日志格式：[时间戳][日志级别][目标] 键值对 - 消息
                println!(
                    "[{}][{}][{}] {} - {}",
                    unix_ms(),  // 获取当前UNIX时间戳(毫秒)
                    record.level(),  // 日志级别
                    record.target(),  // 日志目标
                    record.key_values(),  // 键值对
                    record.args()  // 日志消息
                );
            })
        })
        .init();
}

异步日志记录

use structured_logger::{async_json::new_writer, Builder};
use log::LevelFilter;

#[tokio::main]
async fn main() {
    // 使用异步日志记录器，输出到标准输出
    Builder::with_level(LevelFilter::Info)
        .with_target_writer("*", new_writer(tokio::io::stdout()))
        .init();
    
    // 异步记录日志
    log::info!("This log will be written asynchronously");
}

文件日志记录

use structured_logger::{async_json::new_writer, Builder};
use log::LevelFilter;
use std::fs::File;

fn init_file_logger() {
    // 创建日志文件
    let file = File::create("app.log").expect("Failed to create log file");
    
    // 初始化文件日志记录器
    Builder::with_level(LevelFilter::Info)
        .with_target_writer("*", new_writer(file))
        .init();
}

性能建议

1. 对于高性能应用，使用异步日志记录
2. 避免在日志宏中执行复杂计算
3. 在生产环境中适当调整日志级别
4. 考虑使用缓冲写入器减少I/O操作

与其他日志系统的集成

structured-logger可以与log生态系统中的其他工具一起使用：

use env_logger;
use structured_logger;

fn init_combined_logger() {
    // 初始化env_logger用于开发环境
    env_logger::init();
    
    // 初始化structured_logger用于生产环境
    structured_logger::Builder::with_level("info")
        .with_default_writer(structured_logger::json::new_writer(std::io::stdout()))
        .init_quiet();
}

完整示例Demo

下面是一个完整的应用程序示例，展示了如何使用structured-logger记录不同类型的日志：

use structured_logger::{async_json::new_writer, Builder};
use log::{info, warn, error, debug};
use std::time::Duration;
use std::thread;

fn init_logger() {
    // 初始化日志记录器，设置日志级别为Debug
    Builder::with_level(log::LevelFilter::Debug)
        .with_target_writer("*", new_writer(std::io::stdout()))
        .init();
}

fn perform_operation(user_id: u64) -> Result<(), String> {
    // 模拟一些业务逻辑
    if user_id % 2 == 0 {
        Ok(())
    } else {
        Err("Operation failed for odd user ID".to_string())
    }
}

fn main() {
    // 初始化日志系统
    init_logger();
    
    info!(
        target: "app_startup",
        version = env!("CARGO_PKG_VERSION"),
        "Starting application"
    );
    
    // 模拟用户操作
    for user_id in 1..=5 {
        debug!(
            user_id = user_id,
            "Processing user request"
        );
        
        thread::sleep(Duration::from_millis(100));
        
        match perform_operation(user_id) {
            Ok(_) => info!(
                user_id = user_id,
                status = "success",
                "Operation completed"
            ),
            Err(e) => error!(
                user_id = user_id,
                status = "failed",
                error = e,
                "Operation failed"
            ),
        }
    }
    
    warn!(
        notice = "shutdown",
        "Application shutting down"
    );
}

输出示例：

{
  "timestamp": "2023-05-15T12:34:56.789Z",
  "level": "INFO",
  "target": "app_startup",
  "message": "Starting application",
  "version": "1.0.0"
}
{
  "timestamp": "2023-05-15T12:34:56.790Z",
  "level": "DEBUG",
  "message": "Processing user request",
  "user_id": 1
}
{
  "timestamp": "2023-05-15T12:34:56.890Z",
  "level": "ERROR",
  "message": "Operation failed",
  "user_id": 1,
  "status": "failed",
  "error": "Operation failed for odd user ID"
}
{
  "timestamp": "2023-05-15T12:34:56.890Z",
  "level": "DEBUG",
  "message": "Processing user request",
  "user_id": 2
}
{
  "timestamp": "2023-05-15T12:34:56.990Z",
  "level": "INFO",
  "message": "Operation completed",
  "user_id": 2,
  "status": "success"
}
{
  "timestamp": "2023-05-15T12:34:57.090Z",
  "level": "WARN",
  "message": "Application shutting down",
  "notice": "shutdown"
}

structured-logger是一个强大而灵活的工具，特别适合需要结构化日志的现代应用程序。通过键值对的形式记录日志数据，可以大大简化日志分析和监控的复杂度。