기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 버전 1에서 버전 2로의 SDK 지표 게시 변경 사항
<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에 자동으로 게시합니다. 지표 대상은 하나뿐입니다.

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 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는 API 호출 기간, 마샬링 기간, 서명 기간 및 재시도 횟수와 같은 SDK 요청 및 응답 지표에 중점을 둡니다. v2는 힙 메모리, 스레드 수 및 열린 파일 설명자와 같은 시스템 지표를 수집하지 않습니다. CloudWatch에서 JVM 지표를 계속 수집하려면 [CloudWatch 에이전트를 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>  | 
| 업로드 빈도 설정 | 구성할 수 없습니다. 약 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 대시보드 또는 경보가 있는 경우 연속성`.namespace("AWSSDK/Java")`을 유지하도록를 `AWSSDK/Java`설정합니다.  | 
| 시스템 지표 제외 | 시스템 속성 속성:<pre>-Dcom.amazonaws.sdk.enableDefaultMetrics=excludeMachineMetrics</pre> | 해당 사항 없음. v2는 시스템 지표를 수집하지 않습니다. | 

### Lambda 함수에 대한 지표
<a name="migration-metrics-lambda"></a>

v1에는 Lambda별 지표 솔루션이 없습니다. v2에서는 지표를 CloudWatch 임베디드 지표 형식(EMF)의 구조화된 로그 항목으로 `EmfMetricLoggingPublisher` 작성하는를 사용합니다.

```
// 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)