버전 1에서 버전 2로의 SDK 지표 게시 변경 사항

이 주제에서는의 버전 1.x(v1)에서 버전 2.x(v2)로의 클라이언트 측 SDK 지표 게시 변경 사항에 대해 자세히 설명합니다 AWS SDK for Java.

높은 수준의 변경 사항

아키텍처 변경

v1에서 지표 수집은 시스템 속성으로 활성화하는 글로벌 JVM 전체 설정입니다. SDK는 수집된 모든 지표를 CloudWatch에 자동으로 게시합니다. 지표 대상은 하나뿐입니다.

v2에서 지표 컬렉션은 개별 서비스 클라이언트 또는 요청에 연결하는 플러그형 MetricPublisher 인터페이스를 사용합니다. SDK는 세 가지 구현을 제공합니다.

범위 변경

v1에서 지표를 활성화하면 JVM의 모든 AWS 서비스 클라이언트에 대한 데이터가 게시됩니다. v2에서는 서비스 클라이언트 수준 또는 개별 요청 수준에서 지표를 제어합니다.

지표 유형 변경

v1은 AWS 요청 지표, AWS 서비스 지표 및 머신 지표(힙 메모리, 스레드 수, 열린 파일 설명자)의 세 가지 범주의 지표를 수집합니다.

v2는 API 호출 기간, 마샬링 기간, 서명 기간 및 재시도 횟수와 같은 SDK 요청 및 응답 지표에 중점을 둡니다. v2는 힙 메모리, 스레드 수 및 열린 파일 설명자와 같은 시스템 지표를 수집하지 않습니다. CloudWatch에서 JVM 지표를 계속 수집하려면 CloudWatch 에이전트를 JMX 지표 컬렉션과 함께 사용할 수 있습니다.

종속성 변경 사항

다음 표에는 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>

¹ 최신 버전. ² 최신 버전.

v2 아티팩트는 다음 표와 같이 사용 사례에 따라 달라집니다.

API 변경 사항

지표 활성화

다음 표에서는 다양한 사용 사례에 대해 v1 및 v2에서 지표를 활성화하는 방법을 비교합니다.

-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties

-Dcom.amazonaws.sdk.enableDefaultMetrics

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 대상을 구성하는 방법을 보여줍니다.

-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();

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

-Dcom.amazonaws.sdk.enableDefaultMetrics=excludeMachineMetrics

Lambda 함수에 대한 지표

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();

개발 및 디버깅 지표

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();

필수 권한

다음 표에는 각 지표 게시자에 필요한 IAM 권한이 나열되어 있습니다.

제한 사항

AWS CRT 기반 S3 클라이언트는 현재 v2의 SDK 지표 수집을 지원하지 않습니다.

추가 리소스