本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 從第 1 版發佈到第 2 版的 SDK 指標變更
<a name="migration-metrics"></a>

本主題詳細說明從 版本 1.x (v1) 發佈至 版本 2.x (v2) 的用戶端 SDK 指標變更。 適用於 Java 的 AWS SDK

## 高階變更
<a name="migration-metrics-high-level"></a>

### 架構變更
<a name="migration-metrics-architecture"></a>

在 v1 中，指標集合是您使用系統屬性啟用的全域全 JVM 設定。SDK 會自動將所有收集的指標發佈至 CloudWatch。只有一個指標目的地。

在 v2 中，指標集合使用可插入的 [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)**：彙總指標並定期上傳至 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 服務指標和機器指標 （堆積記憶體、執行緒計數、開啟的檔案描述項）。

v2 著重於 SDK 請求和回應指標，例如 API 呼叫持續時間、封送持續時間、簽署持續時間和重試計數。v2 不會收集機器指標，例如堆積記憶體、執行緒計數和開啟的檔案描述項。若要在 CloudWatch 中繼續收集 JVM 指標，您可以使用 [CloudWatch Agent 搭配 JMX 指標集合](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>  | 
| 啟用單一請求的指標 | 不支援。 |  <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>  | 
| 設定上傳頻率 | 不可設定。大約每分鐘上傳一次。 |  <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)