本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在适用于 Rust 的 AWS SDK 中配置和使用日志记录
<a name="logging"></a>

适用于 Rust 的 AWS SDK 使用[跟踪](http://tracing.rs/)框架进行日志记录。要启用日志记录，请添加 `tracing-subscriber` crate 并在 Rust 应用程序中对其进行初始化。日志包括时间戳、日志级别和模块路径，有助于调试 API 请求和 SDK 行为。使用 `RUST_LOG` 环境变量控制日志的详细程度，必要时按模块筛选。

## 如何在适用于 Rust 的 AWS SDK 中启用日志记录
<a name="enableLogging"></a>

1. 在项目目录的命令提示符中，将 [tracing-subscriber](https://crates.io/crates/tracing-subscriber) crate 添加为依赖项：

   ```
   $ cargo add tracing-subscriber --features tracing-subscriber/env-filter
   ```

   这会将 crate 添加到 `Cargo.toml` 文件的 `[dependencies]` 部分。

1. 初始化订阅用户。通常，这是在调用任何适用于 Rust 的 SDK 操作之前在 `main` 函数中提早完成的：

   ```
   use aws_config::BehaviorVersion;
   
   type BoxError = Box<dyn Error + Send + Sync>;
   
   #[tokio::main]
   async fn main() -> Result<(), BoxError> {
       tracing_subscriber::fmt::init();  // Initialize the subscriber.
       
       let config = aws_config::defaults(BehaviorVersion::latest())
           .load()
           .await;
   
       let s3 = aws_sdk_s3::Client::new(&config);
   
       let _resp = s3.list_buckets()
           .send()
           .await?;
   
       Ok(())               
   }
   ```

1. 使用 `RUST_LOG` 环境变量启用日志记录。要启用日志记录信息的显示，请在命令提示符中将 `RUST_LOG` 环境变量设置为要记录的级别。以下示例将日志记录设置为 `debug` 级别。

------
#### [ Linux/macOS ]

   ```
   $ RUST_LOG={{debug}}
   ```

------
#### [ Windows ]

   如果您使用的是 VSCode，则终端窗口通常默认为 PowerShell。验证您使用的提示类型。

   ```
   C:\> set RUST_LOG={{debug}}
   ```

------
#### [ PowerShell ]

   ```
   PS C:\> $ENV:RUST_LOG="debug"
   ```

------

1. 运行程序：

   ```
   $ cargo run
   ```

   您应该在控制台或终端窗口中看到其他输出。

有关更多信息，请参阅 `tracing-subscriber` 文档中的[使用环境变量筛选事件](https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables)。

## 解读日志输出
<a name="logging-understanding"></a>

按照上一节中的步骤启用日志记录后，默认情况下，其他日志信息将打印为标准输出。

如果您使用的是默认日志输出格式（跟踪模块称之为“完整”），则您在日志输出中看到的信息类似于以下内容：

```
2024-06-25T16:10:12.367482Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt:lazy_load_identity: aws_smithy_runtime::client::identity::cache::lazy: identity cache miss occurred; added new identity (took 480.892ms) new_expiration=2024-06-25T23:07:59Z valid_for=25066.632521s partition=IdentityCachePartition(7)
2024-06-25T16:10:12.367602Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::identity::cache::lazy: loaded identity
2024-06-25T16:10:12.367643Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: resolved identity identity=Identity { data: Credentials {... }, expiration: Some(SystemTime { tv_sec: 1719356879, tv_nsec: 0 }) }
2024-06-25T16:10:12.367695Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: signing request
```

每个条目都包含以下值：
+ 日志条目的时间戳。
+ 条目的日志级别。这是一个单词，例如 `INFO`、`DEBUG` 或 `TRACE`。
+ 生成日志条目的嵌套[跨度](https://docs.rs/tracing/latest/tracing/span/index.html)集，用冒号(“:”)分隔。这可帮助您确定日志条目的来源。
+ 包含生成日志条目的 Rust 模块路径。
+ 日志消息文本。

跟踪模块的标准输出格式使用 ANSI 转义码对输出进行着色。筛选或搜索输出时，请记住这些转义序列。

**注意**  
嵌套跨度集中显示的 `sdk_invocation_id` 是由 SDK 在客户端生成的唯一 ID，用于帮助关联日志消息。它与在 AWS 服务的响应中找到的请求 ID 无关。

## 微调日志记录级别
<a name="logging-control"></a>

如果您使用支持环境筛选的 crate（例如 `tracing_subscriber`），则可以按模块控制日志的详细程度。

您可以为每个模块开启相同的日志记录级别。以下内容将每个模块的日志记录级别设置为了 `trace`：

```
$ RUST_LOG={{trace}} cargo run
```

您可以为特定模块开启跟踪级别日志记录。在以下示例中，只有来自 `aws_smithy_runtime` 的日志才会进入 `trace` 级别。

```
$ RUST_LOG={{aws_smithy_runtime}}={{trace}}
```

您可以用逗号分隔多个模块，从而为它们指定不同的日志级别。以下示例将 `aws_config` 模块设置为 `trace` 级别日志记录，将 `aws_smithy_runtime` 模块设置为 `debug` 级别日志记录。

```
$ RUST_LOG={{aws_config}}={{trace}},{{aws_smithy_runtime}}={{debug}} cargo run
```

下表列出了可用于筛选日志消息的一些模块：


| Prefix | 描述 | 
| --- | --- | 
| `aws_smithy_runtime` | 请求和响应线路日志记录 | 
| `aws_config` | 凭证加载 | 
| `aws_sigv4` | 请求签名和规范请求 | 

要确定需要在日志输出中包含哪些模块，一种方法是先记录所有内容，然后在日志输出中找到 crate 名称以获取所需的信息。然后，您可以相应地设置环境变量并再次运行程序。