Modifications apportées à la publication des métriques du SDK de la version 1 à la version 2

Cette rubrique détaille les modifications apportées à la publication des métriques du SDK côté client entre la version 1.x (v1) et la version 2.x (v2) du. AWS SDK pour Java

High-level modifications

Changements d'architecture

Dans la version 1, la collecte de métriques est un JVM-wide paramètre global que vous activez à l'aide d'une propriété système. Le SDK publie automatiquement toutes les métriques collectées sur CloudWatch. Il n'existe qu'une seule destination pour les métriques.

Dans la version 2, la collecte de métriques utilise une MetricPublisherinterface enfichable que vous associez à des clients ou à des demandes de service individuels. Le SDK propose trois implémentations :

Modifications du champ

Dans la version 1, l'activation des métriques publie les données de tous les clients de AWS service de la JVM. Dans la version 2, vous contrôlez les métriques au niveau du client de service ou au niveau des demandes individuelles.

Changements de type de métrique

v1 collecte trois catégories de métriques : les métriques de AWS demande, les métriques de AWS service et les métriques de machine (mémoire de segment, nombre de threads, descripteurs de fichiers ouverts).

La v2 se concentre sur les métriques de demande et de réponse du SDK, telles que la durée des appels d'API, la durée du marshaling, la durée de signature et le nombre de tentatives. La v2 ne collecte pas les métriques de la machine telles que la mémoire en tas, le nombre de threads et les descripteurs de fichiers ouverts. Pour continuer à collecter des métriques JVM dans CloudWatch, vous pouvez utiliser l'CloudWatch agent avec la collecte de métriques JMX.

Modifications des dépendances

Le tableau suivant montre la dépendance Maven et les changements de nom de package entre la v1 et la v2.

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

¹ Dernière version. ² Dernière version.

L'artefact v2 dépend du cas d'utilisation, comme indiqué dans le tableau suivant.

Modifications de l'API

Activation des métriques

Le tableau suivant compare la manière d'activer les métriques dans les versions 1 et 2 pour différents cas d'utilisation.

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

Configuration de la CloudWatch destination

Le tableau suivant montre comment configurer la CloudWatch destination dans la version v1 par rapport à la version v2.

-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étriques pour les fonctions Lambda

v1 n'a pas de solution de Lambda-specific métriques. Dans la version 2, utilisez celui EmfMetricLoggingPublisher qui écrit les métriques sous forme d'entrées de journal structurées au format EMF ( CloudWatch Embedded Metric Format) :

// 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étriques pour le développement et le débogage

v1 n'a pas de sortie de métriques basée sur la console. Dans la version 2, utilisez LoggingMetricPublisher :

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

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

Gestion du cycle de vie

Dans la version 1, la collecte des métriques s'exécute pendant toute la durée de vie de la machine virtuelle Java une fois que la propriété du système est définie. Dans la version 2, vous devez gérer le cycle de vie des 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();

Autorisations requises

Le tableau suivant répertorie les autorisations IAM requises pour chaque éditeur de mesures.

Limitations

Le client AWS CRT-based S3 ne prend actuellement pas en charge la collecte des métriques du SDK dans la version v2.

Ressources supplémentaires