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

# 从版本 1 到版本 2 的 SDK 指标发布发生了变化
<a name="migration-metrics"></a>

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

## High-level 改变
<a name="migration-metrics-high-level"></a>

### 架构变更
<a name="migration-metrics-architecture"></a>

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

在 v2 中，指标收集使用可插入的[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)接口，您可以将其附加到各个服务客户端或请求。SDK 提供三种实现：
+ **[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 嵌入式指标格式 (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 不收集堆内存、线程数和打开文件描述符等机器指标。要继续在中收集 JVM 指标 CloudWatch，您可以使用[带有 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 的最低版本 | 
| --- | --- | --- | 
| Long-running 应用程序 | cloudwatch-metric-publisher | emrfs | 
| Lambda 函数 | emf-metric-logging-publisher | 2.30.3 | 
| 开发和调试 | 无需其他依赖项（LoggingMetricPublisher在 SDK 核心中） | emrfs | 

## 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-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`器上明确设置。

### 开发和调试指标
<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>

S [AWS CRT-based 3 客户端](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)