diff --git a/src/SUMMARY.md b/src/SUMMARY.md index eb5e5789..8e3c93d5 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -174,12 +174,12 @@ - [Rust 最佳实践](practice/intro.md) - [日常开发三方库精选](practice/third-party-libs.md) - [命名规范](practice/naming.md) - - [记录日志](practice/logs/intro.md) + - [日志](practice/logs/intro.md) - [日志详解](practice/logs/about-log.md) - - [使用 log 记录日志](practice/logs/log.md) - - [使用 tracing 记录日志](practice/logs/tracing.md) + - [日志门面 log](practice/logs/log.md) + - [使用 tracing 记录日志 TODO](practice/logs/tracing.md) - [自定义 tracing 的输出格式](practice/logs/tracing-logger.md) - - [可观测性监控 TODO](practice/observe/intro.md) + - [监控 TODO](practice/observe/intro.md) - [监控详解 TODO](practice/observe/about-observe.md) - [面试经验](practice/interview.md) diff --git a/src/practice/logs/about-log.md b/src/practice/logs/about-log.md index aa730d07..5c22a86a 100644 --- a/src/practice/logs/about-log.md +++ b/src/practice/logs/about-log.md @@ -7,6 +7,7 @@ ## 日志级别和输出位置 #### 日志级别 + 日志级别是对基本的“滚动文本”式日志记录的一个重要补充。每条日志消息都会基于其重要性或严重程度分配到一个日志级别。例如,对于某个程序,“你的电脑着火了”是一个非常重要的消息,而“无法找到配置文件”的重要等级可能就低一些;但对于另外一些程序,"无法找到配置文件" 可能才是最严重的错误,会直接导致程序无法正常启动,而“电脑着火”? 我们可能会记录为一条 `Debug` 日志(参见下文) :D。 @@ -53,7 +54,8 @@ 目前常用的日志采集工具有 filebeat、vector( Rust 开发,功能强大,性能非常高 ) 等,它们都是以 agent 的形式运行在你的应用程序旁边( 在同一个 pod 或虚拟机上 ),提供贴心的服务。 -## 集中式日志存储 +## 中心化日志存储 + 最后,我们再来简单介绍下日志存储。提到存储,首先不得不提的就是日志使用方式。 其实,除了 Debug 的时候,我们使用日志基本都是基于某个关键字进行搜索的,将日志存储在各台主机上的硬盘文件中,然后逐个去查询显然是非常非常低效的,最好的方式就是将日志集中收集上来后,存储在一个搜索平台中,例如 ElasticSearch。 diff --git a/src/practice/logs/log.md b/src/practice/logs/log.md index 489c61cc..c6909601 100644 --- a/src/practice/logs/log.md +++ b/src/practice/logs/log.md @@ -1,8 +1,235 @@ -# 在 Rust 中记录日志 +# 日志门面 log + +就如同 slf4j 是 Java 的日志门面库,[log](https://github.com/rust-lang/log) 也是 Rust 的日志门面库( 这不是我自己编的,官方用语: logging facade ),它目前是由官方提供维护工作,更新较为活跃,因此大家可以放心使用。 + +使用方式很简单,只要在 `Cargo.toml` 中引入即可: +```toml +[dependencies] +log = "0.4" +``` + +> 日志门面不是说排场很大的意思,而是指相应的日志 API 已成为事实上的标准,会被其它日志框架所使用。通过这种统一的门面,开发者就可以不必再拘泥于日志框架的选择,未来大不了再换一个日志框架就是 + +既然是门面,`log` 自然定义了一套统一的日志特征和 API,将日志的操作进行了抽象。 + +## Log 特征 + +例如,它定义了一个 `Log` 特征: +```rust +pub trait Log: Sync + Send { + fn enabled(&self, metadata: &Metadata<'_>) -> bool; + fn log(&self, record: &Record<'_>); + fn flush(&self); +} +``` + +- `enabled` 用于判断某条带有元数据的日志是否能被记录,它对于 `log_enabled!` 宏特别有用 +- `log` 会记录 `record` 所代表的日志 +- `flush` 会将缓存中的日志数据刷到输出中,例如标准输出或者文件中 + +## 日志宏 + +`log` 还为我们提供了一整套标准的宏,用于方便地记录日志。`trace!`、`debug!`、`info!`、`warn!`、`error!`,这几个大家是否很眼熟,是的,它们跟我们上一章节提到的日志级别几乎一模一样,唯一的区别就是这里乱入了一个 `trace!`,它比 `debug!` 的日志级别还要低、记录的信息还要详细,这么说吧,如果你想事无巨细的追踪某个流程的所有信息,就可以用它了。 +```rust +use log::{info, trace, warn}; + +pub fn shave_the_yak(yak: &mut Yak) { + trace!("Commencing yak shaving"); + + loop { + match find_a_razor() { + Ok(razor) => { + info!("Razor located: {}", razor); + yak.shave(razor); + break; + } + Err(err) => { + warn!("Unable to locate a razor: {}, retrying", err); + } + } + } +} +``` + +上面的例子使用 `trace!` 记录了一条可有可无的信息:准备开始剃须,然后开始寻找剃须刀,找到后就用 `info!` 记录一条可能事后也没人看的信息:找到剃须刀;没找到的话,就记录一条 `warn!` 信息,这条信息就有一定价值了,不仅告诉我们没找到的原因,还记录了发生的次数,有助于事后定位问题。 + +可以看出,这里的日志级别使用跟我们上一章节描述的基本吻合。 + +除了以上常用的,`log` 还提供了 `log!` 和 `log_enabled!` 宏,后者用于确定一条消息在当前模块中,对于给定的日志级别是否能够被记录 + +```rust +use log::Level::Debug; +use log::{debug, log_enabled}; + +// 判断能否记录 Debug 消息 +if log_enabled!(Debug) { + let data = expensive_call(); + // 下面的日志记录较为昂贵,因此我们先在前面判断了是否能够记录,能,才继续这里的逻辑 + debug!("expensive debug data: {} {}", data.x, data.y); +} +if log_enabled!(target: "Global", Debug) { + let data = expensive_call(); + debug!(target: "Global", "expensive debug data: {} {}", data.x, data.y); +} +``` + +而 `log!` 宏就简单的多,它是一个通用的日志记录方式,因此需要我们手动指定日志级别: +```rust +use log::{log, Level}; + +let data = (42, "Forty-two"); +let private_data = "private"; + +log!(Level::Error, "Received errors: {}, {}", data.0, data.1); +log!(target: "app_events", Level::Warn, "App warning: {}, {}, {}", + data.0, data.1, private_data); +``` + +## 日志输出在哪里? +我不知道有没有同学尝试运行过上面的代码,但是我知道,就算你们运行了,也看不到任何输出。 + +为什么?原因很简单,`log` 仅仅是日志门面库,**它并不具备完整的日志库功能!**,因此你无法在控制台中看到任何日志输出,这种情况下,说实话,远不如一个 `println!` 有用! + +但是别急,让我们看看该如何让 `log` 有用起来。 + + +## 使用具体的日志库 +`log` 包这么设计,其实是有很多好处的。 + +### Rust 库的开发者 +最直接的好处就是,如果你是一个 Rust 库开发者,那你自己或库的用户肯定都不希望这个库绑定任何具体的日志库,否则用户想使用 `log1` 来记录日志,你的库却使用了 `log2`,这就存在很多问题了! + +因此,**作为库的开发者,你只要在库中使用门面库即可**,将具体的日志库交给用户去选择和绑定。 +```rust +use log::{info, trace, warn}; +pub fn deal_with_something() { + // 开始处理 + + // 记录一些日志 + trace!("a trace log"); + info!("a info long: {}", "abc"); + warn!("a warning log: {}, retrying", err); + + // 结束处理 +} +``` + +### 应用开发者 +如果是应用开发者,那你的应用运行起来,却看不到任何日志输出,这种场景想想都捉急。此时就需要去选择一个具体的日志库了。 + +目前来说,已经有了不少日志库实现,官方也[推荐了一些](https://github.com/rust-lang/log#in-executables) +,大家可以根据自己的需求来选择,不过 [env_logger](https://docs.rs/env_logger/*/env_logger/) 是一个相当不错的选择。 + +`log` 还提供了 [set_logger](https://docs.rs/log/0.4.8/log/fn.set_logger.html) 函数用于设置日志库,[set_max_level](https://docs.rs/log/0.4.8/log/fn.set_max_level.html) 用于设置最大日志级别,但是如果你选了具体的日志库,它往往会提供更高级的 API,无需我们手动调用这两个函数,例如下面的 `env_logger` 就是如此。 + +#### env_logger + +修改 `Cargo.toml` , 添加以下内容: +```toml +# in Cargo.toml + +[dependencies] +log = "0.4.0" +env_logger = "0.9" +``` + +在 `src/main.rs` 中添加如下代码: +```rust +use log::{debug, error, log_enabled, info, Level}; + +fn main() { + // 注意,env_logger 必须尽可能早的初始化 + env_logger::init(); + + debug!("this is a debug {}", "message"); + error!("this is printed by default"); + + if log_enabled!(Level::Info) { + let x = 3 * 4; // expensive computation + info!("the answer was: {}", x); + } +} +``` + +在运行程序时,可以通过环境变量来设定日志级别: +```shell +$ RUST_LOG=error ./main +[2017-11-09T02:12:24Z ERROR main] this is printed by default +``` + +我们还可以为单独一个模块指定日志级别: +```shell +$ RUST_LOG=main=info ./main +[2017-11-09T02:12:24Z ERROR main] this is printed by default +[2017-11-09T02:12:24Z INFO main] the answer was: 12 +``` + +还能为某个模块开启所有日志级别: +```shell +$ RUST_LOG=main ./main +[2017-11-09T02:12:24Z DEBUG main] this is a debug message +[2017-11-09T02:12:24Z ERROR main] this is printed by default +[2017-11-09T02:12:24Z INFO main] the answer was: 12 +``` + +需要注意的是,如果文件名包含 `-`,你需要将其替换成下划线来使用,原因是 Rust 的模块和包名不支持使用 `-`。 +```shell +$ RUST_LOG=my_app ./my-app +[2017-11-09T02:12:24Z DEBUG my_app] this is a debug message +[2017-11-09T02:12:24Z ERROR my_app] this is printed by default +[2017-11-09T02:12:24Z INFO my_app] the answer was: 12 +``` + +默认情况下,`env_logger` 会输出到标准错误 `stderr`,如果你想要输出到标准输出 `stdout`,可以使用 `Builder` 来改变日志对象( target ): +```rust +use std::env; +use env_logger::{Builder, Target}; + +let mut builder = Builder::from_default_env(); +builder.target(Target::Stdout); + +builder.init(); +``` + +默认 ```rust if cfg!(debug_assertions) { eprintln!("debug: {:?} -> {:?}", record, fields); } -``` \ No newline at end of file +``` + +### 日志库开发者 +对于这类开发者而言,自然要实现自己的 `Log` 特征咯: + +```rust +use log::{Record, Level, Metadata}; +struct SimpleLogger; +impl log::Log for SimpleLogger { + fn enabled(&self, metadata: &Metadata) -> bool { + metadata.level() <= Level::Info + } + fn log(&self, record: &Record) { + if self.enabled(record.metadata()) { + println!("{} - {}", record.level(), record.args()); + } + } + fn flush(&self) {} +} +``` + +除此之外,我们还需要像 `env_logger` 一样包装下 `set_logger` 和 `set_max_level`: +```rust +use log::{SetLoggerError, LevelFilter}; +static LOGGER: SimpleLogger = SimpleLogger; +pub fn init() -> Result<(), SetLoggerError> { + log::set_logger(&LOGGER) + .map(|()| log::set_max_level(LevelFilter::Info)) +} +``` + + +## 更多示例 +关于 `log` 门面库和具体的日志库还有更多的使用方式,详情请参见锈书的[开发者工具](https://rusty.rs/devtools/log.html)一章。 + diff --git a/src/practice/logs/tracing-logger.md b/src/practice/logs/tracing-logger.md index c5c7ec50..f8ac6262 100644 --- a/src/practice/logs/tracing-logger.md +++ b/src/practice/logs/tracing-logger.md @@ -1,6 +1,6 @@ # 使用 tracing 输出自定义的 Rust 日志 -在 [tracing](https://docs.rs/crate/tracing/latest) 包出来前,Rust 的日志和监控可以说是一片鱼塘,是的,连鱼龙混杂都算不上。在大名鼎鼎的 tokio 开发团队推出 `tracing` 后,我现在坚定的认为 `tracing` 就是未来! +在 [tracing](https://docs.rs/crate/tracing/latest) 包出来前,Rust 的日志也就 `log` 有一战之力,但是 `log` 的功能相对来说还是鸡简单一些。在大名鼎鼎的 tokio 开发团队推出 `tracing` 后,我现在坚定的认为 `tracing` 就是未来! > 截至目前,rust编译器团队、GraphQL 都在使用 tracing,而且 tokio 在密谋一件大事:基于 tracing 开发一套终端交互式 debug 工具: [console](https://github.com/tokio-rs/console)! @@ -621,4 +621,7 @@ fn on_record( 终于,在最后,我们拥有了一个功能齐全的自定义的 JSON logger,大家快去尝试下吧。当然,你也可以根据自己的需求来定制专属于你的 logger,毕竟方法是一通百通的。 -> 在以下 github 仓库,可以找到完整的代码: https://github.com/bryanburgers/tracing-blog-post \ No newline at end of file +> 在以下 github 仓库,可以找到完整的代码: https://github.com/bryanburgers/tracing-blog-post +> +> 本文由 Rustt 提供翻译 +> 原文链接: https://github.com/studyrs/Rustt/blob/main/Articles/%5B2022-04-07%5D%20在%20Rust%20中使用%20tracing%20自定义日志.md