撰写日志(logging)是调试(debug)和事件分析时经常会使用的方式。Rust 生态圈有 log 这个 crate,针对消息重要性(等级)提供了不同的宏让函数库或是应用程序输出日志(log),不过它并没有限定日志最终会被输出到哪,Rust 开发者在引入有用到 log 这个 crate 的函数库后,可以自行决定日志的输出方式。

log 将消息依重要性依序分为 trace、debug、info、warn、error 五个等级,trace 是最不重要的,error 则是最重要的。这五种等级有各自对应的类函数(function-like)宏(以下称这些宏为日志宏),用法如下:

#[macro_use]
extern crate log;

pub fn add(a: i32, b: i32) -> i32 {
    info!("{a} + {b}");

    a + b
}

日志宏的撰写格式和 println! 类似,可以参考这篇文章来了解格式化文字的方式。除此之外,日志宏还多了标签的功能,可以对日志消息做「分类」的动作,用法如下:

#[macro_use]
extern crate log;

pub fn add(a: i32, b: i32) -> i32 {
    trace!(target: "call_function", "add");
    info!("{a} + {b}");

    a + b
}

如果未在日志宏的第一个参数使用 target: 来定义标签名称,则会将标签名称预设为调用这个宏的模块的路径。例如上面的程序其实等同于:

#[macro_use]
extern crate log;

pub fn add(a: i32, b: i32) -> i32 {
    trace!(target: "call_function", "add");
    info!(target: core::module_path!(), "{} + {}", a, b);

    a + b
}

至此 log 这个 crate 的用法就介绍完了,超简单。但是如果我们在 src/main.rs 中调用上面这个 add 函数的话,会发现程序并不会输出任何日志消息。

因为我们还需要引用其它的 logger 实作,才能真正的让这些日志宏发挥其该有的功能。以下会介绍一些常用的 logger 实作。

env_logger

env_logger 是一个轻巧的 logger,顾名思义,它可以透过环境变量在程序运行阶段进行组态设置。

基本用法如下:

fn main() {
    env_logger::init();

    ...
}

预设的情况下,env_logger 会将日志消息输出到标准错误(stderr),若想改成输出到标准输出(stdout),可以将程序改写如下:

fn main() {
    env_logger::builder().target(env_logger::Target::Stdout).init();

    ...
}

控制 env_logger 行为的环境变量为 RUST_LOG,其值的写法和用途如下:

  • info:输出等级至少为 info 的日志消息。
  • hello:输出 hello 这个模块的所有日志消息。
  • hello=info:输出 hello 这个模块中等级至少为 info 的日志消息。
  • error,hello=info:输出等级至少为 error 的日志消息,但是在 hello 这个模块中会输出等级至少为 info 的日志消息。
  • error,hello=info/regex:输出等级至少为 error 的日志消息,但是在 hello 这个模块中会输出等级至少为 info 的日志消息,而且所有消息都要符合 regex 代表的正则表达式。

RUST_LOG_STYLE 环境变量可以控制 env_logger 输出的消息要不要带有颜色或是粗斜体等风格,设成 never 可以禁用文字风格。

若想要自订日志消息的格式可以将程序改写如下:

use std::io::Write;

fn main() {
    env_logger::builder()
        .format(|buf, record| writeln!(buf, "{}({}): {}", record.level(), record.target(), record.args()))
        .init();

    ...
}

如果要在 Rust 测试中抓取日志消息(为了让这些消息只有在测试失败的时候才会被输出),在初始化 env_logger 时可以使用如下的程序叙述:

env_logger::builder().is_test(true).init();

env_logger 在没有设置 RUST_LOG 环境变量时只会输出 error 等级的日志消息,如果想要预设 RUST_LOG 环境变量的值,程序可以这样写:

use std::env;

fn main() {
    if env::var("RUST_LOG").is_err() {
        env::set_var("RUST_LOG", "debug");
    }

    env_logger::init();

    ...
}

