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

# 日志记录
<a name="logging"></a>

将兼容 [SLF4J](https://www.slf4j.org/manual.html) 的记录器 适用于 Kotlin 的 AWS SDK 配置为遥测提供商`LoggerProvider`的默认记录器。使用 SLF4 J（抽象层），您可以在运行时使用多个日志系统中的任何一个。[支持的日志系统包括 [Java Logging APIs](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/)、[Log4j 2](https://logging.apache.org/log4j/2.x/) 和 Logback。](https://logback.qos.ch/)

**警告**  
我们建议您仅将线路日志用于调试目的。（下文将讨论线路记录。） 在生产环境中将其关闭，因为它可以记录敏感数据，例如电子邮件地址、安全令牌、API 密钥、密码和 AWS Secrets Manager 机密。即使是 HTTPS 呼叫，电线日志记录也无需加密即可记录完整的请求或响应。  
对于大型请求（例如将文件上传到 Amazon S3）或响应，冗长的电汇记录也会显著影响应用程序的性能。

## Log4j 2 日志配置示例
<a name="log4j2-example"></a>

 虽然可以使用任何`SLF4J`兼容的日志库，但此示例使用 Log4j 2 在 JVM 程序中启用 SDK 的日志输出：

**Gradle 依赖关系**

（您可以导航到该{{X.Y.Z}}链接以查看可用的最新版本。）

```
implementation("org.apache.logging.log4j:log4j-slf4j2-impl:[https://search.maven.org/#search|gav|1|g:org.apache.logging.log4j%20AND%20a:log4j-slf4j2-impl](https://search.maven.org/#search|gav|1|g:org.apache.logging.log4j%20AND%20a:log4j-slf4j2-impl)")
```

**Log4j 2 配置文件**

`log4j2.xml`在您的`resources`目录中创建一个名为的文件（例如，`<project-dir>/src/main/resources`）。将以下 XML 配置添加到文件中：

```
<Configuration status="ERROR">
    <Appenders>
        <Console name="Out">
            <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} %-5p %c:%L %X - %encode{%m}{CRLF}%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Out"/>
        </Root>
    </Loggers>
</Configuration>
```

此配置在`pattern`属性中包含启用 MDC（映射的诊断上下文）日志记录的`%X`说明符。

SDK 为每个操作添加以下 MDC 元素。

**rpc**  
例如`S3.GetObject`，被调用的 RPC 的名称。

**sdkInvocationId**  
服务客户端为操作分配的唯一 ID。该 ID 关联与调用单个操作相关的所有日志事件。

## 为线级消息指定日志模式
<a name="sdk-log-mode"></a>

默认情况下， 适用于 Kotlin 的 AWS SDK 不记录线级消息，因为它们可能包含来自 API 请求和响应的敏感数据。但是，有时出于调试目的，你需要这种详细程度。

使用 Kotlin SDK，您可以在代码中设置日志模式，也可以使用环境设置为以下内容启用调试消息：
+ HTTP 请求
+ HTTP 响应

日志模式由一个位域支持，其中每个位都是一个标志（模式），值是累加的。您可以将一种请求模式和一种响应模式结合使用。

### 在代码中设置日志模式
<a name="set-log-mode-programmatically"></a>

要选择使用其他日志记录，请在构建服务客户端时设置该`logMode`属性。

以下示例说明如何启用请求（使用正文）和响应（不带正文）的日志记录。

```
import aws.smithy.kotlin.runtime.client.LogMode

// ...

val client = DynamoDbClient {
    // ...
    logMode = LogMode.LogRequestWithBody + LogMode.LogResponse
}
```

在服务客户端构建期间设置的日志模式值会覆盖环境中设置的任何日志模式值。

### 从环境中设置日志模式
<a name="set-log-mode-from-enviironment"></a>

要为所有未在代码中明确配置的服务客户机设置全局日志模式，请使用以下方法之一：
+ JVM 系统属性：`sdk.logMode`
+ 环境变量：`SDK_LOG_MODE`

以下不区分大小写的值可用：
+ `LogRequest`
+ `LogRequestWithBody`
+ `LogResponse`
+ `LogResponseWithBody`

要使用环境中的设置创建组合日志模式，请使用竖线 (`|`) 符号分隔值。

例如，以下示例设置的日志模式与前面的示例相同。

```
# Environment variable.
export SDK_LOG_MODE=LogRequestWithBody|LogResponse
```

```
# JVM system property.
java -Dsdk.logMode=LogRequestWithBody|LogResponse ...
```

**注意**  
您还必须配置兼容的 SLF4 J Logger 并将日志级别设置为 DEBUG 才能启用线级日志记录。