適用於 Java 的 AWS SDK 1.x 已於 2025 年 12 月 31 日end-of-support。我們建議您遷移至 [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html)，以繼續接收新功能、可用性改善和安全性更新。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 記錄 適用於 Java 的 AWS SDK 通話
使用 [Apache Commons Logging](http://commons.apache.org/proper/commons-logging/guide.html) 進行 適用於 Java 的 AWS SDK 檢測，Apache Commons Logging 是一種抽象層，可在執行時間使用多個記錄系統中的任何一個。
支援的記錄系統包括 Java Logging Framework 和 Apache Log4j 等等。本主題說明如何使用 Log4j。您可以使用開發套件的記錄功能，而無需更改您的應用程式程式碼。
若要進一步了解 [Log4j](http://logging.apache.org/log4j/2.x/)，請參閱 [Apache 網站](http://www.apache.org/)。
**注意**
本主題著重於 Log4j 1.x。Log4j2 不直接支援 Apache Commons Logging，但提供轉接器，使用 Apache Commons Logging 界面將記錄呼叫自動導向 Log4j2。如需詳細資訊，請參閱 Log4j2 文件中的 [Commons Logging Bridge](https://logging.apache.org/log4j/2.x/log4j-jcl.html)。
## 下載 Log4J JAR
若要搭配 SDK 使用 Log4j，您需要從 Apache 網站下載 Log4j JAR。開發套件不包含 JAR。將 JAR 檔案複製到 classpath 上的位置。
Log4j 使用組態檔案 log4j.properties。範例組態檔案如下所示。將此組態檔案複製到 classpath 上的目錄。Log4j JAR 和 log4j.properties 檔案不必位於相同的目錄中。
log4j.properties 組態檔案會指定屬性，例如[記錄層級](http://logging.apache.org/log4j/2.x/manual/configuration.html#Loggers)、記錄輸出的傳送位置 （例如[檔案或主控台](http://logging.apache.org/log4j/2.x/manual/appenders.html))，以及[輸出的格式](http://logging.apache.org/log4j/2.x/manual/layouts.html)。記錄層級是記錄器所產生輸出的精細度。Log4j 支援多個記錄*階層*的概念。每個階層的記錄層級都是獨立設定。以下兩個記錄階層可用於 適用於 Java 的 AWS SDK：
+ log4j.logger.com.amazonaws
+ log4j.logger.org.apache.http.wire
## 設定 Classpath
Log4j JAR 和 log4j.properties 檔案都必須位於 classpath 上。如果您使用的是 [Apache Ant](http://ant.apache.org/manual/)，請在 Ant 檔案中的 `path`元素中設定 classpath。下列範例顯示來自 Ant 檔案的路徑元素，適用於 Amazon S3 軟體開發套件隨附的[範例](https://github.com/aws/aws-sdk-java/blob/master/src/samples/AmazonS3/build.xml)。
```
```
如果您是使用 Eclipse IDE，可以開啟選單並導覽到 **Project (專案)** \$1 **Properties (屬性)** \$1 **Java Build Path (Java 建置路徑)** 來設定 classpath。
## 服務特定錯誤與警告
我們建議您一律將 "com.amazonaws" 記錄器階層設定為 "WARN"，以從用戶端程式庫擷取任何重要訊息。例如，如果 Amazon S3 用戶端偵測到您的應用程式未正確關閉 `InputStream`並可能洩漏資源，S3 用戶端會透過警告訊息向日誌回報。這也可確保在用戶端處理請求或回應發生任何問題時，會記錄訊息。
下列 log4j.properties 檔案會將 `rootLogger` 設定為 WARN，這會導致包含 "com.amazonaws" 階層中所有記錄器的警告和錯誤訊息。或者，您可以明確地將 com.amazonaws 記錄器設定為 WARN。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
# Or you can explicitly enable WARN and ERROR messages for the {AWS} Java clients
log4j.logger.com.amazonaws=WARN
```
## 請求/回應摘要記錄
如果您遇到 如何處理 AWS 請求的問題，對 的每個請求都會 AWS 服務 產生唯一的 AWS 服務 請求 ID。對於任何失敗的服務呼叫，可以透過 SDK 中的例外物件以程式設計方式存取 AWS 請求 IDs，也可以透過 "com.amazonaws.request" 記錄器中的 DEBUG 日誌層級進行報告。
下列 log4j.properties 檔案可啟用請求和回應的摘要，包括 AWS 請求 IDs。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
# Turn on DEBUG logging in com.amazonaws.request to log
# a summary of requests/responses with {AWS} request IDs
log4j.logger.com.amazonaws.request=DEBUG
```
以下為日誌輸出的範例。
```
2009-12-17 09:53:04,269 [main] DEBUG com.amazonaws.request - Sending
Request: POST https://rds.amazonaws.com / Parameters: (MaxRecords: 20,
Action: DescribeEngineDefaultParameters, SignatureMethod: HmacSHA256,
AWSAccessKeyId: ACCESSKEYID, Version: 2009-10-16, SignatureVersion: 2,
Engine: mysql5.1, Timestamp: 2009-12-17T17:53:04.267Z, Signature:
q963XH63Lcovl5Rr71APlzlye99rmWwT9DfuQaNznkD, ) 2009-12-17 09:53:04,464
[main] DEBUG com.amazonaws.request - Received successful response: 200, {AWS}
Request ID: 694d1242-cee0-c85e-f31f-5dab1ea18bc6 2009-12-17 09:53:04,469
[main] DEBUG com.amazonaws.request - Sending Request: POST
https://rds.amazonaws.com / Parameters: (ResetAllParameters: true, Action:
ResetDBParameterGroup, SignatureMethod: HmacSHA256, DBParameterGroupName:
java-integ-test-param-group-0000000000000, AWSAccessKeyId: ACCESSKEYID,
Version: 2009-10-16, SignatureVersion: 2, Timestamp:
2009-12-17T17:53:04.467Z, Signature:
9WcgfPwTobvLVcpyhbrdN7P7l3uH0oviYQ4yZ+TQjsQ=, )
2009-12-17 09:53:04,646 [main] DEBUG com.amazonaws.request - Received
successful response: 200, {AWS} Request ID:
694d1242-cee0-c85e-f31f-5dab1ea18bc6
```
## 詳細連線記錄
在某些情況下，查看 適用於 Java 的 AWS SDK 傳送和接收的確切請求和回應會很有用。您不應該在生產系統中啟用此記錄，因為寫入大型請求 （例如，上傳到的檔案 Amazon S3) 或回應可能會大幅降低應用程式的速度。如果您真的需要存取此資訊，您可以透過 Apache HttpClient 4 記錄器暫時啟用它。啟用 `org.apache.http.wire` 記錄器的 DEBUG 層級，可以啟用所有請求和回應資料的記錄。
下列 log4j.properties 檔案會開啟 Apache HttpClient 4 中的完整線路記錄，並且只應暫時開啟，因為它可能會對您的應用程式造成重大效能影響。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
# Log all HTTP content (headers, parameters, content, etc) for
# all requests and responses. Use caution with this since it can
# be very expensive to log such verbose data!
log4j.logger.org.apache.http.wire=DEBUG
```
## 延遲指標記錄
如果您要進行故障診斷，並想要查看哪些程序耗時最多的指標，或伺服器或用戶端的延遲是否更大，延遲記錄器會很有幫助。將`com.amazonaws.latency`記錄器設定為 DEBUG 以啟用此記錄器。
**注意**
只有在啟用 SDK 指標時，才能使用此記錄器。若要進一步了解 SDK 指標套件，請參閱[啟用 的指標 適用於 Java 的 AWS SDK](generating-sdk-metrics.md)。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
log4j.logger.com.amazonaws.latency=DEBUG
```
以下為日誌輸出的範例。
```
com.amazonaws.latency - ServiceName=[{S3}], StatusCode=[200],
ServiceEndpoint=[https://list-objects-integ-test-test.s3.amazonaws.com],
RequestType=[ListObjectsV2Request], AWSRequestID=[REQUESTID], HttpClientPoolPendingCount=0,
RetryCapacityConsumed=0, HttpClientPoolAvailableCount=0, RequestCount=1,
HttpClientPoolLeasedCount=0, ResponseProcessingTime=[52.154], ClientExecuteTime=[487.041],
HttpClientSendRequestTime=[192.931], HttpRequestTime=[431.652], RequestSigningTime=[0.357],
CredentialsRequestTime=[0.011, 0.001], HttpClientReceiveResponseTime=[146.272]
```