sensible-env-logger

为Rust提供的漂亮、可感知的记录器 - 适用于在所选代码包上运行 示例 和 测试。

这是一个围绕 pretty_env_logger 的薄包装。它需要最少的配置来设置，并以漂亮的彩色输出写入标准错误，以显示日志级别。

此代码包与Cargo配合使用，其 Cargo.toml 看起来如下

[dependencies]
log = "0.4"
sensible-env-logger = "0.3"

入门指南

在编写Cargo项目或代码包的 示例 或 测试 时，最好使用 sensible-env-logger。如果需要，它可以作为 dev-dependency 添加。

首先，将一些用法添加到您的应用程序中

#[macro_use] extern crate log;

fn main() {
    sensible_env_logger::init!();

    info!("such information");
    warn!("o_O");
    error!("much error");
}

然后使用 cargo 运行您的应用程序，您应该看到完整的日志输出

cargo run

或者，使用控制日志级别的环境变量运行您的应用程序，以及显式设置 外部 代码包和 您的 代码包

GLOBAL_RUST_LOG=warn RUST_LOG=trace cargo run

尽管此代码包的名称中包含 env，但在代码中使用 sensible-env-logger 简单至极，且需要最少的配置。

示例

您可以在GitHub项目仓库的 examples/ 文件夹中查看此代码包的示例用法。

默认值

以下辅助宏可用于使用 可感知 默认值配置全局记录器。它们的示例日志输出也显示出来。

注意：任何辅助宏（如 init!()）应尽早在Rust程序执行过程中调用。

init!()

使用漂亮的、可感知的环境记录器初始化全局记录器。

INFO  my_module         > an informational message

初始化时间！()

使用一个带有时间的、合理的环境日志记录器初始化全局日志记录器。

2022-03-24T17:15:31.683Z INFO  my_module         > an informational message

init_timed_short!() - *

使用本地时间的、合理的环境日志记录器初始化全局日志记录器。

12:15:31.683 INFO  my_module         > an informational message

init_timed_local!() - *

使用“无装饰”的本地日期/时间、合理的环境日志记录器初始化全局日志记录器。

2022-03-24 12:15:31.683 - INFO  my_module         > an informational message

init_timed_local_iso!() - *

使用本地时间标记的、合理的环境日志记录器初始化全局日志记录器。

此变体使用ISO-8601/RFC 3339日期和时间格式格式化日志消息。

2022-03-24T12:15:31.683+08:00 INFO  my_module         > an informational message

可选功能

本地时间

使用上面标记的*宏，需要启用local-time功能。

[dev-dependencies]
sensible-env-logger = { version = "0.3", features = ["local-time"] }

在测试中

当在一个crate上运行测试时，可以使用下面的safe_init!()宏。这样可以在初始化全局日志记录器多次时忽略错误。

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

    #[test]
    fn test_one() {
        sensible_env_logger::safe_init!();
        trace!("hello from the first test")
    }

    #[test]
    fn test_two() {
        sensible_env_logger::safe_init!();
        trace!("hello from the second test")
    }
}

理由

想象你正在测试一个名为my_rust_project的Cargo项目。也就是说，你的项目中的Cargo.toml可能看起来像这样

[package]
name = "my-rust-project"

[dependencies]
log = "*"

假设你正在构建一个库，你的src/lib.rs可能看起来像这样

#[macro_use] extern crate log;

pub fn my_awesome_fn() {
    trace!("getting ready to do something cool...");
    std::thread::sleep(std::time::Duration::from_millis(500));
    info!("finished!");
}

然后你创建一个名为examples/my_example.rs的新示例文件，内容如下

use my_rust_project::my_awesome_fn;
#[macro_use] extern crate log;

fn main() {
    debug!("my debug message");
    my_awesome_fn();
    error!("oops! something went wrong!");
}

你可以使用以下命令运行新文件：cargo run --example my_example。这里的问题是默认情况下你不会得到任何终端输出；这是因为你需要事先设置RUST_LOG环境变量，才能看到预期的日志输出。

设置RUST_LOG变量是有效的，但这里有几个问题。例如，如果你的Cargo项目使用了其他外部库怎么办？理想情况下，你希望看到你自己的项目（测试下的crate）的trace日志，但不想看到这些其他库的trace日志。在这种情况下，设置RUST_LOG=trace似乎不是最佳方法。

然后你可以将RUST_LOG环境变量设置为以下日志格式

$ export RUST_LOG='warning,my_rust_project=trace,my_example=trace'

当利用pretty_env_logger crate并在main函数顶部添加pretty_env_logger::init()时，现在它按预期工作，并产生所需的日志输出。

然而，这种方法有几个局限性

• 在你的Cargo项目中，你需要更新运行示例的文档，提到需要显式导出RUST_LOG环境变量。例如，你需要说明示例理想情况下应该这样运行：RUST_LOG=trace cargo run --example my_example。

• 每次您都需要记住设置环境变量RUST_LOG。例如，当您的Windows机器重启或每次打开新的终端窗口时，这可能会很麻烦。

为了解决这些小问题，您可以简单地使用sensible_env_logger库，该库自动设置合理的默认值；这涉及到生成并使用与$RUST_LOG环境变量相同形式的指令字符串。

现在，更新后的代码在examples/my_example.rs中看起来是这样的

use my_rust_project::my_awesome_fn;
#[macro_use] extern crate log;

fn main() {
    sensible_env_logger::init!();

    debug!("my debug message");
    my_awesome_fn();
    error!("oops! something went wrong!");
}

贡献

欢迎贡献！打开一个拉取请求来修复一个错误，或者打开一个问题来讨论新的功能或更改。

有关更多信息，请查看文档中的贡献部分。

许可协议

本项目自豪地采用MIT许可协议（LICENSE或http://opensource.org/licenses/MIT）。

sensible-env-logger可以根据MIT许可协议进行分发。贡献将在同一许可下接受。

作者

• Ritvik Nag