env_logger

实现了一个可以通过环境变量配置的记录器。

用法

在库中

env_logger 在可执行文件（二进制项目）中使用时很有意义。库应使用 log 包。

在可执行文件中

它必须与 log 一起添加到项目的依赖关系中

$ cargo add log env_logger

env_logger 必须尽早初始化到项目中。初始化后，可以使用 log 宏进行实际记录。

#[macro_use]
extern crate log;

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

    info!("starting up");

    // ...
}

然后在运行可执行文件时，指定一个与您想要显示的日志消息相对应的 RUST_LOG 环境变量值。

$ RUST_LOG=info ./main
[2018-11-03T06:09:06Z INFO  default] starting up

日志级别名称的大小写不区分；例如，debug、DEBUG 和 dEbuG 都代表相同的日志级别。因此，前面的例子也可以这样写，将日志级别指定为 INFO 而不是 info

$ RUST_LOG=INFO ./main
[2018-11-03T06:09:06Z INFO  default] starting up

那么应该使用哪种形式？为了保持一致性，我们的约定是使用小写名称。在我们的文档中使用其他形式的情况下，它们都是在特定示例的上下文中使用的，所以如果你在野外看到类似的使用方式，请不要感到惊讶。

可能指定的日志级别对应于 log 包中的 log::Level 枚举。它们是

• error
• warn
• info
• debug
• trace

还有一个伪日志级别，off，可以指定以禁用特定模块或整个应用程序的所有日志。与日志级别一样，大小写不区分。

env_logger 可以通过其他方式配置，而不仅仅是环境变量。有关更多方法，请参阅 示例。

在测试中

测试可以使用env_logger包来查看测试期间生成的日志消息。

[dependencies]
log = "0.4.0"

[dev-dependencies]
env_logger = "0.9.0"

#[macro_use]
extern crate log;

fn add_one(num: i32) -> i32 {
    info!("add_one called with {}", num);
    num + 1
}

#[cfg(test)]
mod tests {
    use super::*;

    fn init() {
        let _ = env_logger::builder().is_test(true).try_init();
    }

    #[test]
    fn it_adds_one() {
        init();

        info!("can log from the test too");
        assert_eq!(3, add_one(2));
    }

    #[test]
    fn it_handles_negative_numbers() {
        init();

        info!("logging from another test");
        assert_eq!(-7, add_one(-8));
    }
}

假设正在测试的模块名为my_lib，使用RUST_LOG过滤器运行测试以显示来自此模块的信息消息，看起来是这样的：

$ RUST_LOG=my_lib=info cargo test
     Running target/debug/my_lib-...

running 2 tests
[INFO my_lib::tests] logging from another test
[INFO my_lib] add_one called with -8
test tests::it_handles_negative_numbers ... ok
[INFO my_lib::tests] can log from the test too
[INFO my_lib] add_one called with 2
test tests::it_adds_one ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured

请注意，env_logger::try_init()需要在每个你想启用日志的测试中调用。另外，测试默认以并行方式运行的行为意味着日志输出可能与测试输出交织。可以通过指定RUST_TEST_THREADS=1或通过指定测试二进制文件作为参数运行一个测试（按照cargo test帮助文档的指示）来在单个线程中运行测试。

$ RUST_LOG=my_lib=info cargo test it_adds_one
     Running target/debug/my_lib-...

running 1 test
[INFO my_lib::tests] can log from the test too
[INFO my_lib] add_one called with 2
test tests::it_adds_one ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

配置日志目标

默认情况下，env_logger将日志记录到stderr。如果你想将日志记录到stdout，可以使用Builder来更改日志目标。

use std::env;
use env_logger::{Builder, Target};

let mut builder = Builder::from_default_env();
builder.target(Target::Stdout);

builder.init();

默认格式的稳定性

默认格式不会优化长期稳定性，并且明确表示在0.x期间不保证其输出在主要、次要或补丁版本升级时的稳定性。

如果你想以编程方式捕获或解释env_logger的输出，则应使用自定义格式。