From 42293a886e00124152b5148e4856248f1e297c40 Mon Sep 17 00:00:00 2001
From: sunface <cto@188.com>
Date: Fri, 8 Apr 2022 22:45:58 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E7=AB=A0=E8=8A=82:=20?=
 =?UTF-8?q?=E6=97=A5=E5=BF=97=E9=97=A8=E9=9D=A2=E5=BA=93=20log?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/SUMMARY.md                      |   8 +-
 src/practice/logs/about-log.md      |   4 +-
 src/practice/logs/log.md            | 231 +++++++++++++++++++++++++++-
 src/practice/logs/tracing-logger.md |   7 +-
 4 files changed, 241 insertions(+), 9 deletions(-)

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)
   <!-- - [代码开发实践 todo](practice/best-pratice.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