View a markdown version of this page

从版本 1 到版本 2 的 SDK 指标发布发生了变化 - AWS SDK for Java 2.x
High-level 改变依赖关系的变化API 更改限制其他资源

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

从版本 1 到版本 2 的 SDK 指标发布发生了变化

本主题详细介绍了客户端 SDK 指标发布从版本 1.x (v1) 到 2.x 版本 (v2) 的变化。 适用于 Java 的 AWS SDK

High-level 改变

架构变更

在 v1 中，指标收集是一个全局 JVM-wide 设置，您可以通过系统属性启用该设置。SDK 会自动将收集到的所有指标发布到 CloudWatch。只有一个指标目的地。

在 v2 中，指标收集使用可插入的MetricPublisher接口，您可以将其附加到各个服务客户端或请求。SDK 提供三种实现：

  • CloudWatchMetricPublisher：汇总指标并将其定期上传到。 CloudWatch最适合长时间运行的应用程序。

  • EmfMetricLoggingPublisher：将指标写成 CloudWatch 嵌入式指标格式 (EMF) 的结构化日志条目。最适合 Lambda 函数和其他短寿命环境。

  • LoggingMetricPublisher：通过 SLF4J 日志将指标输出到控制台。最适合本地开发和调试。

范围变更

在 v1 中，启用指标会发布 JVM 中所有 AWS 服务客户端的数据。在 v2 中，您可以在服务客户端级别或单个请求级别控制指标。

指标类型更改

v1 收集三类指标： AWS 请求指标、 AWS 服务指标和计算机指标（堆内存、线程数、打开的文件描述符）。

v2 侧重于 SDK 请求和响应指标，例如 API 调用时长、编组时长、签名持续时间和重试次数。v2 不收集堆内存、线程数和打开文件描述符等机器指标。要继续在中收集 JVM 指标 CloudWatch，您可以使用带有 JMX 指标收集功能的CloudWatch 代理。

依赖关系的变化

下表显示了 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 的最低版本
Long-running 应用程序 cloudwatch-metric-publisher emrfs
Lambda 函数 emf-metric-logging-publisher 2.30.3
开发和调试 无需其他依赖项（LoggingMetricPublisher在 SDK 核心中） emrfs

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-specific 指标解决方案。在 v2 中，使用EmfMetricLoggingPublisher它以 CloudWatch 嵌入式指标格式 (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在非 Lambda 环境中，例如 Amazon ECS 或 Amazon EC2，您必须在构建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

限制

S AWS CRT-based 3 客户端目前不支持 v2 中的 SDK 指标收集。

其他资源