在适用于 Rust 的 AWS SDK 中配置和使用日志记录 - 适用于 Rust 的 AWS SDK
如何在适用于 Rust 的 AWS SDK 中启用日志记录解读日志微调日志记录级别

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

在适用于 Rust 的 AWS SDK 中配置和使用日志记录

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

如何在适用于 Rust 的 AWS SDK 中启用日志记录

  1. 在项目目录的命令提示符中，将 tracing-subscriber crate 添加为依赖项：

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

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

  2. 初始化订阅用户。通常，这是在调用任何适用于 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(())               
}

  3. 使用 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"

  4. 运行程序：

    $ cargo run

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

有关更多信息，请参阅 tracing-subscriber 文档中的使用环境变量筛选事件。

解读日志输出

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

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

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。

  • 生成日志条目的嵌套跨度集，用冒号(“:”)分隔。这可帮助您确定日志条目的来源。

  • 包含生成日志条目的 Rust 模块路径。

  • 日志消息文本。

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

注意

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

微调日志记录级别

如果您使用支持环境筛选的 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 名称以获取所需的信息。然后，您可以相应地设置环境变量并再次运行程序。