本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 記錄
<a name="logging"></a>

會將 [SLF4J](https://www.slf4j.org/manual.html) 相容記錄器 適用於 Kotlin 的 AWS SDK 設定為遙測提供者`LoggerProvider`的預設值。使用 SLF4J 是一種抽象層，您可以在執行時間使用多個記錄系統中的任何一個。支援的記錄系統包括 [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 啟用日誌輸出：

**梯度相依性**

（您可以導覽至 {{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` 屬性中的`%X`指標，可啟用 MDC （映射診斷內容） 記錄。

軟體開發套件會為每個操作新增下列 MDC 元素。

**rpc**  
調用 RPC 的名稱，例如 `S3.GetObject`。

**sdkInvocationId**  
由服務用戶端為 操作指派的唯一 ID。ID 會關聯與呼叫單一 操作相關的所有記錄事件。

## 指定線路層級訊息的日誌模式
<a name="sdk-log-mode"></a>

根據預設， 適用於 Kotlin 的 AWS SDK 不會記錄線路層級訊息，因為它們可能包含來自 API 請求和回應的敏感資料。不過，有時您需要此層級的詳細資訊以進行偵錯。

使用 Kotlin 開發套件，您可以在程式碼中或使用環境設定來啟用下列項目的偵錯訊息：
+ 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 ...
```

**注意**  
您還必須設定相容的 SLF4J 記錄器，並將記錄層級設定為 DEBUG，以啟用線路層級記錄。