View a markdown version of this page

記錄 - AWS SDK for Kotlin
指定線路層級訊息的日誌模式

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

記錄

會將 SLF4J 相容記錄器AWS SDK for Kotlin設定為遙測提供者LoggerProvider的預設值。使用 SLF4J 是一種抽象層，您可以在執行時間使用多個記錄系統中的任何一個。支援的記錄系統包括 Java Logging APIs、Log4j 2 和 Logback。

警告

我們建議您僅使用線路記錄進行除錯。（以下將討論線路記錄。) 在生產環境中將其關閉，因為它可以記錄敏感資料，例如電子郵件地址、安全字符、API 金鑰、密碼和AWS Secrets Manager秘密。線路記錄會記錄完整的請求或回應，無需加密，即使是 HTTPS 呼叫也一樣。

對於大型請求 （例如將檔案上傳至 Amazon S3) 或回應，詳細的線路記錄也會大幅影響應用程式的效能。

雖然可以使用任何 SLF4J相容的日誌程式庫，但此範例會使用 Log4j 2 從 JVM 程式中的 SDK 啟用日誌輸出：

梯度相依性

（您可以導覽至 X.Y.Z 連結，以查看可用的最新版本。)

implementation("org.apache.logging.log4j:log4j-slf4j2-impl:X.Y.Z")

Log4j 2 組態檔案

在log4j2.xmlresources目錄中建立名為 的檔案 （例如，<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 會關聯與呼叫單一 操作相關的所有記錄事件。

指定線路層級訊息的日誌模式

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

使用 Kotlin 開發套件，您可以在程式碼中或使用環境設定來啟用下列項目的偵錯訊息：

  • HTTP 請求

  • HTTP 回應

日誌模式的後端是位元欄位，其中每個位元都是旗標 （模式），而值是累加的。您可以結合一個請求模式和一個回應模式。

在程式碼中設定日誌模式

若要選擇加入其他記錄，請在建構服務用戶端時設定 logMode 屬性。

下列範例示範如何啟用 請求記錄 （含內文） 和 回應 （不含內文）。

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

// ...

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

在服務用戶端建構期間設定的日誌模式值， 會覆寫從環境設定的任何日誌模式值。

從環境設定日誌模式

若要針對程式碼中未明確設定的所有服務用戶端全域設定日誌模式，請使用下列其中一項：

  • 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，以啟用線路層級記錄。