View a markdown version of this page

從第 1 版發佈到第 2 版的 SDK 指標變更 - AWS SDK for Java 2.x
高階變更相依性變更API 變更限制其他資源

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

從第 1 版發佈到第 2 版的 SDK 指標變更

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

高階變更

架構變更

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

在 v2 中，指標集合使用可插入的 MetricPublisher 介面，您連接到個別服務用戶端或請求。開發套件提供三種實作：

  • CloudWatchMetricPublisher：彙總指標並定期上傳至 CloudWatch。最適合長時間執行的應用程式。

  • EmfMetricLoggingPublisher：在 CloudWatch Embedded Metric Format (EMF) 中將指標寫入為結構化日誌項目。最適合 Lambda 函數和其他短期環境。

  • LoggingMetricPublisher：透過 SLF4J 記錄將指標輸出至主控台。最適合本機開發和偵錯。

範圍變更

在 v1 中，啟用指標會發佈 JVM 中所有 AWS 服務用戶端的資料。在 v2 中，您可以在服務用戶端層級或個別請求層級控制指標。

指標類型變更

v1 收集三個類別的指標： AWS 請求指標、 AWS 服務指標和機器指標 （堆積記憶體、執行緒計數、開啟的檔案描述項）。

v2 著重於 SDK 請求和回應指標，例如 API 呼叫持續時間、封送持續時間、簽署持續時間和重試計數。v2 不會收集機器指標，例如堆積記憶體、執行緒計數和開啟的檔案描述項。若要在 CloudWatch 中繼續收集 JVM 指標，您可以使用 CloudWatch Agent 搭配 JMX 指標集合。

相依性變更

下表顯示 v1 和 v2 之間的 Maven 相依性和套件名稱變更。

變更 v1   v2

Maven 相依性

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.x1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-cloudwatchmetrics</artifactId>
    </dependency>
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.x.x2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>cloudwatch-metric-publisher</artifactId>
    </dependency>
</dependencies>
套件名稱 com.amazonaws.metrics software.amazon.awssdk.metrics

1 最新版本。 2 最新版本。

v2 成品取決於使用案例，如下表所示。

使用案例 v2 artifactId 最低 SDK 版本
長時間執行的應用程式 cloudwatch-metric-publisher 2.14.0
Lambda 函式 emf-metric-logging-publisher 2.30.3
開發和偵錯 不需要額外的相依性 (LoggingMetricPublisher 位於 SDK 核心） 2.14.0

API 變更

啟用 指標

下表比較如何在 v1 和 v2 中針對不同的使用案例啟用指標。

使用案例 v1   v2

全域啟用指標

新增 JVM 系統屬性：

-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties
 不支援。將 MetricPublisher連接到每個服務用戶端。

在不含登入資料檔案的 Amazon EC2 上啟用指標

 
-Dcom.amazonaws.sdk.enableDefaultMetrics
 不適用。v2 使用其標準登入資料解析。

啟用服務用戶端的指標

 不支援。指標為全域或關閉。 
MetricPublisher metricsPub =
    CloudWatchMetricPublisher.create();

DynamoDbClient ddb = DynamoDbClient.builder()
    .overrideConfiguration(c -> c
        .addMetricPublisher(metricsPub))
    .build();

// ... use the client ...

metricsPub.close();
ddb.close();

啟用單一請求的指標

 不支援。 
ddb.listTables(ListTablesRequest.builder()
    .overrideConfiguration(c -> c
        .addMetricPublisher(metricsPub))
    .build());

設定 CloudWatch 目的地

下表顯示與 v2 相比，如何在 v1 中設定 CloudWatch 目的地。

使用案例 v1   v2

設定 CloudWatch 區域

系統屬性：

-Dcom.amazonaws.sdk.enableDefaultMetrics=cloudwatchRegion=us-west-2
 
CloudWatchMetricPublisher.builder()
    .cloudWatchClient(
        CloudWatchAsyncClient.builder()
            .region(Region.US_WEST_2)
            .build())
    .build();

設定上傳頻率

 不可設定。大約每分鐘上傳一次。 
CloudWatchMetricPublisher.builder()
    .uploadFrequency(Duration.ofMinutes(5))
    .build();

設定 CloudWatch 命名空間

 修正為 AWSSDK/Java。

預設為 AwsSdk/JavaSdk2。可透過以下方式設定：

CloudWatchMetricPublisher.builder()
    .namespace("MyApp/SDK")
    .build();
注意

如果您有參考 v1 命名空間 的現有 CloudWatch 儀表板或警示AWSSDK/Java，請將 .namespace("AWSSDK/Java") 設定為保留連續性。

排除機器指標

系統屬性：

-Dcom.amazonaws.sdk.enableDefaultMetrics=excludeMachineMetrics
 不適用。v2 不會收集機器指標。

Lambda 函數的指標

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明確設定 。

開發和偵錯的指標

v1 沒有以主控台為基礎的指標輸出。在 v2 中，使用 LoggingMetricPublisher：

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

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

生命週期管理

在 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上呼叫 。否則可能會導致執行緒或檔案描述項洩漏。

所需的許可

下表列出每個指標發佈者所需的 IAM 許可。

許可類型 v1 v2 (CloudWatchMetricPublisher) v2 (EmfMetricLoggingPublisher)
IAM 許可 cloudwatch:PutMetricData cloudwatch:PutMetricData logs:PutLogEvents

限制

AWS CRT 型 S3 用戶端目前不支援 v2 中的 SDK 指標集合。

其他資源