翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# SDK メトリクスの公開をバージョン 1 からバージョン 2 に変更
<a name="migration-metrics"></a>

このトピックでは、 のバージョン 1.x (v1) からバージョン 2.x (v2) へのクライアント側の SDK メトリクス発行の変更について詳しく説明します AWS SDK for Java。

## 高レベル変更
<a name="migration-metrics-high-level"></a>

### アーキテクチャの変更
<a name="migration-metrics-architecture"></a>

v1 では、メトリクスコレクションは、システムプロパティで有効にする JVM 全体のグローバル設定です。SDK は、収集されたすべてのメトリクスを CloudWatch に自動的に発行します。メトリクスの送信先は 1 つだけです。

v2 では、メトリクスコレクションは、個々のサービスクライアントまたはリクエストにアタッチするプラガブル [MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html) インターフェイスを使用します。SDK には 3 つの実装があります。
+ **[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)**: メトリクスを集約し、定期的に CloudWatch にアップロードします。長時間実行されるアプリケーションに最適です。
+ **[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)**: CloudWatch Embedded Metric Format (EMF) の構造化ログエントリとしてメトリクスを書き込みます。Lambda 関数やその他の存続期間の短い環境に最適です。
+ **[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)**: SLF4J ログ記録を通じてメトリクスをコンソールに出力します。ローカル開発とデバッグに最適です。

### スコープの変更
<a name="migration-metrics-scope"></a>

v1 では、メトリクスを有効にすると、JVM 内のすべての AWS サービスクライアントのデータが公開されます。v2 では、サービスクライアントレベルまたは個々のリクエストレベルでメトリクスを制御します。

### メトリクスタイプの変更
<a name="migration-metrics-types"></a>

v1 は、 AWS リクエストメトリクス、 AWS サービスメトリクス、マシンメトリクス (ヒープメモリ、スレッド数、オープンファイル記述子) の 3 つのカテゴリのメトリクスを収集します。

v2 は、API コール期間、マーシャリング期間、署名期間、再試行回数などの SDK リクエストおよびレスポンスメトリクスに焦点を当てています。v2 は、ヒープメモリ、スレッド数、オープンファイル記述子などのマシンメトリクスを収集しません。CloudWatch で JVM メトリクスを引き続き収集するには、[JMX メトリクスコレクションで CloudWatch エージェント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-JMX-metrics.html)を使用できます。

## 依存関係の変更
<a name="migration-metrics-deps"></a>

次の表は、v1 と v2 の間の Maven の依存関係とパッケージ名の変更を示しています。



| 変更 | v1 |  v2 | 
| --- | --- | --- | 
| Maven の依存関係 |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>com.amazonaws</groupId><br />            <artifactId>aws-java-sdk-bom</artifactId><br />            <version>{{1.12.x1}}</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>com.amazonaws</groupId><br />        <artifactId>aws-java-sdk-cloudwatchmetrics</artifactId><br />    </dependency><br /></dependencies></pre>  |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>software.amazon.awssdk</groupId><br />            <artifactId>bom</artifactId><br />            <version>{{2.x.x2}}</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>software.amazon.awssdk</groupId><br />        <artifactId>cloudwatch-metric-publisher</artifactId><br />    </dependency><br /></dependencies></pre>  | 
| パッケージ名 | com.amazonaws.metrics | software.amazon.awssdk.metrics | 

