Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Publiez les métriques du SDK à partir du AWS SDK for Java 2.x AWS SDK for Java 2.x Vous pouvez ainsi collecter des statistiques sur les clients et les demandes de service dans votre application, analyser les résultats dans Amazon CloudWatch Logs, puis agir en conséquence. Par défaut, la collecte de métriques est désactivée dans le SDK. Cette rubrique vous aide à l'activer et à le configurer. ## Commencer à utiliser les métriques du SDK Pour activer la collecte de métriques dans votre application, choisissez l'implémentation appropriée de l'`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`interface en fonction de votre cas d'utilisation et suivez les instructions de configuration détaillées : **Pour les applications de longue durée :** + Utilisation des `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` + Consultez [Publier les métriques du SDK à partir d'applications de longue durée](metric-pub-impl-cwmp.md) pour obtenir des instructions de configuration complètes, des exemples de code et des options de configuration. **Pour les AWS Lambda fonctions :** + Utilisation des `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` + Voir [Publier les métriques du SDK pour les AWS Lambda fonctions pour](metric-pub-impl-emf.md) les instructions de configuration complètes, les dépendances et la configuration spécifique à Lambda. **Pour le dépannage et les sorties de console :** + Utilisation des `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` + Consultez les [métriques du SDK de sortie vers la console pour le développement et le débogage](metric-pub-impl-logging.md) pour obtenir des instructions de configuration, des options de formatage et des exemples de développement local et de résolution des problèmes. ## Aperçu rapide de la mise en œuvre Voici à quoi ressemble l'activation des métriques pour chaque cas d'utilisation : **Applications de longue durée :** ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` **Fonctions Lambda :** ``` EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("MyApp") .build(); DynamoDbClient dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .build(); ``` **Développement et débogage :** ``` MetricPublisher loggingPublisher = LoggingMetricPublisher.create(); S3Client s3 = S3Client.builder() .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher)) .build(); ``` ## Limitation des métriques du client S3 AWS basé sur CRT Le [client S3 AWS basé sur CRT](crt-based-s3-client.md) ne prend actuellement pas en charge la collecte de métriques du SDK. Le générateur d'une instance cliente S3 AWS basée sur CRT ne fournit pas de méthodes pour configurer les éditeurs de métriques. [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html) ## Quand les statistiques sont-elles disponibles ? Les métriques sont généralement disponibles dans les 5 à 10 minutes suivant leur émission par le SDK for Java. Pour des up-to-date statistiques précises, vérifiez Cloudwatch au moins 10 minutes après avoir émis les métriques depuis vos applications Java. ## Quelles informations sont collectées ? La collecte de métriques inclut les éléments suivants : + Nombre de demandes d'API, y compris si elles aboutissent ou échouent + Informations sur les requêtes Services AWS que vous appelez dans vos demandes d'API, y compris les exceptions renvoyées + Durée des différentes opérations telles que le marshalling, la signature et les requêtes HTTP + Mesures du client HTTP, telles que le nombre de connexions ouvertes, le nombre de demandes en attente et le nom du client HTTP utilisé **Note** Les métriques disponibles varient selon le client HTTP. Pour une liste complète, consultez la section [Mesures relatives aux clients du service](metrics-list.md). ## Comment puis-je utiliser ces informations ? Vous pouvez utiliser les métriques collectées par le SDK pour surveiller les clients de service de votre application. Vous pouvez examiner les tendances générales d'utilisation, identifier les anomalies, examiner les exceptions renvoyées par les clients du service ou approfondir la compréhension d'un problème particulier. À l'aide d'Amazon CloudWatch Logs, vous pouvez également créer des alarmes pour vous avertir dès que votre application atteint une condition que vous définissez. Pour plus d'informations, consultez les sections [Utilisation CloudWatch des métriques Amazon Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) et [Utilisation CloudWatch des alarmes Amazon Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) dans le [guide de l'utilisateur Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). # Publiez les métriques du SDK à partir d'applications de longue durée à l'aide du AWS SDK for Java 2.x Étant donné que l'`[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)`implémentation agrège et télécharge régulièrement les métriques sur Amazon CloudWatch avec un certain retard, son utilisation convient parfaitement aux applications de longue durée. Les paramètres par défaut de l'éditeur de métriques visent à minimiser l'utilisation de la mémoire et les CloudWatch coûts, tout en fournissant un aperçu utile des données métriques. ## Configuration Avant de pouvoir activer et utiliser les métriques en utilisant`CloudWatchMetricPublisher`, procédez comme suit. ### Étape 1 : Ajouter la dépendance requise Configurez les dépendances de votre projet (par exemple, dans votre `build.gradle` fichier `pom.xml` ou dans votre fichier) pour utiliser la version `2.14.0` ou une version ultérieure du AWS SDK pour Java. Incluez l'`cloudwatch-metric-publisher`ArtifactiD avec le `2.14.0` numéro de version ou une version ultérieure dans les dépendances de votre projet. Par exemple : ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk cloudwatch-metric-publisher ``` ### Étape 2 : configurer les autorisations requises Activez `cloudwatch:PutMetricData` les autorisations pour l'identité IAM utilisée par l'éditeur de métriques afin de permettre au SDK for Java d'écrire des métriques. ## Activer les métriques pour une demande spécifique Le cours suivant explique comment activer l'éditeur de CloudWatch métriques pour une demande adressée à Amazon DynamoDB. Il utilise la configuration par défaut de l'éditeur de métriques. ``` import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest; public class DefaultConfigForRequest { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.create(); // Publish metrics the for ListTables operation. ddb.listTables(ListTablesRequest.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build()); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` **Important** Assurez-vous que votre application appelle `close` l'`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`instance lorsque le client de service n'est plus utilisé. Si vous ne le faites pas, cela peut entraîner des fuites de thread ou de descripteur de fichier. ## Activer les métriques récapitulatives pour un client de service spécifique L'extrait de code suivant montre comment activer un éditeur de CloudWatch mesures avec des paramètres par défaut pour un client de service. ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` ## Personnaliser un éditeur CloudWatch de statistiques La classe suivante montre comment configurer une configuration personnalisée pour l'éditeur de métriques pour un client de service spécifique. Les personnalisations incluent le chargement d'un profil spécifique, la spécification d'une AWS région dans laquelle l'éditeur de métriques envoie des demandes et la personnalisation de la fréquence à laquelle l'éditeur envoie des métriques. CloudWatch ``` import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider; import software.amazon.awssdk.core.metrics.CoreMetric; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import java.time.Duration; public class CustomConfigForDDBClient { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.builder() .cloudWatchClient(CloudWatchAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(ProfileCredentialsProvider.create("cloudwatch")) .build()) .uploadFrequency(Duration.ofMinutes(5)) .maximumCallsPerUpload(100) .namespace("ExampleSDKV2Metrics") .detailedMetrics(CoreMetric.API_CALL_DURATION) .build(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); // Publish metrics for DynamoDB operations. ddb.listTables(); ddb.describeEndpoints(); ddb.describeLimits(); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` Les personnalisations présentées dans l'extrait précédent ont les effets suivants. + La `cloudWatchClient` méthode vous permet de personnaliser le CloudWatch client utilisé pour envoyer les métriques. Dans cet exemple, nous utilisons une région différente de la région par défaut *us-east-1 où* le client envoie des métriques. Nous utilisons également un profil nommé différent, *cloudwatch*, dont les informations d'identification seront utilisées pour authentifier les demandes adressées à. CloudWatch Ces informations d'identification doivent être autorisées à`cloudwatch:PutMetricData`. + La `uploadFrequency` méthode vous permet de spécifier la fréquence à laquelle l'éditeur télécharge les CloudWatch métriques. La valeur par défaut est une fois par minute. + La `maximumCallsPerUpload` méthode limite le nombre d'appels effectués par téléchargement. La valeur par défaut est illimitée. + Par défaut, le SDK pour Java 2.x publie les métriques sous l'espace de noms. `AwsSdk/JavaSdk2` Vous pouvez utiliser `namespace` cette méthode pour spécifier une valeur différente. + Par défaut, le SDK publie des métriques récapitulatives. Les mesures récapitulatives comprennent la moyenne, le minimum, le maximum, la somme et le nombre d'échantillons. En spécifiant une ou plusieurs métriques du SDK dans la `detailedMetrics` méthode, le SDK publie des données supplémentaires pour chaque métrique. Ces données supplémentaires permettent d'obtenir des statistiques percentiles telles que p90 et p99 que vous pouvez interroger. CloudWatch Les métriques détaillées sont particulièrement utiles pour les métriques de latence`APICallDuration`, telles que celles qui mesurent la end-to-end latence pour les demandes des clients du SDK. Vous pouvez utiliser les champs de la `[CoreMetric](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)` classe pour spécifier d'autres métriques courantes du SDK. **Étapes suivantes :** Si vous utilisez également des fonctions Lambda, voir [Publier des métriques du SDK pour les fonctions de publication de métriques basées sur les AWS Lambda champs](metric-pub-impl-emf.md) EMF. # Publiez les métriques du SDK pour les AWS Lambda fonctions à l'aide du AWS SDK for Java 2.x Comme les fonctions Lambda s'exécutent généralement pendant des millisecondes à quelques minutes, tout retard dans l'envoi des métriques, qui se produit avec le`CloudWatchMetricPublisher`, risque d'entraîner une perte de données. `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`fournit une approche plus adaptée en écrivant immédiatement les métriques sous forme d'entrées de journal structurées au format [EMF (CloudWatch Embedded Metric Format).](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) `EmfMetricLoggingPublisher`fonctionne dans des environnements d'exécution intégrés à Amazon CloudWatch Logs, tels qu' AWS Lambda Amazon Elastic Container Service. ## Configuration Avant de pouvoir activer et utiliser les métriques en utilisant`EmfMetricLoggingPublisher`, procédez comme suit. ### Étape 1 : Ajouter la dépendance requise Configurez les dépendances de votre projet (par exemple, dans votre `build.gradle` fichier `pom.xml` ou dans votre fichier) pour utiliser la version `2.30.3` ou une version ultérieure du AWS SDK pour Java. Incluez l'`emf-metric-logging-publisher`ArtifactiD avec le `2.30.3` numéro de version ou une version ultérieure dans les dépendances de votre projet. Par exemple : ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk emf-metric-logging-publisher ``` ### Étape 2 : configurer les autorisations requises Activez `logs:PutLogEvents` les autorisations pour l'identité IAM utilisée par l'éditeur de métriques afin de permettre au SDK for Java d'écrire des journaux au format EMF. ### Étape 3 : Configuration de la journalisation Pour garantir une collecte correcte des métriques, configurez votre journalisation pour qu'elle soit sortie sur la console au `INFO` niveau ou inférieur (par exemple`DEBUG`). Dans votre `log4j2.xml` dossier : ``` ``` Consultez la [rubrique consacrée à la journalisation](logging-slf4j.md) dans ce guide pour plus d'informations sur la configuration d'un `log4j2.xml` fichier. ## Configuration et utilisation `EmfMetricLoggingPublisher` La classe de fonction Lambda suivante crée et configure d'abord une `EmfMetricLoggingPublisher` instance, puis l'utilise avec un client de service Amazon DynamoDB : ``` public class GameIdHandler implements RequestHandler, String> { private final EmfMetricLoggingPublisher emfPublisher; private final DynamoDbClient dynamoDb; public GameIdHandler() { // Build the publisher. this.emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("namespace") .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME) .build(); // Add the publisher to the client. this.dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .region(Region.of(System.getenv("AWS_REGION"))) .build(); } @Override public String handleRequest(Map event, Context context) { Map gameItem = new HashMap<>(); gameItem.put("gameId", AttributeValue.builder().s(event.get("id")).build()); PutItemRequest putItemRequest = PutItemRequest.builder() .tableName("games") .item(gameItem) .build(); dynamoDb.putItem(putItemRequest); return "Request handled"; } } ``` Lorsque le client DynamoDB exécute la méthode, il publie automatiquement `putItem` les métriques dans CloudWatch un flux de journal au format EMF. ### Exemple d'événement du journal EMF Par exemple, si vous envoyez l'événement suivant à la fonction GameHandler Lambda avec la journalisation configurée comme indiqué précédemment : ``` { "id": "23456" } ``` Une fois que la fonction a traité l'événement, vous trouverez deux événements de journal qui ressemblent à ceux de l'exemple suivant. L'objet JSON du deuxième événement contient les données métriques du SDK Java pour l'`PutItem`opération vers DynamoDB. Lorsqu'il CloudWatch reçoit un événement de journal au format EMF, il analyse automatiquement le JSON structuré pour extraire les données métriques. CloudWatch crée ensuite les métriques correspondantes tout en stockant l'entrée de journal d'origine dans CloudWatch Logs. ``` 2025-07-11 15:58:30 [main] INFO org.example.GameIdHandler:39 - Received map: {id=23456} 2025-07-11 15:58:34 [main] INFO software.amazon.awssdk.metrics.publishers.emf.EmfMetricLoggingPublisher:43 - { "_aws": { "Timestamp": 1752249513975, "LogGroupName": "/aws/lambda/GameId", "CloudWatchMetrics": [ { "Namespace": "namespace", "Dimensions": [ [ "OperationName", "ServiceId" ] ], "Metrics": [ { "Name": "AvailableConcurrency" }, { "Name": "PendingConcurrencyAcquires" }, { "Name": "ServiceCallDuration", "Unit": "Milliseconds" }, { "Name": "EndpointResolveDuration", "Unit": "Milliseconds" }, { "Name": "MaxConcurrency" }, { "Name": "BackoffDelayDuration", "Unit": "Milliseconds" }, { "Name": "MarshallingDuration", "Unit": "Milliseconds" }, { "Name": "LeasedConcurrency" }, { "Name": "SigningDuration", "Unit": "Milliseconds" }, { "Name": "ConcurrencyAcquireDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallSuccessful" }, { "Name": "RetryCount" }, { "Name": "UnmarshallingDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallDuration", "Unit": "Milliseconds" }, { "Name": "CredentialsFetchDuration", "Unit": "Milliseconds" } ] } ] }, "AvailableConcurrency": 0, "PendingConcurrencyAcquires": 0, "OperationName": "PutItem", "ServiceCallDuration": 1339, "EndpointResolveDuration": 81, "MaxConcurrency": 50, "BackoffDelayDuration": 0, "ServiceId": "DynamoDB", "MarshallingDuration": 181, "LeasedConcurrency": 1, "SigningDuration": 184, "ConcurrencyAcquireDuration": 83, "ApiCallSuccessful": 1, "RetryCount": 0, "UnmarshallingDuration": 85, "ApiCallDuration": 1880, "CredentialsFetchDuration": 138 } ``` La [documentation de l'API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html) `EmfMetricLoggingPublisher.Builder` indique les options de configuration que vous pouvez utiliser. Vous pouvez également activer la journalisation des métriques EMF pour une seule demande, comme [indiqué pour le CloudWatchMetricPublisher](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request). **Prochaines étapes :** pour les applications de longue durée, voir [Publier des métriques du SDK à partir d'applications de longue durée pour la publication de métriques](metric-pub-impl-cwmp.md) CloudWatch basées sur des métriques. # Envoyez les métriques du SDK à la console à l'aide du AWS SDK for Java 2.x L'`[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)`implémentation génère des métriques directement dans la console ou dans les fichiers journaux de votre application. Cette approche est idéale pour le développement, le débogage et la compréhension des métriques collectées par le SDK sans avoir besoin de services externes tels qu'Amazon. CloudWatch Contrairement à `CloudWatchMetricPublisher` et`EmfMetricLoggingPublisher`, `LoggingMetricPublisher` fournit une sortie immédiate sans délais ni dépendances externes. Cela le rend parfait pour les scénarios de développement et de dépannage locaux. ## Quand utiliser LoggingMetricPublisher Utilisez `LoggingMetricPublisher` lorsque vous devez : + Déboguer la collecte de métriques pendant le développement + Découvrez les indicateurs que le SDK collecte pour vos opérations + Résoudre les problèmes de performances localement + Tester la collecte de métriques sans dépendance à des services externes + Afficher les métriques immédiatement dans votre console ou dans vos fichiers journaux **Note** `LoggingMetricPublisher`n'est pas recommandé pour les environnements de production où vous avez besoin de capacités de stockage et d'analyse de métriques persistantes. ## Configurer la journalisation de la console pour les métriques Pour voir le `LoggingMetricPublisher` résultat, configurez votre infrastructure de journalisation pour afficher les messages de `INFO` niveau. La `log4j2.xml` configuration suivante garantit l'affichage des métriques dans votre console : ``` ``` Cette configuration indique au SDK de générer des métriques au `INFO` niveau de votre console. La configuration de l'`LoggingMetricPublisher`enregistreur garantit que la sortie métrique apparaît même si votre enregistreur racine utilise un niveau supérieur tel que `WARN` ou. `ERROR` ## Activer les métriques de console pour un client de service L'exemple suivant montre comment créer un `LoggingMetricPublisher` et l'utiliser avec un client Amazon Simple Storage Service : ``` import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; // Create a LoggingMetricPublisher with default settings. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Add the publisher to your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build(); // Make requests - metrics will appear in your console. s3Client.listBuckets(); // Clean up resources. metricPublisher.close(); s3Client.close(); ``` ## Choisissez le format de sortie métrique `LoggingMetricPublisher`prend en charge deux formats de sortie : + **Format PLAIN (par défaut) :** affiche les métriques sous forme d'entrées compactes sur une seule ligne + **Format PRETTY :** affiche les métriques dans un format multiligne lisible par l'homme L'exemple suivant montre comment utiliser le format PRETTY pour faciliter la lecture pendant le développement : ``` import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; // Create a LoggingMetricPublisher with PRETTY format. MetricPublisher prettyMetricPublisher = LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY ); // Use with your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(prettyMetricPublisher)) .build(); ``` ## Exemple complet L'exemple suivant illustre l'utilisation `LoggingMetricPublisher` de deux manières : + Au niveau du client de service + Pour une seule demande ``` import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListBucketsRequest; import software.amazon.awssdk.services.s3.model.ListBucketsResponse; /** * Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x. *

* This demo focuses on the S3 listBuckets operation to show how metrics are collected * and logged to the console for development and debugging purposes. *

* LoggingMetricPublisher is ideal for: * - Development and debugging * - Console output for troubleshooting * - Understanding what metrics are being collected * - Testing metric collection without external dependencies */ public class S3LoggingMetricPublisherDemo { private static final Logger logger = LoggerFactory.getLogger(S3LoggingMetricPublisherDemo.class); public static void main(String[] args) { S3LoggingMetricPublisherDemo demo = new S3LoggingMetricPublisherDemo(); demo.demonstrateUsage(); } /** * Demonstrates basic usage with S3Client and metrics enabled at the client level. */ private void demonstrateUsage() { // Create a LoggingMetricPublisher with default settings. The SDK logs metrics as text in a single line. // The default settings are equivalent to using `LoggingMetricPublisher.Format.PLAIN`. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Create an S3 client with metrics enabled. try (S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build()) { // Make the listBuckets request - metrics will be logged to console. ListBucketsResponse response = s3Client.listBuckets(ListBucketsRequest.builder().build()); // The next block shows the using a different LoggingMetricPublisher with a `PRETTY` format. // Since the metric publisher is added to the request using the `overrideConfiguration`, this formatting // applies only to the one request. try { s3Client.listBuckets(ListBucketsRequest.builder() .overrideConfiguration(config -> config .addMetricPublisher(LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY))) .build()); } catch (Exception e) { logger.info("Request failed with metrics logged: {}", e.getMessage()); } logger.info("Found {} buckets in your AWS account.", response.buckets().size()); } catch (Exception e) { logger.error("Error during S3 operation: {}", e.getMessage()); logger.info("Note: This is expected if AWS credentials are not configured."); } // Close the metric publisher to flush any remaining metrics. metricPublisher.close(); } } ``` Le code enregistre les informations suivantes sur la console : ``` INFO LoggingMetricPublisher - Metrics published: MetricCollection(name=ApiCall, metrics=[MetricRecord(metric=MarshallingDuration, value=PT0.005409792S), MetricRecord(metric=RetryCount, value=0), MetricRecord(metric=ApiCallSuccessful, value=true), MetricRecord(metric=OperationName, value=ListBuckets), MetricRecord(metric=EndpointResolveDuration, value=PT0.000068S), MetricRecord(metric=ApiCallDuration, value=PT0.163802958S), MetricRecord(metric=CredentialsFetchDuration, value=PT0.145686542S), MetricRecord(metric=ServiceEndpoint, value=https://s3.amazonaws.com), MetricRecord(metric=ServiceId, value=S3)], children=[MetricCollection(name=ApiCallAttempt, metrics=[MetricRecord(metric=TimeToFirstByte, value=PT0.138816S), MetricRecord(metric=SigningDuration, value=PT0.007803459S), MetricRecord(metric=ReadThroughput, value=165153.96002660287), MetricRecord(metric=ServiceCallDuration, value=PT0.138816S), MetricRecord(metric=AwsExtendedRequestId, value=e13Swj3uwn0qP1Oz+m7II5OGq7jf8xxT8H18iDfRBCQmDg+gU4ek91Xrsl8XxRLROlIzCAPQtsQF0DAAWOb8ntuKCzX2AJdj), MetricRecord(metric=HttpStatusCode, value=200), MetricRecord(metric=BackoffDelayDuration, value=PT0S), MetricRecord(metric=TimeToLastByte, value=PT0.148915667S), MetricRecord(metric=AwsRequestId, value=78AW9BM7SWR6YMGB)], children=[MetricCollection(name=HttpClient, metrics=[MetricRecord(metric=MaxConcurrency, value=50), MetricRecord(metric=AvailableConcurrency, value=0), MetricRecord(metric=LeasedConcurrency, value=1), MetricRecord(metric=ConcurrencyAcquireDuration, value=PT0.002623S), MetricRecord(metric=PendingConcurrencyAcquires, value=0), MetricRecord(metric=HttpClientName, value=Apache)], children=[])])]) INFO LoggingMetricPublisher - [4e6f2bb5] ApiCall INFO LoggingMetricPublisher - [4e6f2bb5] ┌──────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MarshallingDuration=PT0.000063S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ RetryCount=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallSuccessful=true │ INFO LoggingMetricPublisher - [4e6f2bb5] │ OperationName=ListBuckets │ INFO LoggingMetricPublisher - [4e6f2bb5] │ EndpointResolveDuration=PT0.000024375S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallDuration=PT0.018463083S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ CredentialsFetchDuration=PT0.000022334S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceEndpoint=https://s3.amazonaws.com │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceId=S3 │ INFO LoggingMetricPublisher - [4e6f2bb5] └──────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] ApiCallAttempt INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToFirstByte=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ SigningDuration=PT0.000301125S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ReadThroughput=1195591.792850103 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceCallDuration=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsExtendedRequestId=3QI1eenRuokdszWqZBmBMDUmko6FlSmHkM+CUMNMeLor7gJml4D4lv6QXUZ1zWoTgG+tHbr6yo2vHdz4h1P8PDovvtMFRCeB │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpStatusCode=200 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ BackoffDelayDuration=PT0S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToLastByte=PT0.017952625S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsRequestId=78AVFAF795AAWAXH │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] HttpClient INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MaxConcurrency=50 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AvailableConcurrency=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ LeasedConcurrency=1 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ConcurrencyAcquireDuration=PT0.00004S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ PendingConcurrencyAcquires=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpClientName=Apache │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────┘ INFO S3LoggingMetricPublisherDemo - Found 6 buckets in your AWS account. ``` ### Artefacts supplémentaires pour l'exemple Fichier Maven `pom.xml` ``` 4.0.0 com.example s3-logging-metric-publisher-demo 1.0.0 jar AWS S3 LoggingMetricPublisher Demo Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x 17 17 UTF-8 2.31.66 2.24.3 software.amazon.awssdk bom ${aws.java.sdk.version} pom import org.apache.logging.log4j log4j-bom ${log4j.version} pom import software.amazon.awssdk s3 org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-core org.apache.maven.plugins maven-compiler-plugin 3.13.0 17 17 ``` Fichier de configuration `Log4j2.xml` ``` ``` Les métriques incluent les informations temporelles, les détails du service, les noms des opérations et les codes d'état HTTP qui vous aident à comprendre les modèles d'utilisation des AWS API de votre application. ## Étapes suivantes Après l'avoir utilisé `LoggingMetricPublisher` pour le développement et le débogage, considérez les options suivantes pour les environnements de production : + Pour les applications de longue durée, utilisez-le [CloudWatchMetricPublisher](metric-pub-impl-cwmp.md)pour envoyer des métriques à Amazon à des CloudWatch fins d'analyse et d'alerte + Pour AWS Lambda les fonctions, utilisez [EmfMetricLoggingPublisher](metric-pub-impl-emf.md)pour publier des métriques au format métrique CloudWatch intégré # AWS SDK for Java 2.x: Référence complète sur les métriques Avec le AWS SDK for Java 2.x, vous pouvez collecter des statistiques auprès des clients du service dans votre application, puis publier (générer) ces statistiques [sur Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html). Ces tableaux répertorient les métriques que vous pouvez collecter et les exigences relatives à l'utilisation du client HTTP. Pour plus d'informations sur l'activation et la configuration des métriques pour le SDK, consultez la section [Activation des métriques du SDK](metrics.md). ## Métriques collectées à chaque demande | Nom des métriques | Description | Type | | --- | --- | --- | | ApiCallDuration | Durée de l'appel d'API. Cela inclut toutes les tentatives d'appel effectuées. | Durée\$1 | | ApiCallSuccessful | Vrai si l'appel d'API a réussi, faux dans le cas contraire. | Booléen | | CredentialsFetchDuration | Durée nécessaire pour récupérer les informations de signature pour l'appel d'API. | Durée\$1 | | EndpointResolveDuration | Durée de résolution du point de terminaison utilisé pour l'appel d'API. | Durée\$1 | | MarshallingDuration | Durée nécessaire pour transformer la requête du SDK en une requête HTTP. | Durée\$1 | | OperationName | Nom de l'opération de service invoquée. | String | | RetryCount | Le nombre de tentatives effectuées par le SDK lors de l'exécution de la demande. 0 signifie que la demande a fonctionné la première fois et qu'aucune nouvelle tentative n'a été tentée. Pour plus d'informations sur la configuration du comportement des nouvelles tentatives, consultez[Réessayez les stratégies](retry-strategy.md#retry-strategies). | Entier | | ServiceId | L'identifiant unique du service. | String | | ServiceEndpoint | Le point de terminaison du service. | URI | | TokenFetchDuration | Durée nécessaire pour récupérer les informations de signature pour l'appel d'API. | Durée\$1 | \$1 [java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) ## Mesures collectées pour chaque tentative de demande Chaque appel d'API peut nécessiter plusieurs tentatives avant de recevoir une réponse. Ces statistiques sont collectées pour chaque tentative. ### Indicateurs de base | Nom des métriques | Description | Type | | --- | --- | --- | | AwsExtendedRequestId | ID de demande étendu de la demande de service. | String | | AwsRequestId | ID de demande de la demande de service. | String | | BackoffDelayDuration | Durée pendant laquelle le SDK a attendu avant cette tentative d'appel d'API. La valeur est basée sur l'`[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)`ensemble défini sur le client. Consultez la [Réessayez les stratégies](retry-strategy.md#retry-strategies) section de ce guide pour plus d'informations. | Durée\$1 | | ErrorType | Type d'erreur survenue lors d'une tentative d'appel. Les valeurs admises sont les suivantes : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/metrics-list.html) | String | | ReadThroughput | Le débit de lecture du client, défini comme`NumberOfResponseBytesRead / (TTLB - TTFB)`. Cette valeur est exprimée en octets par seconde. Notez que cette métrique mesure uniquement les octets lus depuis le `ResponseTransformer` ou`AsyncResponseTransformer`. Les données lues en dehors du transformateur, par exemple lorsque le flux de réponse est renvoyé comme résultat du transformateur, ne sont pas incluses dans le calcul. | Double | | WriteThroughput | Le débit d'écriture du client, défini comme`RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)`. Cette valeur est exprimée en octets par seconde. Cette métrique mesure le taux auquel le SDK fournit le corps de la requête au client HTTP. Il exclut la configuration de la connexion, le temps de prise de contact TLS et le temps de traitement du serveur. Cette métrique n'est signalée que pour les demandes ayant un corps de streaming tel que S3 PutObject. Notez que cette métrique ne tient pas compte de la mise en mémoire tampon dans la couche client HTTP. Le débit de transmission réseau réel peut être inférieur si le client HTTP met les données en mémoire tampon avant de les envoyer. Cette métrique représente une limite supérieure du débit du réseau. | Double | | ServiceCallDuration | Durée nécessaire pour se connecter au service (ou acquérir une connexion à partir du pool de connexions), envoyer la demande sérialisée et recevoir la réponse initiale (par exemple, le code d'état HTTP et les en-têtes). Cela n'inclut pas le temps nécessaire pour lire l'intégralité de la réponse du service. | Durée\$1 | | SigningDuration | Durée de signature de la requête HTTP. | Durée\$1 | | TimeToFirstByte | Durée entre l'envoi de la requête HTTP (y compris l'acquisition d'une connexion) au service et la réception du premier octet des en-têtes de la réponse. | Durée\$1 | | TimeToLastByte | Durée entre l'envoi de la requête HTTP (y compris l'acquisition d'une connexion) au service et la réception du dernier octet de la réponse. Notez que pour ce APIs qui renvoie des réponses de streaming, cette métrique couvre le temps écoulé jusqu'à la fin de la `ResponseTransformer` ou`AsyncResponseTransformer`. | Durée\$1 | | UnmarshallingDuration | Durée de désinstallation de la réponse HTTP à une réponse du SDK. Remarque : pour les opérations de streaming, cela n'inclut pas le temps de lecture de la charge utile de réponse. | Durée\$1 | \$1 [java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) ### Métriques HTTP | Nom des métriques | Description | Type | Client HTTP requis\$1 | | --- | --- | --- | --- | | AvailableConcurrency | Nombre de demandes simultanées supplémentaires prises en charge par le client HTTP sans établir de nouvelles connexions avec le serveur cible. Pour les opérations HTTP/1, cela correspond au nombre de connexions TCP inactives établies avec le service. Pour les opérations HTTP/2, cela correspond au nombre de flux inactifs. Remarque : Cette valeur varie en fonction de l'implémentation du client HTTP : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/metrics-list.html) La valeur est limitée à une instance de client HTTP individuelle et exclut la simultanéité des autres clients HTTP de la même machine virtuelle Java. | Entier | Apache, Netty, CRT | | ConcurrencyAcquireDuration | Durée d'acquisition d'un canal à partir du pool de connexions. Pour les opérations HTTP/1, un canal équivaut à une connexion TCP. Pour les opérations HTTP/2, un canal est égal à un canal de flux HTTP/2. L'acquisition d'une nouvelle chaîne peut nécessiter du temps pour : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/metrics-list.html) | Durée\$1 | Apache, Netty, CRT | | HttpClientName | Nom du protocole HTTP utilisé pour la demande. | String | Apache, Netty, CRT | | HttpStatusCode | Code d'état de la réponse HTTP. | Entier | N’importe lequel | | LeasedConcurrency | Le nombre de requêtes que le client HTTP exécute actuellement. Pour les opérations HTTP/1, cela correspond au nombre de connexions TCP actives avec le service (à l'exclusion des connexions inactives). Pour les opérations HTTP/2, cela correspond au nombre de flux HTTP actifs associés au service (à l'exclusion de la capacité des flux inactifs). Remarque : Cette valeur varie en fonction de l'implémentation du client HTTP : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/metrics-list.html) La valeur est limitée à une instance de client HTTP individuelle et exclut la simultanéité des autres clients HTTP de la même machine virtuelle Java. | Entier | Apache, Netty, CRT | | LocalStreamWindowSize | Taille de la fenêtre HTTP/2 locale en octets pour le flux qui exécute cette demande. | Entier | Netty | | MaxConcurrency | Nombre maximal de demandes simultanées prises en charge par le client HTTP. Pour les opérations HTTP/1, cela correspond au nombre maximum de connexions TCP que le client HTTP peut regrouper. Pour les opérations HTTP/2, cela correspond au nombre maximum de flux que le client HTTP peut regrouper. Remarque : Cette valeur varie en fonction de l'implémentation du client HTTP : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/metrics-list.html) La valeur est limitée à une instance de client HTTP individuelle et exclut la simultanéité des autres clients HTTP de la même machine virtuelle Java. | Entier | Apache, Netty, CRT | | PendingConcurrencyAcquires | Nombre de demandes en attente de simultanéité de la part du client HTTP. Pour les opérations HTTP/1, cela correspond au nombre de demandes en attente d'établissement ou de retour d'une connexion TCP depuis le pool de connexions. Pour les opérations HTTP/2, cela correspond au nombre de requêtes en attente d'un nouveau flux (et éventuellement d'une nouvelle connexion HTTP/2) depuis le pool de connexions. Remarque : Cette valeur varie en fonction de l'implémentation du client HTTP : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/metrics-list.html) La valeur est limitée à une instance de client HTTP individuelle et exclut la simultanéité des autres clients HTTP de la même machine virtuelle Java. | Entier | Apache, Netty, CRT | | RemoteStreamWindowSize | Taille de la fenêtre HTTP/2 distante en octets pour le flux qui exécute cette demande. | Entier | Netty | \$1 [java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) Les termes utilisés dans la colonne signifient : + Apache : le client HTTP basé sur Apache () `[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)` + Netty : le client HTTP basé sur Netty () `[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)` + CRT : le client HTTP AWS basé sur CRT () `[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)` + N'importe lequel : la collecte de données métriques ne dépend pas du client HTTP ; cela inclut le client HTTP URLConnection basé (`[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`)