翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # から 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)`) も含まれます。