本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在中設定可觀測性功能 AWS SDK for Java 2.x 遙測是從遠端來源自動收集和傳輸資料，讓您能夠監控和分析系統的行為。適用於 Java 的 SDK 2.x 中的可觀測性，可讓開發人員全面了解其 Java 應用程式如何 AWS 服務透過擷取完整請求生命週期的豐富遙測資料與互動。這些功能可讓您收集、分析和視覺化遙測訊號，例如指標、日誌和追蹤，讓您監控請求模式、識別瓶頸，並最佳化應用程式 AWS 的互動，以提高可靠性和效能。 **Topics** + [指標](metrics.md) + [監控](monitoring-overview.md) + [日誌](logging-slf4j.md) # 從發佈 SDK 指標 AWS SDK for Java 2.x 使用 AWS SDK for Java 2.x ，您可以收集應用程式中服務用戶端和請求的指標，分析 Amazon CloudWatch Logs 中的輸出，然後對其採取行動。根據預設，在 SDK 中會停用指標集合。本主題可協助您啟用和設定它。 ## SDK 指標入門若要在您的應用程式中啟用指標收集，請根據您的使用案例選擇適當的`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`界面實作，並遵循詳細的設定指示： **對於長時間執行的應用程式：** + 使用 `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` + 如需完整的設定指示、程式碼範例和組態選項，請參閱[從長時間執行的應用程式發佈 SDK 指標](metric-pub-impl-cwmp.md)。 **對於 AWS Lambda 函數：** + 使用 `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` + 如需完整的設定指示、相依性和 Lambda 特定組態，請參閱[發佈 AWS Lambda 函數的 SDK 指標](metric-pub-impl-emf.md)。 **針對故障診斷和主控台輸出：** + 使用 `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` + 如需設定指示、格式化選項，以及本機[開發和故障診斷的範例，請參閱將 SDK 指標輸出至主控台以進行開發和偵錯](metric-pub-impl-logging.md)。 ## 快速實作預覽以下是為每個使用案例啟用指標的外觀： **長時間執行的應用程式：** ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` **Lambda 函數：** ``` EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("MyApp") .build(); DynamoDbClient dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .build(); ``` **開發和偵錯：** ``` MetricPublisher loggingPublisher = LoggingMetricPublisher.create(); S3Client s3 = S3Client.builder() .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher)) .build(); ``` ## AWS CRT 型 S3 用戶端的指標限制 [AWS CRT 型 S3 用戶端](crt-based-s3-client.md)目前不支援 SDK 指標集合。 AWS CRT 型 S3 用戶端執行個體的建置器[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html)不提供設定指標發佈者的方法。 ## 何時可使用指標？指標通常會在適用於 Java 的開發套件發出後 5-10 分鐘內提供。如需準確且up-to-date指標，請在從 Java 應用程式發出指標後至少 10 分鐘檢查 Cloudwatch。 ## 會收集哪些資訊？指標集合包括下列項目： + API 請求的數量，包括它們是成功還是失敗 + AWS 服務您在 API 請求中呼叫的相關資訊，包括傳回的例外狀況 + 各種操作的持續時間，例如封送、簽署和 HTTP 請求 + HTTP 用戶端指標，例如開啟的連線數量、待處理的請求數量，以及使用的 HTTP 用戶端名稱 **注意** 可用的指標因 HTTP 用戶端而異。如需完整清單，請參閱[服務用戶端指標](metrics-list.md)。 ## 如何使用此資訊？您可以使用 SDK 收集的指標來監控應用程式中的服務用戶端。您可以查看整體用量趨勢、識別異常、檢閱傳回的服務用戶端例外狀況，或深入了解特定問題。使用 Amazon CloudWatch Logs，您也可以建立警示，在應用程式到達您定義的條件時立即通知您。如需詳細資訊，請參閱《[Amazon CloudWatch Logs 使用者指南》中的使用 Amazon CloudWatch Logs 指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)[和 Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)[使用 Amazon CloudWatch Logs Amazon CloudWatch 警示](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。 # 使用從長時間執行的應用程式發佈 SDK 指標 AWS SDK for Java 2.x 由於`[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)`實作會彙總指標並定期延遲上傳至 Amazon CloudWatch，因此最適合長時間執行的應用程式。指標發佈者的預設設定旨在將記憶體用量和 CloudWatch 成本降至最低，同時仍提供對指標資料的實用洞見。 ## 設定您必須先完成下列步驟`CloudWatchMetricPublisher`，才能使用啟用和使用指標。 ### 步驟 1：新增必要的相依性將專案相依性（例如，在您的 `pom.xml`或 `build.gradle` 檔案中）設定為使用版本 `2.14.0` 或更新版本適用於 Java 的 AWS SDK。在專案的相依性中，將 artifactId `cloudwatch-metric-publisher` 包含版本編號 `2.14.0`或更新版本。例如： ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk cloudwatch-metric-publisher ``` ### 步驟 2：設定必要的許可啟用指標發佈者使用的 IAM 身分`cloudwatch:PutMetricData`許可，以允許適用於 Java 的 SDK 寫入指標。 ## 啟用特定請求的指標下列類別說明如何為 Amazon DynamoDB 的請求啟用 CloudWatch 指標發佈者。它使用預設指標發佈者組態。 ``` import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest; public class DefaultConfigForRequest { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.create(); // Publish metrics the for ListTables operation. ddb.listTables(ListTablesRequest.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build()); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` **重要** 確保您的應用程式`close`在服務用戶端不再使用時呼叫`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`執行個體。否則可能會導致執行緒或檔案描述項洩漏。 ## 啟用特定服務用戶端的摘要指標下列程式碼片段示範如何使用服務用戶端的預設設定啟用 CloudWatch 指標發佈者。 ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` ## 自訂 CloudWatch 指標發佈者下列類別示範如何為特定服務用戶端的指標發佈者設定自訂組態。自訂包括載入特定設定檔、指定指標發佈者傳送請求 AWS 的區域，以及自訂發佈者將指標傳送至 CloudWatch 的頻率。 ``` import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider; import software.amazon.awssdk.core.metrics.CoreMetric; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import java.time.Duration; public class CustomConfigForDDBClient { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.builder() .cloudWatchClient(CloudWatchAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(ProfileCredentialsProvider.create("cloudwatch")) .build()) .uploadFrequency(Duration.ofMinutes(5)) .maximumCallsPerUpload(100) .namespace("ExampleSDKV2Metrics") .detailedMetrics(CoreMetric.API_CALL_DURATION) .build(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); // Publish metrics for DynamoDB operations. ddb.listTables(); ddb.describeEndpoints(); ddb.describeLimits(); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` 上一個程式碼片段中顯示的自訂具有下列效果。 + `cloudWatchClient` 方法可讓您自訂用於傳送指標的 CloudWatch 用戶端。在此範例中，我們使用與 *us-east-1* 預設值不同的區域，用戶端會在其中傳送指標。我們也使用不同的具名設定檔 *cloudwatch*，其登入資料將用於驗證對 CloudWatch 的請求。這些登入資料必須具有的許可`cloudwatch:PutMetricData`。 + `uploadFrequency` 方法可讓您指定指標發佈者將指標上傳至 CloudWatch 的頻率。預設值為每分鐘一次。 + `maximumCallsPerUpload` 方法會限制每次上傳進行的呼叫數量。預設值為無限制。 + 依預設，適用於 Java 的 SDK 2.x 會在命名空間下發佈指標。 `AwsSdk/JavaSdk2`您可以使用 `namespace`方法來指定不同的值。 + 根據預設，軟體開發套件會發佈摘要指標。摘要指標包含平均值、最小值、最大值、總和和範例計數。透過在 `detailedMetrics`方法中指定一或多個 SDK 指標，SDK 會為每個指標發佈其他資料。此額外資料可讓您在 CloudWatch 中查詢 p90 和 p99 等百分位數統計資料。詳細指標特別適用於延遲指標，例如 `APICallDuration`，可測量 SDK 用戶端請求的end-to-end延遲。您可以使用 `[CoreMetric](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)`類別的欄位來指定其他常見的 SDK 指標。 **後續步驟：**如果您也使用 Lambda 函數，請參閱[為以 EMF 為基礎的指標發佈 AWS Lambda 函數發佈 SDK](metric-pub-impl-emf.md) 指標。 # 使用發佈 AWS Lambda 函數的 SDK 指標 AWS SDK for Java 2.x 由於 Lambda 函數通常會執行幾毫秒到幾分鐘，因此傳送指標時發生的任何延遲都會造成資料遺失`CloudWatchMetricPublisher`的風險。 `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` 透過立即將指標寫入 [CloudWatch Embedded Metric Format (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) 中的結構化日誌項目，提供更合適的方法。 `EmfMetricLoggingPublisher` 可在與 Amazon CloudWatch Logs AWS Lambda 和 Amazon Elastic Container Service 等內建整合的執行環境中運作。 ## 設定您必須先完成下列步驟`EmfMetricLoggingPublisher`，才能使用啟用和使用指標。 ### 步驟 1：新增必要的相依性將專案相依性（例如，在您的 `pom.xml`或 `build.gradle` 檔案中）設定為使用版本 `2.30.3` 或更新版本適用於 Java 的 AWS SDK。在專案的相依性中，將 artifactId `emf-metric-logging-publisher` 包含版本編號 `2.30.3`或更新版本。例如： ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk emf-metric-logging-publisher ``` ### 步驟 2：設定必要的許可啟用指標發佈者使用的 IAM 身分`logs:PutLogEvents`許可，以允許適用於 Java 的 SDK 寫入 EMF 格式的日誌。 ### 步驟 3：設定記錄為了確保適當的指標收集，請將您的記錄設定為輸出至 `INFO` 層級或更低的主控台（例如 `DEBUG`)。在您的 `log4j2.xml` 檔案中： ``` ``` 如需如何設定`log4j2.xml`檔案的詳細資訊，請參閱本指南中的[記錄主題](logging-slf4j.md)。 ## 設定和使用 `EmfMetricLoggingPublisher` 下列 Lambda 函數類別會先建立和設定`EmfMetricLoggingPublisher`執行個體，然後將其與 Amazon DynamoDB 服務用戶端搭配使用： ``` public class GameIdHandler implements RequestHandler, String> { private final EmfMetricLoggingPublisher emfPublisher; private final DynamoDbClient dynamoDb; public GameIdHandler() { // Build the publisher. this.emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("namespace") .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME) .build(); // Add the publisher to the client. this.dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .region(Region.of(System.getenv("AWS_REGION"))) .build(); } @Override public String handleRequest(Map event, Context context) { Map gameItem = new HashMap<>(); gameItem.put("gameId", AttributeValue.builder().s(event.get("id")).build()); PutItemRequest putItemRequest = PutItemRequest.builder() .tableName("games") .item(gameItem) .build(); dynamoDb.putItem(putItemRequest); return "Request handled"; } } ``` DynamoDB 用戶端執行 `putItem`方法時，會自動以 EMF 格式將指標發佈至 CloudWatch 日誌串流。 ### EMF 日誌事件的範例例如，如果您將下列事件傳送至 GameHandler Lambda 函數，並設定記錄，如先前所示： ``` { "id": "23456" } ``` 函數處理事件後，您會找到兩個類似下列範例的日誌事件。第二個事件中的 JSON 物件包含 DynamoDB `PutItem`操作的 Java SDK 指標資料。當 CloudWatch 收到 EMF 格式的日誌事件時，會自動剖析結構化 JSON 以擷取指標資料。然後CloudWatch 會在將原始日誌項目存放在 CloudWatch Logs 時建立對應的指標。 ``` 2025-07-11 15:58:30 [main] INFO org.example.GameIdHandler:39 - Received map: {id=23456} 2025-07-11 15:58:34 [main] INFO software.amazon.awssdk.metrics.publishers.emf.EmfMetricLoggingPublisher:43 - { "_aws": { "Timestamp": 1752249513975, "LogGroupName": "/aws/lambda/GameId", "CloudWatchMetrics": [ { "Namespace": "namespace", "Dimensions": [ [ "OperationName", "ServiceId" ] ], "Metrics": [ { "Name": "AvailableConcurrency" }, { "Name": "PendingConcurrencyAcquires" }, { "Name": "ServiceCallDuration", "Unit": "Milliseconds" }, { "Name": "EndpointResolveDuration", "Unit": "Milliseconds" }, { "Name": "MaxConcurrency" }, { "Name": "BackoffDelayDuration", "Unit": "Milliseconds" }, { "Name": "MarshallingDuration", "Unit": "Milliseconds" }, { "Name": "LeasedConcurrency" }, { "Name": "SigningDuration", "Unit": "Milliseconds" }, { "Name": "ConcurrencyAcquireDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallSuccessful" }, { "Name": "RetryCount" }, { "Name": "UnmarshallingDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallDuration", "Unit": "Milliseconds" }, { "Name": "CredentialsFetchDuration", "Unit": "Milliseconds" } ] } ] }, "AvailableConcurrency": 0, "PendingConcurrencyAcquires": 0, "OperationName": "PutItem", "ServiceCallDuration": 1339, "EndpointResolveDuration": 81, "MaxConcurrency": 50, "BackoffDelayDuration": 0, "ServiceId": "DynamoDB", "MarshallingDuration": 181, "LeasedConcurrency": 1, "SigningDuration": 184, "ConcurrencyAcquireDuration": 83, "ApiCallSuccessful": 1, "RetryCount": 0, "UnmarshallingDuration": 85, "ApiCallDuration": 1880, "CredentialsFetchDuration": 138 } ``` 的 [API 文件](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html)`EmfMetricLoggingPublisher.Builder`會顯示您可以使用的組態選項。您也可以為單一請求啟用 EMF 指標記錄，如 [ CloudWatchMetricPublisher 所示](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request)。 **後續步驟：**如需長時間執行的應用程式，請參閱[從長時間執行的應用程式發佈 SDK 指標](metric-pub-impl-cwmp.md)，以進行 CloudWatch 型指標發佈。 # 使用將 SDK 指標輸出至主控台 AWS SDK for Java 2.x `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` 實作會將指標直接輸出至應用程式的主控台或日誌檔案。此方法非常適合用於開發、偵錯和了解 SDK 收集哪些指標，而不需要 Amazon CloudWatch 等外部服務。與 `CloudWatchMetricPublisher`和不同`EmfMetricLoggingPublisher`， `LoggingMetricPublisher`提供即時輸出，沒有延遲或外部相依性。這使得它非常適合本機開發和故障診斷案例。 ## 何時使用 LoggingMetricPublisher 當您需要以下功能時，可使用 `LoggingMetricPublisher`： + 在開發期間偵錯指標集合 + 了解 SDK 為您的操作收集哪些指標 + 在本機對效能問題進行故障診斷 + 沒有外部服務相依性的測試指標集合 + 立即在主控台或日誌檔案中檢視指標 **注意** `LoggingMetricPublisher` 不建議用於需要持久性指標儲存和分析功能的生產環境。 ## 設定指標的主控台記錄若要查看`LoggingMetricPublisher`輸出，請將您的記錄架構設定為顯示`INFO`關卡訊息。下列`log4j2.xml`組態可確保指標出現在主控台中： ``` ``` 此組態會指示 SDK 在 `INFO`層級將指標輸出到您的主控台。`LoggingMetricPublisher` 記錄器組態可確保即使您的根記錄器使用更高層級的 `WARN`或，指標輸出也會出現`ERROR`。 ## 啟用服務用戶端的主控台指標下列範例示範如何建立 `LoggingMetricPublisher`，並將其與 Amazon Simple Storage Service 用戶端搭配使用： ``` import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; // Create a LoggingMetricPublisher with default settings. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Add the publisher to your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build(); // Make requests - metrics will appear in your console. s3Client.listBuckets(); // Clean up resources. metricPublisher.close(); s3Client.close(); ``` ## 選擇指標輸出格式 `LoggingMetricPublisher` 支援兩種輸出格式： + **PLAIN 格式（預設）：**將指標輸出為精簡的單行項目 + **PRETTY 格式：**以多行、人類可讀的格式輸出指標下列範例示範如何使用 PRETTY 格式，以便在開發期間更輕鬆地閱讀： ``` import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; // Create a LoggingMetricPublisher with PRETTY format. MetricPublisher prettyMetricPublisher = LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY ); // Use with your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(prettyMetricPublisher)) .build(); ``` ## 完成範例下列範例`LoggingMetricPublisher`示範以兩種方式使用： + 在服務用戶端層級 + 對於單一請求 ``` import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListBucketsRequest; import software.amazon.awssdk.services.s3.model.ListBucketsResponse; /** * Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x. *

