env_logger

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

用法

在库中

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

在可执行文件中

必须将其与 log 一起添加到项目依赖中

$ cargo add log env_logger

env_logger 必须尽早初始化项目。初始化后，你可以使用 log 宏来进行实际的日志记录。

use log::info;

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::Level 枚举，该枚举来自 log 包。它们是

• 错误
• 警告
• 信息
• 调试
• 跟踪

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

env_logger 除了环境变量之外，还可以以其他方式配置。有关更多方法，请参阅 示例。

在测试中

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

$ cargo add log
$ cargo add --dev env_logger

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

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

    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 的输出，则应使用自定义格式。