Cambios en la publicación de métricas del SDK de la versión 1 a la versión 2

En este tema se detallan los cambios en la publicación de métricas del SDK del lado del cliente desde la versión 1.x (v1) a la versión 2.x (v2) de. AWS SDK para Java

High-level cambios

Cambios en la arquitectura

En la versión 1, la recopilación de métricas es una JVM-wide configuración global que se habilita con una propiedad del sistema. El SDK publica automáticamente todas las métricas recopiladas en CloudWatch. Solo hay un destino de métricas.

En la versión 2, la recopilación de métricas utiliza una MetricPublisherinterfaz conectable que se conecta a los clientes o solicitudes de servicio individuales. El SDK ofrece tres implementaciones:

Cambios de alcance

En la versión 1, al habilitar las métricas, se publican los datos de todos los clientes de AWS servicio de la JVM. En la versión 2, las métricas se controlan a nivel de cliente de servicio o a nivel de solicitud individual.

Cambios en el tipo de métrica

La versión 1 recopila tres categorías de métricas: métricas de AWS solicitudes, métricas de AWS servicio y métricas de máquinas (memoria de pila, recuento de subprocesos y descriptores de archivos abiertos).

La versión 2 se centra en las métricas de solicitudes y respuestas del SDK, como la duración de las llamadas a la API, la duración de la clasificación, la duración de las firmas y el recuento de reintentos. La v2 no recopila métricas de las máquinas, como la memoria acumulada, el recuento de subprocesos y los descriptores de archivos abiertos. Para seguir recopilando métricas de JVM CloudWatch, puede utilizar el CloudWatch agente con la recopilación de métricas de JMX.

Cambios en las dependencias

La siguiente tabla muestra la dependencia de Maven y los cambios en el nombre de los paquetes entre la versión 1 y la versión 2.

<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>

¹ Última versión. ² Última versión.

El artefacto v2 depende del caso de uso, como se muestra en la siguiente tabla.

Cambios en la API

Habilitar métricas de

En la siguiente tabla, se compara cómo habilitar las métricas en las versiones 1 y 2 para distintos casos de uso.

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

Configurar el CloudWatch destino

La siguiente tabla muestra cómo configurar el CloudWatch destino en la versión 1 en comparación con la versión 2.

-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

Métricas para funciones Lambda

La versión 1 no tiene una solución de Lambda-specific métricas. En la versión 2, EmfMetricLoggingPublisher utilícela para escribir las métricas como entradas de registro CloudWatch estructuradas en formato métrico integrado (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();

Métricas para el desarrollo y la depuración

La versión 1 no tiene una salida de métricas basada en una consola. En la versión 2, utiliceLoggingMetricPublisher:

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

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

Administración del ciclo de vida

En la versión 1, la recopilación de métricas se ejecuta durante toda la vida útil de la JVM una vez establecida la propiedad del sistema. En la versión 2, debe gestionar el ciclo de vida deMetricPublisher:

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

Permisos necesarios

En la siguiente tabla se enumeran los permisos de IAM necesarios para cada publicador de métricas.

Limitaciones

El cliente AWS CRT-based S3 no admite actualmente la recopilación de métricas del SDK en la versión 2.

Recursos adicionales