pretty_env_logger

pretty_env_logger 是 env_logger 的视觉加强版,用法与 env_logger 基本上是一样的。不过 pretty_env_logger 并没有提供 builder 函数,而是改用 formatted_builder 和 formatted_timed_builder 函数,这两个函数内部会去调用 env_logger::Builder 的 format 方法来设置文字格式。

基本用法如下:

fn main() {
    pretty_env_logger::init();

    ...
}

simplelog

simplelog 提供了三种轻巧的 logger,分别是什么风格都不加、单纯将消息写入标准输出或是标准错误的 SimpleLogger、有加风格的 TermLogger、能将日志写入某个 Writer(例如文件)的 WriteLogger。另外它还提供了 CombinedLogger,让我们可以同时使用多个以上提到的 logger。

SimpleLogger 的基本用法如下:

fn main() {
    simplelog::SimpleLogger::init(simplelog::LevelFilter::Info, simplelog::Config::default()).unwrap();

    ...
}

LevelFilter 枚举可以设置能输出的日志消息之最小等级。对于 error 等级的日志消息,SimpleLogger 会将其写进标准错误,其余等级的日志消息会写入标准输出。

TermLogger 的基本用法如下:

fn main() {
    simplelog::TermLogger::init(simplelog::LevelFilter::Info, simplelog::Config::default(), simplelog::TerminalMode::Stderr).unwrap();

    ...
}

TerminalMode 枚举可以设置 TermLogger 要将日志消息输出到标准输出或标准错误。或者可以使用其 Mixed 变体,将 error 等级的日志消息写进标准错误,其余等级的日志消息会写入标准输出。

WriteLogger 的基本用法如下:

use std::fs::File;

fn main() {
    simplelog::WriteLogger::init(simplelog::LevelFilter::Info, simplelog::Config::default(), File::create("app.log").unwrap()).unwrap();

    ...
}

以上用法,会将日志消息写进目前工作目录的 app.log 文件中。

CombinedLogger 的基本用法如下:

use std::fs::File;

fn main() {
    simplelog::CombinedLogger::init(vec![
        simplelog::SimpleLogger::new(simplelog::LevelFilter::Info, simplelog::Config::default()),
        simplelog::WriteLogger::new(simplelog::LevelFilter::Info, simplelog::Config::default(), File::create("app.log").unwrap()),
    ])
    .unwrap();

    ...
}

以上用法,会将日志消息写进目前工作目录的 app.log 文件,以及标准输出和标准错误中。

若要修改日志消息的格式,就不能直接使用 simplelog::Config 结构体,而是要透过 simplelog::ConfigBuilder 结构体来产生 simplelog::Config 结构实体。如下:

fn main() {
    simplelog::SimpleLogger::init(
        simplelog::LevelFilter::Info,
        simplelog::ConfigBuilder::new().set_time_format_str("%+").set_time_to_local(true).build(),
    )
    .unwrap();

    ...
}

simplelog 不能完全自订消息的格式,只能按照 ConfigBuilder 结构实体提供的现有方法来设置。

syslog

syslog 是 Unix-like 的操作系统用来统一管理系统日志所用的协议或者说服务。syslog 这个 crate 可以让 log 的日志消息输出给 syslog 进行管理。

基本用法如下:

fn main() {
    let formatter = syslog::Formatter3164 {
        facility: syslog::Facility::LOG_USER,
        hostname: None,
        process: String::from("myprogram"),
        pid: unsafe { libc::getpid() },
    };

    let logger = syslog::unix(formatter).expect("could not connect to syslog");

    log::set_boxed_logger(Box::new(syslog::BasicLogger::new(logger))).map(|_| log::set_max_level(log::LevelFilter::Info)).expect("could not register logger");

    ...
}

console_log

console_log 可以在 WebAssembly 程序中将日志消息输出到主控台(console)。

基本用法如下:

fn main() {
    console_log::init_with_level(log::Level::Info).unwrap();

    ...
}