* This demo focuses on the S3 listBuckets operation to show how metrics are collected * and logged to the console for development and debugging purposes. *

* LoggingMetricPublisher is ideal for: * - Development and debugging * - Console output for troubleshooting * - Understanding what metrics are being collected * - Testing metric collection without external dependencies */ public class S3LoggingMetricPublisherDemo { private static final Logger logger = LoggerFactory.getLogger(S3LoggingMetricPublisherDemo.class); public static void main(String[] args) { S3LoggingMetricPublisherDemo demo = new S3LoggingMetricPublisherDemo(); demo.demonstrateUsage(); } /** * Demonstrates basic usage with S3Client and metrics enabled at the client level. */ private void demonstrateUsage() { // Create a LoggingMetricPublisher with default settings. The SDK logs metrics as text in a single line. // The default settings are equivalent to using `LoggingMetricPublisher.Format.PLAIN`. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Create an S3 client with metrics enabled. try (S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build()) { // Make the listBuckets request - metrics will be logged to console. ListBucketsResponse response = s3Client.listBuckets(ListBucketsRequest.builder().build()); // The next block shows the using a different LoggingMetricPublisher with a `PRETTY` format. // Since the metric publisher is added to the request using the `overrideConfiguration`, this formatting // applies only to the one request. try { s3Client.listBuckets(ListBucketsRequest.builder() .overrideConfiguration(config -> config .addMetricPublisher(LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY))) .build()); } catch (Exception e) { logger.info("Request failed with metrics logged: {}", e.getMessage()); } logger.info("Found {} buckets in your AWS account.", response.buckets().size()); } catch (Exception e) { logger.error("Error during S3 operation: {}", e.getMessage()); logger.info("Note: This is expected if AWS credentials are not configured."); } // Close the metric publisher to flush any remaining metrics. metricPublisher.close(); } } ``` 程式碼會將下列項目記錄到主控台： ``` INFO LoggingMetricPublisher - Metrics published: MetricCollection(name=ApiCall, metrics=[MetricRecord(metric=MarshallingDuration, value=PT0.005409792S), MetricRecord(metric=RetryCount, value=0), MetricRecord(metric=ApiCallSuccessful, value=true), MetricRecord(metric=OperationName, value=ListBuckets), MetricRecord(metric=EndpointResolveDuration, value=PT0.000068S), MetricRecord(metric=ApiCallDuration, value=PT0.163802958S), MetricRecord(metric=CredentialsFetchDuration, value=PT0.145686542S), MetricRecord(metric=ServiceEndpoint, value=https://s3.amazonaws.com), MetricRecord(metric=ServiceId, value=S3)], children=[MetricCollection(name=ApiCallAttempt, metrics=[MetricRecord(metric=TimeToFirstByte, value=PT0.138816S), MetricRecord(metric=SigningDuration, value=PT0.007803459S), MetricRecord(metric=ReadThroughput, value=165153.96002660287), MetricRecord(metric=ServiceCallDuration, value=PT0.138816S), MetricRecord(metric=AwsExtendedRequestId, value=e13Swj3uwn0qP1Oz+m7II5OGq7jf8xxT8H18iDfRBCQmDg+gU4ek91Xrsl8XxRLROlIzCAPQtsQF0DAAWOb8ntuKCzX2AJdj), MetricRecord(metric=HttpStatusCode, value=200), MetricRecord(metric=BackoffDelayDuration, value=PT0S), MetricRecord(metric=TimeToLastByte, value=PT0.148915667S), MetricRecord(metric=AwsRequestId, value=78AW9BM7SWR6YMGB)], children=[MetricCollection(name=HttpClient, metrics=[MetricRecord(metric=MaxConcurrency, value=50), MetricRecord(metric=AvailableConcurrency, value=0), MetricRecord(metric=LeasedConcurrency, value=1), MetricRecord(metric=ConcurrencyAcquireDuration, value=PT0.002623S), MetricRecord(metric=PendingConcurrencyAcquires, value=0), MetricRecord(metric=HttpClientName, value=Apache)], children=[])])]) INFO LoggingMetricPublisher - [4e6f2bb5] ApiCall INFO LoggingMetricPublisher - [4e6f2bb5] ┌──────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MarshallingDuration=PT0.000063S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ RetryCount=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallSuccessful=true │ INFO LoggingMetricPublisher - [4e6f2bb5] │ OperationName=ListBuckets │ INFO LoggingMetricPublisher - [4e6f2bb5] │ EndpointResolveDuration=PT0.000024375S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallDuration=PT0.018463083S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ CredentialsFetchDuration=PT0.000022334S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceEndpoint=https://s3.amazonaws.com │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceId=S3 │ INFO LoggingMetricPublisher - [4e6f2bb5] └──────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] ApiCallAttempt INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToFirstByte=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ SigningDuration=PT0.000301125S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ReadThroughput=1195591.792850103 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceCallDuration=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsExtendedRequestId=3QI1eenRuokdszWqZBmBMDUmko6FlSmHkM+CUMNMeLor7gJml4D4lv6QXUZ1zWoTgG+tHbr6yo2vHdz4h1P8PDovvtMFRCeB │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpStatusCode=200 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ BackoffDelayDuration=PT0S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToLastByte=PT0.017952625S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsRequestId=78AVFAF795AAWAXH │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] HttpClient INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MaxConcurrency=50 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AvailableConcurrency=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ LeasedConcurrency=1 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ConcurrencyAcquireDuration=PT0.00004S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ PendingConcurrencyAcquires=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpClientName=Apache │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────┘ INFO S3LoggingMetricPublisherDemo - Found 6 buckets in your AWS account. ``` ### 範例的其他成品 Maven `pom.xml` 檔案 ``` 4.0.0 com.example s3-logging-metric-publisher-demo 1.0.0 jar AWS S3 LoggingMetricPublisher Demo Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x 17 17 UTF-8 2.31.66 2.24.3 software.amazon.awssdk bom ${aws.java.sdk.version} pom import org.apache.logging.log4j log4j-bom ${log4j.version} pom import software.amazon.awssdk s3 org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-core org.apache.maven.plugins maven-compiler-plugin 3.13.0 17 17 ``` `Log4j2.xml` 組態檔案 ``` ``` 這些指標包括時間資訊、服務詳細資訊、操作名稱和 HTTP 狀態碼，可協助您了解應用程式的 AWS API 使用模式。 ## 後續步驟使用 `LoggingMetricPublisher`進行開發和偵錯之後，請考慮生產環境的下列選項： + 對於長時間執行的應用程式，請使用 [CloudWatchMetricPublisher](metric-pub-impl-cwmp.md) 將指標傳送至 Amazon CloudWatch 進行分析和提醒 + 對於 AWS Lambda 函數，使用 [EmfMetricLoggingPublisher](metric-pub-impl-emf.md) 以 CloudWatch Embedded Metric Format 發佈指標 # AWS SDK for Java 2.x：綜合指標參考使用 AWS SDK for Java 2.x，您可以從應用程式中的服務用戶端收集指標，然後將這些指標發佈（輸出）至 [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)。這些資料表列出您可以收集的指標，以及任何 HTTP 用戶端用量需求。如需啟用和設定 SDK 指標的詳細資訊，請參閱[啟用 SDK 指標](metrics.md)。 ## 每個請求收集的指標 | 指標名稱 | 說明 | Type | | --- | --- | --- | | ApiCallDuration | API 呼叫的持續時間。這包括所有進行的呼叫嘗試。 | 持續時間\$1 | | ApiCallSuccessful | 如果 API 呼叫成功，則為 True，否則為 false。 | Boolean | | CredentialsFetchDuration | 擷取 API 呼叫簽署憑證的持續時間。 | 持續時間\$1 | | EndpointResolveDuration | 解析 API 呼叫所用端點的持續時間。 | 持續時間\$1 | | MarshallingDuration | 將 SDK 請求封送至 HTTP 請求的持續時間。 | 持續時間\$1 | | OperationName | 要叫用之服務操作的名稱。 | String | | RetryCount | 開發套件在執行請求時執行的重試次數。0 表示請求第一次運作，而且未嘗試任何重試。如需設定重試行為的詳細資訊，請參閱 [重試策略](retry-strategy.md#retry-strategies)。 | Integer | | ServiceId | 服務的唯一 ID。 | String | | ServiceEndpoint | 服務的端點。 | URI | | TokenFetchDuration | 擷取 API 呼叫簽署憑證的持續時間。 | 持續時間\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)。 ## 每次請求嘗試收集的指標在收到回應之前，每個 API 呼叫可能需要多次嘗試。每次嘗試都會收集這些指標。 ### 核心指標 | 指標名稱 | 說明 | Type | | --- | --- | --- | | AwsExtendedRequestId | 服務請求的延伸請求 ID。 | String | | AwsRequestId | 服務請求的請求 ID。 | String | | BackoffDelayDuration | 開發套件在此 API 呼叫嘗試之前等待的持續時間。此值是以用戶端上的 `[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)` 集為基礎。如需詳細資訊，請參閱本指南中的[重試策略](retry-strategy.md#retry-strategies)一節。 | 持續時間\$1 | | ErrorType | 呼叫嘗試發生的錯誤類型。以下是可能的值： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/metrics-list.html) | String | | ReadThroughput | 用戶端的讀取輸送量，定義為 `NumberOfResponseBytesRead / (TTLB - TTFB)`。此值以每秒位元組為單位。請注意，此指標只會測量從 `ResponseTransformer`或中讀取的位元組`AsyncResponseTransformer`。在轉換器外部讀取的資料，例如回應串流因轉換器而傳回時，不會包含在計算中。 | Double | | WriteThroughput | 用戶端的寫入輸送量，定義為 `RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)`。此值以每秒位元組為單位。此指標會測量 SDK 向 HTTP 用戶端提供請求內文的速率。它不包括連線設定、TLS 交握時間和伺服器處理時間。只有具有串流內文的請求，例如 S3 PutObject，才會報告此指標。請注意，此指標不會考慮 HTTP 用戶端層中的緩衝。如果 HTTP 用戶端在傳送之前緩衝資料，實際的網路傳輸速率可能會較低。此指標代表網路輸送量的上限。 | Double | | ServiceCallDuration | 連線到服務（或從連線集區取得連線）、傳送序列化請求和接收初始回應（例如 HTTP 狀態碼和標頭）的持續時間。這不包括從服務讀取整個回應的時間。 | 持續時間\$1 | | SigningDuration | 簽署 HTTP 請求的持續時間。 | 持續時間\$1 | | TimeToFirstByte | 從傳送 HTTP 請求（包括取得連線）到服務，以及接收回應中第一個位元組標頭的持續時間。 | 持續時間\$1 | | TimeToLastByte | 從傳送 HTTP 請求（包括取得連線）到服務，以及接收回應最後一個位元組的持續時間。請注意，對於傳回串流回應APIs，此指標會跨越 `ResponseTransformer`或 `AsyncResponseTransformer`完成之前的時間。 | 持續時間\$1 | | UnmarshallingDuration | 取消封送 HTTP 回應至 SDK 回應的持續時間。注意：對於串流操作，這不包括讀取回應承載的時間。 | 持續時間\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)。 ### HTTP 指標 | 指標名稱 | 說明 | Type | 需要 HTTP 用戶端\$1 | | --- | --- | --- | --- | | AvailableConcurrency | HTTP 用戶端支援的額外並行請求數量，無需建立與目標伺服器的新連線。對於 HTTP/1 操作，這等於使用服務建立的閒置 TCP 連線數。對於 HTTP/2 操作，這等於閒置串流的數量。注意：此值因 HTTP 用戶端實作而異： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/metrics-list.html) 此值的範圍為個別 HTTP 用戶端執行個體，並排除來自相同 JVM 中其他 HTTP 用戶端的並行。 | Integer | Apache、Netty、CRT | | ConcurrencyAcquireDuration | 從連線集區取得頻道的持續時間。對於 HTTP/1 操作，頻道等於 TCP 連線。對於 HTTP/2 操作，頻道等於 HTTP/2 串流頻道。取得新頻道可能包括下列時間： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/metrics-list.html) | 持續時間\$1 | Apache、Netty、CRT | | HttpClientName | 用於請求的 HTTP 名稱。 | String | Apache、Netty、CRT | | HttpStatusCode | HTTP 回應的狀態碼。 | Integer | 任何 | | LeasedConcurrency | HTTP 用戶端目前執行的請求數量。對於 HTTP/1 操作，這等於與服務的作用中 TCP 連線數（閒置連線除外）。對於 HTTP/2 操作，這等於服務作用中 HTTP 串流的數量（閒置串流容量除外）。注意：此值因 HTTP 用戶端實作而異： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/metrics-list.html) 此值的範圍為個別 HTTP 用戶端執行個體，並排除來自相同 JVM 中其他 HTTP 用戶端的並行。 | Integer | Apache、Netty、CRT | | LocalStreamWindowSize | 執行此請求之串流的本機 HTTP/2 視窗大小，以位元組為單位。 | Integer | Netty | | MaxConcurrency | HTTP 用戶端支援的並行請求數目上限。對於 HTTP/1 操作，這等於 HTTP 用戶端可以集區的最大 TCP 連線數。對於 HTTP/2 操作，這等於 HTTP 用戶端可以集區的最大串流數量。注意：此值因 HTTP 用戶端實作而異： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/metrics-list.html) 此值的範圍為個別 HTTP 用戶端執行個體，並排除來自相同 JVM 中其他 HTTP 用戶端的並行。 | Integer | Apache、Netty、CRT | | PendingConcurrencyAcquires | 等待來自 HTTP 用戶端並行的請求數量。對於 HTTP/1 操作，這等於等待 TCP 連線從連線集區建立或傳回的請求數目。對於 HTTP/2 操作，這等於從連線集區等待新串流（可能為新的 HTTP/2 連線）的請求數量。注意：此值因 HTTP 用戶端實作而異： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/metrics-list.html) 此值的範圍為個別 HTTP 用戶端執行個體，並排除來自相同 JVM 中其他 HTTP 用戶端的並行。 | Integer | Apache、Netty、CRT | | RemoteStreamWindowSize | 執行此請求之串流的遠端 HTTP/2 視窗大小，以位元組為單位。 | Integer | Netty | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)。資料欄中使用的術語表示： + Apache：以 Apache 為基礎的 HTTP 用戶端 (`[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)`) + Netty：以 Netty 為基礎的 HTTP 用戶端 (`[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)`) + CRT：以 AWS CRT 為基礎的 HTTP 用戶端 (`[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)`) + 任何：指標資料的集合不依賴於 HTTP 用戶端；這包括 URLConnection 型 HTTP 用戶端 (`[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`) # 監控 AWS SDK for Java 2.x 應用程式監控是使用維護應用程式可靠性、可用性和效能的重要部分 AWS SDK for Java 2.x。 AWS 提供下列監控工具來監看適用於 Java 的 SDK 2.x、在發生錯誤時回報，並適時採取自動動作： + *Amazon CloudWatch* AWS 會即時監控您的 AWS 資源和您在上執行的應用程式。您可以收集和追蹤指標、建立自訂儀板表，以及設定警示，在特定指標達到您指定的閾值時通知您或採取動作。例如，您可以讓 CloudWatch 追蹤 CPU 使用量或其他 Amazon EC2 執行個體指標，並在需要時自動啟動新的執行個體。如需詳細資訊，請參閱 [Amazon CloudWatch 使用者指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)。 + *Amazon CloudWatch Logs* 可讓您監控、存放和存取來自 Amazon EC2 執行個體、CloudTrail 及其他來源的日誌檔案。CloudWatch Logs 可監控日誌檔案中的資訊，並在達到特定閾值時通知您。您也可以將日誌資料存檔在高耐用性的儲存空間。如需詳細資訊，請參閱 [Amazon CloudWatch Logs 使用者指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)。 + *AWS CloudTrail* 會擷取您 AWS 帳戶或代表您的帳戶發出的 API 呼叫和相關事件，並將日誌檔案交付至您指定的 Amazon S3 儲存貯體。您可以識別呼叫的使用者和帳戶 AWS、進行呼叫的來源 IP 地址，以及呼叫的時間。如需詳細資訊，請參閱「[AWS CloudTrail 使用者指南](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)」。 # 使用適用於 Java 的 SDK 2.x 進行記錄 AWS SDK for Java 2.x 使用 [SLF4J](https://www.slf4j.org/manual.html)，這是一種抽象層，可在執行時間使用多個記錄系統中的任何一個。支援的記錄系統包括 Java Logging Framework 和 Apache[ Log4j 2](https://logging.apache.org/log4j/2.x/) 等。本主題說明如何使用 Log4j 2 做為使用 SDK 的記錄系統。 ## Log4j 2 組態檔案您通常會使用名為`log4j2.xml` Log4j 2 的組態檔案。範例組態檔案如下所示。若要進一步了解組態檔案中使用的值，請參閱 [Log4j 組態手冊](https://logging.apache.org/log4j/2.x/manual/configuration.html)。當您的應用程式啟動時， `log4j2.xml` 檔案必須位於 classpath 上。對於 Maven 專案，請將檔案放在 `/src/main/resources`目錄中。 `log4j2.xml` 組態檔案會指定[記錄層級](https://logging.apache.org/log4j/2.x/manual/configuration.html#Loggers)、記錄輸出的傳送位置（例如[檔案或主控台](https://logging.apache.org/log4j/2.x/manual/appenders.html)) 等屬性，以及[輸出的格式](https://logging.apache.org/log4j/2.x/manual/layouts.html)。記錄層級會指定 Log4j 2 輸出的詳細資訊層級。Log4j 2 支援多個記錄[https://logging.apache.org/log4j/2.x/manual/architecture.html#](https://logging.apache.org/log4j/2.x/manual/architecture.html#)的概念。每個階層的記錄層級都是獨立設定。您搭配使用的主要記錄階層 AWS SDK for Java 2.x 是 `software.amazon.awssdk`。 ## 新增記錄相依性若要在建置檔案中設定 SLF4J 的 Log4j 2 繫結，請使用下列命令。 ------ #### [ Maven ] 將下列元素新增至您的 `pom.xml` 檔案。 ``` ... org.apache.logging.log4j log4j-slf4j2-impl VERSION ... ``` ------ #### [ Gradle–Kotlin DSL ] 將下列項目新增至您的 `build.gradle.kts` 檔案。 ``` ... dependencies { ... implementation("org.apache.logging.log4j:log4j-slf4j2-impl:VERSION") ... } ... ``` ------ 使用 `2.20.0`做為`log4j-slf4j2-impl`成品的最低版本。針對最新版本，請使用發佈至 [Maven central](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-slf4j2-impl) 的版本。以您將使用的版本取代 *VERSION*。 ## SDK 特定的錯誤和警告我們建議您一律將 "software.amazon.awssdk" 記錄器階層設定為 "WARN"，以從開發套件的用戶端程式庫擷取任何重要訊息。例如，如果 Amazon S3 用戶端偵測到您的應用程式未正確關閉 `InputStream`並可能洩漏資源，S3 用戶端會透過警告訊息向日誌回報。這也可確保在用戶端處理請求或回應發生任何問題時，會記錄訊息。下列`log4j2.xml`檔案會將 `rootLogger`設定為「WARN」，這會導致來自應用程式中的所有記錄器的警告和錯誤層級訊息輸出，*包括*「software.amazon.awssdk」階層中的訊息。或者，如果``使用，您可以明確將 "software.amazon.awssdk" 記錄器階層設定為 "WARN"。 **Log4j2.xml 組態檔案範例** 此組態會將「ERROR」和「WARN」層級的訊息記錄到所有記錄器階層的主控台。 ``` ``` ## 請求/回應摘要記錄如果您遇到如何處理 AWS 請求的問題，的每個請求都會 AWS 服務產生唯一的 AWS 服務請求 ID。 AWS 對於任何失敗的服務呼叫，請求 IDs 可以透過 SDK 中的[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId())物件以程式設計方式存取，也可以透過「software.amazon.awssdk.request」記錄器的「DEBUG」日誌層級進行報告。下列`log4j2.xml`檔案會啟用請求和回應的摘要。 ``` ``` 以下為日誌輸出的範例： ``` 2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=POST, protocol=https, host=dynamodb.us-east-1.amazonaws.com, encodedPath=/, headers=[amz-sdk-invocation-id, Content-Length, Content-Type, User-Agent, X-Amz-Target], queryParameters=[]) 2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Received successful response: 200, Request ID: QS9DUMME2NHEDH8TGT9N5V53OJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended Request ID: not available ``` 如果您只對請求 ID 感興趣，請使用 ``。 ## 偵錯層級 SDK 記錄如果您需要 SDK 正在執行之作業的詳細資訊，您可以將`software.amazon.awssdk`記錄器的記錄層級設定為 `DEBUG`。在此層級，軟體開發套件會輸出大量詳細資訊，因此我們建議您將此層級設定為使用整合測試來解決錯誤。在此記錄層級，軟體開發套件會記錄有關組態、憑證解析、執行攔截器、高階 TLS 活動、請求簽署等資訊。以下是 SDK 在 `DEBUG` 層級針對`S3Client#listBuckets()`呼叫所輸出的陳述式範例。 ``` DEBUG s.a.a.r.p.AwsRegionProviderChain:57 - Unable to load region from software.amazon.awssdk.regions.providers.SystemSettingsRegionProvider@324dcd31:Unable to load region from system settings. Region must be specified either via environment variable (AWS_REGION) or system property (aws.region). DEBUG s.a.a.c.i.h.l.ClasspathSdkHttpServiceProvider:85 - The HTTP implementation loaded is software.amazon.awssdk.http.apache.ApacheSdkHttpService@a23a01d DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@69b2f8e5, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@6331250e, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@a10c1b5, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@644abb8f, software.amazon.awssdk.services.s3.auth.scheme.internal.S3AuthSchemeInterceptor@1a411233, software.amazon.awssdk.services.s3.endpoints.internal.S3ResolveEndpointInterceptor@70325d20, software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa, software.amazon.awssdk.services.s3.internal.handlers.StreamingRequestInterceptor@4d847d32, software.amazon.awssdk.services.s3.internal.handlers.CreateBucketInterceptor@5f462e3b, software.amazon.awssdk.services.s3.internal.handlers.CreateMultipartUploadRequestInterceptor@3d7fa3ae, software.amazon.awssdk.services.s3.internal.handlers.DecodeUrlEncodedResponseInterceptor@58065f0c, software.amazon.awssdk.services.s3.internal.handlers.GetBucketPolicyInterceptor@3605c4d3, software.amazon.awssdk.services.s3.internal.handlers.S3ExpressChecksumInterceptor@585c13de, software.amazon.awssdk.services.s3.internal.handlers.AsyncChecksumValidationInterceptor@187eb9a8, software.amazon.awssdk.services.s3.internal.handlers.SyncChecksumValidationInterceptor@726a6b94, software.amazon.awssdk.services.s3.internal.handlers.EnableTrailingChecksumInterceptor@6ad11a56, software.amazon.awssdk.services.s3.internal.handlers.ExceptionTranslationInterceptor@522b2631, software.amazon.awssdk.services.s3.internal.handlers.GetObjectInterceptor@3ff57625, software.amazon.awssdk.services.s3.internal.handlers.CopySourceInterceptor@1ee29c84, software.amazon.awssdk.services.s3.internal.handlers.ObjectMetadataInterceptor@7c8326a4] DEBUG s.a.a.u.c.CachedSupplier:85 - (SsoOidcTokenProvider()) Cached value is stale and will be refreshed. ... DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@51351f28, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@21618fa7, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@15f2eda3, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@34cf294c, software.amazon.awssdk.services.sso.auth.scheme.internal.SsoAuthSchemeInterceptor@4d7aaca2, software.amazon.awssdk.services.sso.endpoints.internal.SsoResolveEndpointInterceptor@604b1e1d, software.amazon.awssdk.services.sso.endpoints.internal.SsoRequestSetEndpointInterceptor@62566842] ... DEBUG s.a.a.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=GET, protocol=https, host=portal.sso.us-east-1.amazonaws.com, encodedPath=/federation/credentials, headers=[amz-sdk-invocation-id, User-Agent, x-amz-sso_bearer_token], queryParameters=[role_name, account_id]) DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: smithy.api#noAuth DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to portal.sso.us-east-1.amazonaws.com/18.235.195.183:443 with timeout 2000 ... DEBUG s.a.a.requestId:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available DEBUG s.a.a.request:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available DEBUG s.a.a.u.c.CachedSupplier:85 - (software.amazon.awssdk.services.sso.auth.SsoCredentialsProvider@b965857) Successfully refreshed cached value. Next Prefetch Time: 2024-04-25T22:03:10.097Z. Next Stale Time: 2024-04-25T22:05:30Z DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Interceptor 'software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa' modified the message with its modifyHttpRequest method. ... DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: aws.auth#sigv4 ... DEBUG s.a.a.a.s.Aws4Signer:85 - AWS4 Canonical Request: GET ... DEBUG s.a.a.h.a.a.i.s.DefaultV4RequestSigner:85 - AWS4 String to sign: AWS4-HMAC-SHA256 20240425T210631Z 20240425/us-east-1/s3/aws4_request aafb7784627fa7a49584256cb746279751c48c2076f813259ef767ecce304d64 DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to s3.us-east-1.amazonaws.com/52.217.41.86:443 with timeout 2000 ... ``` 下列`log4j2.xml`檔案會設定先前的輸出。 ``` ``` ## 啟用線路記錄查看適用於 Java 的 SDK 2.x 傳送和接收的確切請求和回應會很有用。如果您需要存取此資訊，您可以根據服務用戶端使用的 HTTP 用戶端新增必要的組態來暫時啟用它。根據預設，同步服務用戶端，例如 [S3Client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html)，使用基礎 Apache HttpClient，以及非同步服務用戶端，例如 [S3AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html)，使用 Netty 非封鎖 HTTP 用戶端。以下是您可以用於兩種服務用戶端類別的 HTTP 用戶端明細： | 同步 HTTP 用戶端 | 非同步 HTTP 用戶端 | | --- | --- | | [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) （預設） | [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) （預設） | | [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) | [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html) | | [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) | | | [Apache5HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) | 如需根據基礎 HTTP 用戶端新增的組態設定，請參閱以下適當的索引標籤。 **警告** 建議您只將連線記錄用於偵錯用途。請在您的生產環境停用此功能，因為它可能記錄敏感資料。它會記錄完整的請求或回應而不加密，即使對於 HTTPS 呼叫亦同。對於大型請求（例如將檔案上傳到其中 Amazon S3) 或回應，詳細的線路記錄也會大幅影響應用程式的效能。 ------ #### [ ApacheHttpClient ] 將 "org.apache.http.wire" 記錄器新增至`log4j2.xml`組態檔案，並將關卡設定為 "DEBUG"。下列`log4j2.xml`檔案會開啟 Apache HttpClient 的完整線路記錄。 ``` ``` 使用 Apache 進行線路記錄時，需要額外對`log4j-1.2-api`成品的 Maven 相依性，因為它使用 1.2。下列建置檔案程式碼片段會顯示 log4j 2 的完整 Maven 相依性集，包括 Apache HTTP 用戶端的線路記錄。 **Maven** ``` ... ... org.apache.logging.log4j log4j-bom VERSION pom import ... org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-1.2-api ... ``` **Gradle–Kotlin DSL** ``` ... dependencies { ... implementation(platform("org.apache.logging.log4j:log4j-bom:VERSION")) implementation("org.apache.logging.log4j:log4j-slf4j2-impl") implementation("org.apache.logging.log4j:log4j-1.2-api") } ... ``` 使用 `2.20.0`做為`log4j-bom`成品的最低版本。針對最新版本，請使用發佈至 [Maven central](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-bom) 的版本。以您將使用的版本取代 *VERSION*。 ------ #### [ Apache5HttpClient ] 將 "org.apache.hc.client5.http.wire" 記錄器新增至`log4j2.xml`組態檔案，並將關卡設定為 "DEBUG"。下列`log4j2.xml`檔案會開啟 Apache5 HttpClient 的完整線路記錄。 ``` ``` ------ #### [ UrlConnectionHttpClient ] 若要記錄使用之服務用戶端的詳細資訊`UrlConnectionHttpClient`，請先建立具有下列內容`logging.properties`的檔案： ``` handlers=java.util.logging.ConsoleHandler java.util.logging.ConsoleHandler.level=FINEST sun.net.www.protocol.http.HttpURLConnection.level=ALL ``` 使用的完整路徑設定下列 JVM 系統屬性`logging.properties`： ``` -Djava.util.logging.config.file=/full/path/to/logging.properties ``` 此組態只會記錄請求和回應的標頭，例如： ``` FINE: sun.net.www.MessageHeader@35a9782c11 pairs: {GET /fileuploadtest HTTP/1.1: null}{amz-sdk-invocation-id: 5f7e707e-4ac5-bef5-ba62-00d71034ffdc}{amz-sdk-request: attempt=1; max=4}{Authorization: AWS4-HMAC-SHA256 Credential=/20220927/us-east-1/s3/aws4_request, SignedHeaders=amz-sdk-invocation-id;amz-sdk-request;host;x-amz-content-sha256;x-amz-date;x-amz-te, Signature=e367fa0bc217a6a65675bb743e1280cf12fbe8d566196a816d948fdf0b42ca1a}{User-Agent: aws-sdk-java/2.17.230 Mac_OS_X/12.5 OpenJDK_64-Bit_Server_VM/25.332-b08 Java/1.8.0_332 vendor/Amazon.com_Inc. io/sync http/UrlConnection cfg/retry-mode/legacy}{x-amz-content-sha256: UNSIGNED-PAYLOAD}{X-Amz-Date: 20220927T133955Z}{x-amz-te: append-md5}{Host: tkhill-test1.s3.amazonaws.com}{Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2}{Connection: keep-alive} FINE: sun.net.www.MessageHeader@70a36a6611 pairs: {null: HTTP/1.1 200 OK}{x-amz-id-2: sAFeZDOKdUMsBbkdjyDZw7P0oocb4C9KbiuzfJ6TWKQsGXHM/dFuOvr2tUb7Y1wEHGdJ3DSIxq0=}{x-amz-request-id: P9QW9SMZ97FKZ9X7}{Date: Tue, 27 Sep 2022 13:39:57 GMT}{Last-Modified: Tue, 13 Sep 2022 14:38:12 GMT}{ETag: "2cbe5ad4a064cedec33b452bebf48032"}{x-amz-transfer-encoding: append-md5}{Accept-Ranges: bytes}{Content-Type: text/plain}{Server: AmazonS3}{Content-Length: 67} ``` 若要查看請求/回應內文，請將 `-Djavax.net.debug=all`新增至 JVM 屬性。這個額外的屬性會記錄大量資訊，包括所有 SSL 資訊。在日誌主控台或日誌檔案中，搜尋 `"GET"`或 `"POST"` 以快速移至包含實際請求和回應的日誌區段。搜尋`"Plaintext before ENCRYPTION"`請求和`"Plaintext after DECRYPTION"`回應，以查看標頭和內文的完整文字。 ------ #### [ NettyNioAsyncHttpClient ] 如果您的非同步服務用戶端使用預設 `NettyNioAsyncHttpClient`，請將兩個額外的記錄器新增至您的 `log4j2.xml` 檔案，以記錄 HTTP 標頭和請求/回應內文。 ``` ``` 以下是完整的`log4j2.xml`範例： ``` ``` 這些設定會記錄所有標頭詳細資訊和請求/回應內文。 ------ #### [ AwsCrtAsyncHttpClient/AwsCrtHttpClient ] 如果您已將服務用戶端設定為使用 CRT 型 HTTP 用戶端的 AWS 執行個體，您可以透過設定 JVM 系統屬性或以程式設計方式記錄詳細資訊。 | | | --- | | Log to a file at "Debug" level | | 使用系統屬性：

-Daws.crt.log.level=Trace 
-Daws.crt.log.destination=File 
-Daws.crt.log.filename=

| 以程式設計方式：

import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK service client.
Log.initLoggingToFile(Log.LogLevel.Trace, "");

| | Log to the console at "Debug" level | | 使用系統屬性：

-Daws.crt.log.level=Trace 
-Daws.crt.log.destination=Stdout

| 以程式設計方式：

import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK service client.
Log.initLoggingToStdout(Log.LogLevel.Trace);

| 基於安全考量，在「追蹤」層級，以 AWS CRT 為基礎的 HTTP 用戶端只會記錄回應標頭。不會記錄請求標頭、請求內文和回應內文。 ------