1 [最新バージョン](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。 2 [最新バージョン](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。

次の表に示すように、v2 アーティファクトはユースケースによって異なります。



| ユースケース | v2 artifactId | SDK の最小バージョン | 
| --- | --- | --- | 
| 長時間実行されるアプリケーション | cloudwatch-metric-publisher | 2.14.0 | 
| Lambda 関数 | emf-metric-logging-publisher | 2.30.3 | 
| 開発とデバッグ | 追加の依存関係は必要ありません (LoggingMetricPublisher は SDK コアにあります) | 2.14.0 | 

## API の変更
<a name="migration-metrics-api"></a>

### メトリクスを有効にする
<a name="migration-metrics-enabling"></a>

次の表は、さまざまなユースケースで v1 と v2 でメトリクスを有効にする方法を比較したものです。



| ユースケース | v1 |  v2 | 
| --- | --- | --- | 
| メトリクスをグローバルに有効にする | JVM システムプロパティを追加します。<pre>-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties</pre> | サポート外。を各サービスクライアントMetricPublisherにアタッチします。 | 
| 認証情報ファイルなしで Amazon EC2 でメトリクスを有効にする |  <pre>-Dcom.amazonaws.sdk.enableDefaultMetrics</pre>  | 該当なし。v2 は標準の認証情報解決を使用します。 | 
| サービスクライアントのメトリクスを有効にする | サポート外。メトリクスはグローバルまたはオフです。 |  <pre>MetricPublisher metricsPub =<br />    CloudWatchMetricPublisher.create();<br /><br />DynamoDbClient ddb = DynamoDbClient.builder()<br />    .overrideConfiguration(c -> c<br />        .addMetricPublisher(metricsPub))<br />    .build();<br /><br />// ... use the client ...<br /><br />metricsPub.close();<br />ddb.close();</pre>  | 
| 1 つのリクエストのメトリクスを有効にする | サポート外。 |  <pre>ddb.listTables(ListTablesRequest.builder()<br />    .overrideConfiguration(c -> c<br />        .addMetricPublisher(metricsPub))<br />    .build());</pre>  | 

### CloudWatch 送信先の設定
<a name="migration-metrics-cw-config"></a>

次の表は、v2 と比較して v1 で CloudWatch 送信先を設定する方法を示しています。



| ユースケース | v1 |  v2 | 
| --- | --- | --- | 
| CloudWatch リージョンの設定 | システムプロパティ属性:<pre>-Dcom.amazonaws.sdk.enableDefaultMetrics=cloudwatchRegion={{us-west-2}}</pre> |  <pre>CloudWatchMetricPublisher.builder()<br />    .cloudWatchClient(<br />        CloudWatchAsyncClient.builder()<br />            .region(Region.US_WEST_2)<br />            .build())<br />    .build();</pre>  | 
| アップロード頻度を設定する | 設定可能ではありません。1 分に約 1 回アップロードします。 |  <pre>CloudWatchMetricPublisher.builder()<br />    .uploadFrequency(Duration.ofMinutes(5))<br />    .build();</pre>  | 
| CloudWatch 名前空間の設定 | を修正しましたAWSSDK/Java。 | デフォルトは `AwsSdk/JavaSdk2` です。以下を介して設定可能:<pre>CloudWatchMetricPublisher.builder()<br />    .namespace("MyApp/SDK")<br />    .build();</pre> v1 名前空間 を参照する既存の CloudWatch ダッシュボードまたはアラームがある場合は`AWSSDK/Java`、継続性を保持する`.namespace("AWSSDK/Java")`ように を設定します。  | 
| マシンメトリクスを除外する | システムプロパティ属性:<pre>-Dcom.amazonaws.sdk.enableDefaultMetrics=excludeMachineMetrics</pre> | 該当なし。v2 はマシンメトリクスを収集しません。 | 

### Lambda 関数のメトリクス
<a name="migration-metrics-lambda"></a>

v1 には Lambda 固有のメトリクスソリューションはありません。v2 `EmfMetricLoggingPublisher`では、 を使用して CloudWatch Embedded Metric Format (EMF) の構造化ログエントリとしてメトリクスを書き込みます。

```
// v2 - Lambda-optimized metrics publishing
EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder()
        .namespace("MyApp")
        .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME)
        .build();

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher))
        .build();
```

**注記**  
Lambda 環境では、 `logGroupName`は`AWS_LAMBDA_LOG_GROUP_NAME`環境変数から自動的に検出されます。Amazon ECS や Amazon EC2 などの Lambda 以外の環境では、ビルダーで`logGroupName`明示的に を設定する必要があります。

### 開発とデバッグのメトリクス
<a name="migration-metrics-debugging"></a>

v1 にはコンソールベースのメトリクス出力はありません。v2 では、 を使用します`LoggingMetricPublisher`。

```
// v2 - Console output for debugging
MetricPublisher loggingPublisher = LoggingMetricPublisher.create();

S3Client s3 = S3Client.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher))
        .build();
```

### ライフサイクル管理
<a name="migration-metrics-lifecycle"></a>

v1 では、システムプロパティが設定されると、メトリクス収集は JVM の存続期間中実行されます。v2 では、 のライフサイクルを管理する必要があります`MetricPublisher`。

```
// v2 - Close the publisher when no longer needed
MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
        .build();

// ... use the client ...

metricsPub.close(); // Flushes remaining metrics to CloudWatch
ddb.close();
```

**重要**  
不要になった`MetricPublisher`インスタンス`close`で を呼び出します。そうしないと、スレッドまたはファイル記述子のリークが発生する可能性があります。

### 必要なアクセス許可
<a name="migration-metrics-permissions"></a>

次の表に、各メトリクスパブリッシャーに必要な IAM アクセス許可を示します。



| アクセス許可タイプ | v1 | v2 (CloudWatchMetricPublisher) | v2 (EmfMetricLoggingPublisher) | 
| --- | --- | --- | --- | 
| IAM 許可 | cloudwatch:PutMetricData | cloudwatch:PutMetricData | logs:PutLogEvents | 

## 制限事項
<a name="migration-metrics-limitations"></a>

[AWS CRT ベースの S3 クライアント](crt-based-s3-client.md)は現在、v2 での SDK メトリクス収集をサポートしていません。

## その他のリソース
<a name="migration-metrics-resources"></a>
+ [v1 メトリクスドキュメント](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/generating-sdk-metrics.html)
+ [から SDK メトリクスを発行する AWS SDK for Java 2.x](metrics.md)
+ [長時間実行されるアプリケーションから SDK メトリクスを発行する](metric-pub-impl-cwmp.md)
+ [関数の AWS Lambda SDK メトリクスを発行する](metric-pub-impl-emf.md)
+ [SDK メトリクスをコンソールに出力する](metric-pub-impl-logging.md)
+ [包括的なメトリクスリファレンス](metrics-list.md)