#json-log #json #logging #log

json_env_logger

Rust的结构化JSON日志记录器

2个版本

0.1.1 2020年7月6日
0.1.0 2020年7月6日

#190调试

Download history 3494/week @ 2024-03-14 2852/week @ 2024-03-21 2932/week @ 2024-03-28 2070/week @ 2024-04-04 3915/week @ 2024-04-11 2546/week @ 2024-04-18 3682/week @ 2024-04-25 2176/week @ 2024-05-02 2448/week @ 2024-05-09 3629/week @ 2024-05-16 3516/week @ 2024-05-23 2094/week @ 2024-05-30 3392/week @ 2024-06-06 2665/week @ 2024-06-13 2610/week @ 2024-06-20 1033/week @ 2024-06-27

10,205 每月下载量
用于 8 crates

MIT 许可证

17KB
151 代码行

json env logger

Rust的简单结构化JSON日志记录器


安装

将以下内容添加到您的 Cargo.toml 文件中

[dependencies]
json_env_logger = "0.1"

用法

简要说明

当您运行

$ RUST_LOG=trace cargo -q run \
  --example default \
  --features iso-timestamps

您将获得

{"level":"TRACE","ts":"2020-07-06T03:41:57.831Z","msg":"I am a trace","task_id":567,"thread_id":"12"}
{"level":"DEBUG","ts":"2020-07-06T03:41:57.832Z","msg":"I am a debug","foo":1}
{"level":"INFO","ts":"2020-07-06T03:41:57.832Z","msg":"I am an info"}
{"level":"WARN","ts":"2020-07-06T03:41:57.832Z","msg":"I am a warning"}
{"level":"ERROR","ts":"2020-07-06T03:41:57.832Z","msg":"I am an error"}

基本用法

类似于 env_logger,在开始日志记录引擎之前调用 init

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

    log::info!("👋")
}

运行程序时使用 RUST_LOG=info your/bin

添加更多结构

log crate 正在努力为其宏中的结构化字段添加一等接口。而不是重新发明这个功能,这个crate接受它。当存在时,json_env_logger 将序列化这些键值对。遗憾的是,log crate 还没有完全公开这些宏接口。...但是 kv-log-macro 做了!

[dependencies]
json_env_logger = "0.1"
kv-log-macro = "1.0"
// the macros exported in this crate are
// log compatible and will one day be merged 
// so save your future self the toil of find and replace
use kv_log_macro as log;

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

    log::info!("👋", { size: "medium", age: 42 })
}

⭐ 目前这些结构化字段仅限于以下类型的值:u64i64f64boolcharstr

运行程序时使用 RUST_LOG=info your/bin

ISO时间戳

默认情况下,json_env_logger 使用 Unix 纪元时间作为时间戳。您可能更喜欢 ISO-8601 时间戳。您可以通过启用 iso-timestamps 功能来替换实现。

[dependencies]
json_env_logger = { version = "0.1", features = ["iso-timestamps"] }
fn main() {
    json_env_logger::init();

    log::info!("👋")
}

运行程序时使用 RUST_LOG=info your/bin

panic可见性

当panic无法避免时,您可以通过注册一个将panic序列化为JSON并在使用 error! 记录之前记录panic的panic钩子。

fn main() {
    json_env_logger::init();
    json_env_logger::panic_hook();

    panic!("whoooops!")
}

运行程序时使用 RUST_LOG=info your/bin

⭐ 您还可以通过启用 backtrace cargo功能来序列化回溯。

常见问题解答

为什么我需要结构化日志记录?

也许你不需要。...但是也许你需要!如果你在生产环境中运行应用程序,并且你的日志聚合通过发出JSON日志(例如)为你做了有用的事情,那么你可能需要。

  • 基于结构化字段的过滤器,是手工艺正则表达式查询的替代品
  • 聚合统计
  • 警报自动化
  • 异常检测
  • 基本上,当计算机的日志以机器可读的格式结构化时,它可以为您做的事情

 
json_env_logger针对哪些用例?

在Rust日志市场中,大多数人都从log开始。很快,他们发现需要可配置的日志记录,因此转向env_logger。有时他们想要env_logger但更美观的日志记录,以便在本地主机应用程序中,所以他们转向pretty_env_logger,如果你喜欢的话,还有emoji-logger

在其他情况下,你可能想在云服务中运行应用程序,这些服务奖励你以JSON格式输出日志。这就是它针对的用例,那些来自env_logger但希望利用云服务提供的免费内置JSON日志解析和发现选项的人。

 
这些中已经存在吗?

实际上有一些。就像Rust生态系统中的许多crate一样,它们都是好的。选择一个依赖关系是在权衡应用的目标和需求。

这里有slog,一个为Rust提供的完整日志记录生态系统。它的优势在于它可以高度配置。它的缺点是它高度可配置的接口可能会妨碍你只想以json格式输出结构化日志而不需要太多仪式的情况。

下面是一个直接来自其文档的例子

#[macro_use]
extern crate slog;
extern crate slog_json;

use slog::Drain;
use std::sync::Mutex;

fn main() {
    let root = slog::Logger::root(
        Mutex::new(slog_json::Json::default(std::io::stderr())).map(slog::Fuse),
        o!("version" => env!("CARGO_PKG_VERSION"))
    );
}

vs

fn main() {
    json_env_logger::init();
}

slog鼓励的编程模型是将日志记录实例作为参数传递。这是一个好习惯,允许简单的上下文传播,但代价是它是一个与使用标准logcrate编写的其他代码有很大不同的编程模型,所以你可能需要重写更多代码,而不仅仅是程序的初始化。

还有femme,它是一个漂亮的打印器,一个JSON日志记录器,以及一个WASM JavaScript对象记录器。它的优势在于它确实很漂亮!它不仅仅是漂亮的记录器,而且也不仅仅是JSON记录器。它是一系列东西的集合,使其具有广泛的应用范围,而不是仅仅关注JSON日志格式。如果你只使用其中的一个,你可能需要打包你不需要的东西。

如果你是从env_logger的环境变量驱动的配置选项迁移过来的,你可能会有些失望。你会发现你需要重新编译和重新构建你的应用程序来更改日志级别。

 
那么json_env_logger的权衡是什么呢?

很高兴你问了。它取决于env_logger,它有一些有偏见的首选设置,其中一些你可能不喜欢。例如,它默认将日志记录到stderr。你可能会选择stdout。好消息是,json_env_logger公开了其接口以覆盖这些偏见。

env_logger中一些可用的功能,json_env_logger没有使用,这些带来了额外的传递依赖。我们清楚这一点。幸运的是,它们都在env_logger功能标志后面,json_env_logger将它们全部关闭!因此,唯一的传递依赖项只是log,如果你正在进行任何类型的日志记录,你已经有了它:)

 
我还有更多问题

从技术上来说,这不是一个问题,但没关系。可以通过打开一个GitHub问题来提问。谢谢!

 

Doug Tangren (softprops) 2020

依赖项

~3–12MB
~137K SLoC