翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # でのオブザーバビリティ機能の設定 AWS SDK for Java 2.x テレメトリは、リモートソースから自動的に収集および送信されるデータのコレクションであり、テレメトリを使用してシステムの動作をモニタリングおよび分析できます。 SDK for Java 2.x のオブザーバビリティにより、開発者は、リクエストのライフサイクル全体をキャプチャする豊富なテレメトリデータ AWS のサービス を通じて、Java アプリケーションが とやり取りする方法を包括的に把握できます。これらの機能により、メトリクス、ログ、トレースなどのテレメトリシグナルを収集、分析、視覚化し、リクエストパターンのモニタリング、ボトルネックの特定、アプリケーション 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(); ``` ## CRT AWS ベースの 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)、メトリクスパブリッシャーを設定するメソッドを提供しません。 ## メトリクスが利用可能になるまでの時間 メトリクスは通常、SDK for Java によって発行されてから 5 ～ 10 分以内に利用可能になります。正確で最新のメトリクスを利用するには、Java アプリケーションからメトリクスが発行されてから 10 分以上経過後、Cloudwatch を確認してください。 ## 収集される情報 メトリクスの収集には、次のものが含まれます。 + API リクエストの数 (成功したか、失敗したかを含む) + 返される例外など、API リクエストで AWS のサービス 呼び出す に関する情報 + Marshalling、Signing、HTTP リクエストなどのさまざまな操作の期間 + 開いている接続の数、保留中のリクエストの数、使用されている HTTP クライアントの名前などの HTTP クライアントのメトリクス **注記** 使用可能なメトリクスは、HTTP クライアントによって異なります。 詳細なリストについては、[サービスクライアントのメトリクス](metrics-list.md)を参照してください。 ## この情報の使用方法 SDK が収集するメトリクスを使用して、アプリケーションのサービスクライアントをモニタリングできます。全体的な使用傾向の確認や、異常の特定ができるほか、返されたサービスクライアントの例外を確認したり、特定の問題を理解するために詳しく確認したりすることもできます。Amazon CloudWatch Logs を使用して、定義した条件にアプリケーションが達するとすぐに通知するアラームを作成することもできます。 詳細については、「[Amazon CloudWatch ユーザーガイド](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)」の「[Amazon CloudWatch メトリクスの使用](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)」と「[Amazon CloudWatch Logs アラームの使用](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: 必要な依存関係を追加する AWS SDK for Javaのバージョン `2.14.0` 以降を使用するように、プロジェクトの依存関係を (例: `pom.xml` または `build.gradle` ファイルで) 設定します。 `cloudwatch-metric-publisher`プロジェクトの依存関係にバージョン番号 `2.14.0` 以降の artifactId を含めます。 例えば、次のようになります。 ``` 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 ID に対して `cloudwatch:PutMetricData` のアクセス許可を有効にし、SDK for Java がメトリクスを書き込めるようにします。 ## 特定のリクエストのメトリクスを有効にする 次のクラスは、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(); } } ``` **重要** サービスクライアントが使用されなくなったときに、アプリケーションが `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` インスタンス`close` を呼び出すことを確認します。呼び出さない場合、スレッドまたはファイル記述子が漏洩する可能性があります。 ## 特定のサービスクライアントのためにサマリメートリクスを有効にする 次のコードスニペットは、サービスクライアントのデフォルト設定で 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 にメトリクスをアップロードする頻度を指定できます。デフォルト値は 1 分に 1 回です。 + `maximumCallsPerUpload` メソッドは、アップロードごとに行われる呼び出しの数を制限します。デフォルトは無制限です。 + デフォルトでは、SDK for Java 2.x は `AwsSdk/JavaSdk2` 名前空間の下にメトリクスを公開します。`namespace` を使用して別の値を指定できます。 + デフォルトでは、SDK はサマリーメトリクスを公開します。概要メトリクスは、平均、最小、最大、合計、サンプル数で構成されます。`detailedMetrics` メソッドで 1 つ以上の SDK メトリクスを指定することで、SDK はメトリクスごとに追加のデータを公開します。この追加データにより、CloudWatch でクエリできる p90 や p99 などのパーセンタイル統計が有効になります。詳細なメトリクスは、DK クライアントリクエストのエンドツーエンドのレイテンシーを測定する `APICallDuration` のようなレイテンシーメトリクスに特に有益です。`[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 組み込みメトリクス形式 (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) で構造化されたログエントリとしてメトリクスをすぐに記述することで、より適切なアプローチを提供します。`EmfMetricLoggingPublisher` は、 AWS Lambda や Amazon Elastic Container Service などの Amazon CloudWatch Logs との統合が組み込まれている実行環境で動作します。 ## セットアップ `EmfMetricLoggingPublisher` を使用してメトリクスを有効にし、使用する前に、次の手順を完了する必要があります。 ### ステップ 1: 必要な依存関係を追加する AWS SDK for Javaのバージョン `2.30.3` 以降を使用するように、プロジェクトの依存関係を (例: `pom.xml` または `build.gradle` ファイルで) 設定します。 `emf-metric-logging-publisher`プロジェクトの依存関係にバージョン番号 `2.30.3` 以降の artifactId を含めます。 例えば、次のようになります。 ``` 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 ID に対して `logs:PutLogEvents` のアクセス許可を有効にし、SDK for Java が 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" } ``` 関数がイベントを処理すると、次の例のような 2 つのログイベントが表示されます。2 番目のイベントの 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 } ``` `EmfMetricLoggingPublisher.Builder` の [API ドキュメント](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html)には、使用できる設定オプションが記載されています。 [CloudWatchMetricPublisher に示すように](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request)、単一のリクエストに対して EMF メトリクスログ記録を有効にすることもできます。 **次のステップ:** 長時間実行されるアプリケーションについては、CloudWatch ベースのメトリクス公開に向けた「[長時間実行するアプリケーションから SDK メトリクスを公開する](metric-pub-impl-cwmp.md)」を参照してください。 # を使用して 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` は次の 2 つの形式をサポートしています。 + **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(); ``` ## 完全な例 次の例は、2 つの方法で `LoggingMetricPublisher` を使用する方法を示しています。 + サービスクライアントレベル + 1 つのリクエストに対して ``` 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` 設定ファイル ``` ``` メトリクスには、アプリケーションの AWS API 使用パターンを理解するのに役立つタイミング情報、サービスの詳細、オペレーション名、HTTP ステータスコードが含まれます。 ## 次の手順 開発とデバッグに `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)を参照してください。 ## 各リクエストで収集されたメトリクス | メトリクス名 | 説明 | タイプ | | --- | --- | --- | | ApiCallDuration | API コールが行われた時間。これには、試行されたすべての呼び出しが含まれます。 | 時間\$1 | | ApiCallSuccessful | API コールが成功した場合は true、それ以外の場合は false。 | ブール値 | | CredentialsFetchDuration | API コールの署名認証情報を取得するまでの時間。 | 時間\$1 | | EndpointResolveDuration | API コールに使用されるエンドポイントを解決するまでの時間。 | 時間\$1 | | MarshallingDuration | SDK リクエストを HTTP リクエストにマーシャリングするまでの時間。 | 時間\$1 | | OperationName | 呼び出されるサービスオペレーションの名前。 | String | | RetryCount | SDK がリクエストの実行中に再試行した回数。0 は、リクエストが最初に成功し、再試行されなかったことを意味します。 再試行動作の設定については、「[再試行戦略](retry-strategy.md#retry-strategies)」を参照してください。 | 整数 | | 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 コールでは、レスポンスが受信されるまでに複数回試行する必要がある場合があります。これらのメトリクスは、各試行について収集されます。 ### コアメトリクス | メトリクス名 | 説明 | タイプ | | --- | --- | --- | | AwsExtendedRequestId | サービスリクエストの拡張リクエスト ID。 | String | | AwsRequestId | サービスリクエストのリクエスト ID。 | String | | BackoffDelayDuration | この API コールが試行される前に SDK が待機した時間。値は、クライアントで設定された `[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/ja_jp/sdk-for-java/latest/developer-guide/metrics-list.html) | String | | ReadThroughput | `NumberOfResponseBytesRead / (TTLB - TTFB)` として定義されるクライアントの読み取りスループット。この値は 1 秒あたりのバイト数です。 このメトリクスは、 `ResponseTransformer` または `AsyncResponseTransformer` 内から読み取られたバイトのみを測定することに注意してください。トランスフォーマーの結果としてレスポンスストリームが返される場合など、トランスフォーマーの外部で読み取られるデータは計算に含まれません。 | Double | | WriteThroughput | クライアントの書き込みスループット。 として定義されます`RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)`。この値は 1 秒あたりのバイト数です。 このメトリクスは、SDK がリクエストボディを HTTP クライアントに提供するレートを測定します。接続設定、TLS ハンドシェイク時間、サーバー処理時間は含まれません。このメトリクスは、S3 PutObject などのストリーミング本文を持つリクエストに対してのみ報告されます。 このメトリクスは、HTTP クライアントレイヤーでのバッファリングを考慮しないことに注意してください。HTTP クライアントが送信前にデータをバッファする場合、実際のネットワーク送信レートが低下する可能性があります。このメトリクスは、ネットワークスループットの上限を表します。 | Double | | ServiceCallDuration | サービスへの接続 (または接続プールからの接続の取得）、シリアル化されたリクエストの送信、最初のレスポンス (HTTP ステータスコードやヘッダーなど) の受信にかかる時間。これには、サービスからレスポンス全体を読み取る時間は含まれません。 | 時間\$1 | | SigningDuration | HTTP リクエストに署名するまでの時間。 | 時間\$1 | | TimeToFirstByte | サービスへの HTTP リクエストの送信 (接続の取得を含む) から、レスポンス内のヘッダーの最初のバイトを受信するまでの時間。 | 時間\$1 | | TimeToLastByte | サービスへの HTTP リクエストの送信 (接続の取得を含む) から、レスポンス内の最後のバイトを受信するまでの時間。 ストリーミングレスポンスを返す API の場合、このメトリクスは `ResponseTransformer` または `AsyncResponseTransformer` が完了するまでが対象となります。 | 時間\$1 | | UnmarshallingDuration | SDK 応答に対する HTTP 応答のマーシャリングを解除するまでの時間。 注: ストリーミングオペレーションの場合、これにはレスポンスのペイロードを読み取る時間は含まれません。 | 時間\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). ### HTTP メトリクス | メトリクス名 | 説明 | タイプ | HTTP クライアントが必須です\$1 | | --- | --- | --- | --- | | AvailableConcurrency | ターゲットサーバーへの新しい接続を確立せずに HTTP クライアントがサポートできる追加の同時リクエストの数。 HTTP/1 オペレーションの場合、これはサービスで確立されたアイドル状態の TCP 接続の数に等しくなります。HTTP/2 オペレーションの場合、これはアイドルストリームの数に等しくなります。 注: この値は HTTP クライアントの実装によって異なります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/latest/developer-guide/metrics-list.html) 値は個々の HTTP クライアントインスタンスに限定され、同じ JVM 内の他の HTTP クライアントからの同時実行を除外します。 | 整数 | アパッチ、Netty、CRT | | ConcurrencyAcquireDuration | 接続プールからチャンネルを取得するまでの時間。 HTTP/1 オペレーションの場合、チャネルは TCP 接続に等しくなります。HTTP/2 オペレーションの場合、チャネルは HTTP/2 ストリームチャネルに等しくなります。 新しいチャネルの取得には、次の時間が含まれる場合があります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/latest/developer-guide/metrics-list.html) | 時間\$1 | アパッチ、Netty、CRT | | HttpClientName | リクエストに使用されている HTTP の名前。 | String | アパッチ、Netty、CRT | | HttpStatusCode | HTTP レスポンスの ステータスコード。 | 整数 | いずれか | | LeasedConcurrency | HTTP クライアントが現在実行しているリクエストの数。 HTTP/1 オペレーションの場合、これは サービスとのアクティブな TCP 接続の数 (アイドル接続を除く) に等しくなります。HTTP/2 オペレーションの場合、これはサービスに対してアクティブな HTTP ストリームの数に等しくなります (アイドルストリーム容量を除く）。 注: この値は HTTP クライアントの実装によって異なります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/latest/developer-guide/metrics-list.html) 値は個々の HTTP クライアントインスタンスに限定され、同じ JVM 内の他の HTTP クライアントからの同時実行を除外します。 | 整数 | アパッチ、Netty、CRT | | LocalStreamWindowSize | このリクエストを実行したストリームのローカル HTTP/2 ウィンドウサイズ (バイト)。 | 整数 | Netty | | MaxConcurrency | HTTP クライアントによってサポートされる同時リクエストの最大数。 HTTP/1 オペレーションの場合、これは HTTP クライアントがプールできる TCP 接続の最大数に等しくなります。HTTP/2 オペレーションの場合、これは HTTP クライアントがプールできるストリームの最大数に等しくなります。 注: この値は HTTP クライアントの実装によって異なります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/latest/developer-guide/metrics-list.html) 値は個々の HTTP クライアントインスタンスに限定され、同じ JVM 内の他の HTTP クライアントからの同時実行を除外します。 | 整数 | アパッチ、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/ja_jp/sdk-for-java/latest/developer-guide/metrics-list.html) 値は個々の HTTP クライアントインスタンスに限定され、同じ JVM 内の他の HTTP クライアントからの同時実行を除外します。 | 整数 | アパッチ、Netty、CRT | | RemoteStreamWindowSize | このリクエストを実行したストリームのリモート HTTP/2 ウィンドウサイズ (バイト) | 整数 | Netty | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). 列で使用されている用語の意味は以下のとおりです。 + 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 は、SDK for Java 2.x をモニタリングし、問題が発生したときに報告を行い、必要に応じて自動アクションを実行するために、以下のモニタリングツールを提供しています。 + *Amazon CloudWatch* は、AWS のリソースおよび AWS で実行しているアプリケーションをリアルタイムでモニタリングします。メトリクスの収集と追跡、カスタマイズしたダッシュボードの作成、および指定したメトリクスが指定したしきい値に達したときに通知またはアクションを実行するアラームの設定を行うことができます。例えば、CloudWatch で Amazon EC2 インスタンスの CPU 使用率などのメトリクスを追跡し、必要に応じて新しいインスタンスを自動的に起動できます。詳細については、「[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/)を参照してください。 # SDK for Java 2.x でのログ記録 は [SLF4J](https://www.slf4j.org/manual.html) AWS SDK for Java 2.x を使用します。これは、実行時に複数のロギングシステムのいずれかを使用できるようにする抽象化レイヤーです。 サポートされるログ記録システムには、Java ログ記録 フレームワークおよび Apache[ Log4j 2](https://logging.apache.org/log4j/2.x/) などがあります。このトピックでは、SDK を使用するためのログ記録システムとして Log4j 2 を使用する方法について説明します。 ## Log4j 2 設定ファイル 通常は `log4j2.xml` Log4j 2 という名前の設定ファイルを使用します。設定ファイルの例を次に示します。この設定ファイルで使用する値の詳細については、「[Log4j 設定のマニュアル](https://logging.apache.org/log4j/2.x/manual/configuration.html)」を参照してください。 `log4j2.xml` ファイルは、アプリケーションの起動時にクラスパス上にある必要があります。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") ... } ... ``` ------ `log4j-slf4j2-impl` アーティファクトの最小バージョンには `2.20.0` を使用します。最新バージョンには、[Maven Central](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-slf4j2-impl) に公開されているバージョンを使用します。*VERSION* は、使用するバージョンに置き換えます。 ## SDK 固有のエラーおよび警告 SDK のクライアントライブラリからの重要なメッセージを取得するために、「software.amazon.awssdk」ロガー階層は必ず「WARN」に設定しておくことをお勧めします。例えば、アプリケーションで `InputStream` が正しく閉じられなかったためにリソースが漏洩する可能性があると Amazon S3 クライアントが検出した場合、S3 クライアントは警告メッセージを使用してログに報告します。これにより、リクエストやレスポンスの処理でクライアントに問題が発生した場合、メッセージが必ずログに記録されます。 以下の `log4j2.xml` ファイルでは、`rootLogger` を「WARN」に設定しています。これにより、「software.amazon.awssdk」階層内のロガーを*含め*、アプリケーション内のすべてのロガーからの警告およびエラーレベルのメッセージが出力されます。また、`` が使用されている場合、明示的に「software.amazon.awssdk」ロガー階層を「WARN」に設定することもできます。 **Log4j2.xml 設定ファイルの例** この設定では、すべてのロガー階層の「ERROR」レベルと「WARN」レベルのメッセージがコンソールにログ記録されます。 ``` ``` ## リクエスト/応答の概要のログ記録 へのすべてのリクエストは、 AWS のサービス が AWS リクエストを処理する方法に問題がある場合に便利な一意のリクエスト ID AWS のサービス を生成します。 AWS リクエスト IDs「software.amazon.awssdk.request」ロガーの「DEBUG」ログレベルを介して報告することもできます。 [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()) 次の `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` に設定できます。このレベルでは、SDK は大量の詳細を出力するため、統合テストを使用してエラーを解消する際にこのレベルを設定することをお勧めします。 このログ記録レベルでは、SDK は設定、認証情報解決、実行インターセプター、高レベルの TLS アクティビティ、リクエスト署名などに関する情報をログに記録します。 以下は、 `S3Client#listBuckets()` 呼び出しに対して SDK によって`DEBUG` レベルで出力されるステートメントの例です。 ``` 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` ファイルは、前の出力を設定します。 ``` ``` ## ワイヤログの有効化 SDK for Java 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 クライアントを使用します。 2 つのカテゴリーのサービスクライアントに使用できる 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 では内部で 1.2 を使用しているため、Apache でのワイヤログ記録には `log4j-1.2-api` アーティファクトへの Maven 依存関係がさらに必要です。 Apache HTTP クライアントのワイヤログ記録を含む log4j 2 の Maven 依存関係のすべてのセットは、以下の構築ファイルスニペットに示されています。 **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 ] `log4j2.xml` 「org.apache.hc.client5.http.wire」ロガーを設定ファイルに追加し、レベルを「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} ``` リクエスト/レスポンスの本文を表示するには、JVM プロパティに `-Djavax.net.debug=all` を追加します。この追加プロパティは、すべての SSL 情報を含む大量の情報をログ記録します。 ログコンソールまたはログファイル内で、`"GET"` または `"POST"` を検索すると、実際のリクエストとレスポンスを含むログのセクションにすばやく移動できます。リクエストに `"Plaintext before ENCRYPTION"` を、レスポンスに `"Plaintext after DECRYPTION"` を検索すると、ヘッダーと本文の全文が表示されます。 ------ #### [ NettyNioAsyncHttpClient ] 非同期サービスクライアントがデフォルト `NettyNioAsyncHttpClient` を使用している場合は、HTTP ヘッダーとリクエスト/レスポンスの本文をログ記録するロガーを `log4j2.xml` ファイルに 2 つ追加します。 ``` ``` 以下はすべての `log4j2.xml` の例です。 ``` ``` これらの設定は、すべてのヘッダー詳細とリクエスト/レスポンス本文をログ記録します。 ------ #### [ AwsCrtAsyncHttpClient/AwsCrtHttpClient ] AWS CRT ベースの HTTP クライアントのインスタンスを使用するようにサービスクライアントを設定している場合は、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 クライアントはレスポンスヘッダーのみをログに記録します。リクエストヘッダー、リクエストボディ、レスポンスボディはログ記録されません。 ------