撰写日志(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();
...
}
