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.
# Configuration des fonctionnalités d'observabilité dans le AWS SDK for Java 2.x
La télémétrie est la collecte et la transmission automatisées de données provenant de sources distantes qui vous permettent de surveiller et d'analyser le comportement de votre système.
L'observabilité du SDK for Java 2.x fournit aux développeurs un aperçu complet de la façon dont leurs applications Java interagissent Services AWS avec elles grâce à des données de télémétrie riches qui capturent le cycle de vie complet des demandes. Ces fonctionnalités vous permettent de collecter, d'analyser et de visualiser des signaux de télémétrie tels que les métriques, les journaux et les traces, ce qui vous permet de surveiller les modèles de demandes, d'identifier les goulots d'étranglement et d'optimiser les AWS interactions de votre application pour améliorer la fiabilité et les performances.
**Topics**
+ [Métriques](metrics.md)
+ [Surveillance](monitoring-overview.md)
+ [Logging](logging-slf4j.md)
# 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.awssdkbom[2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)pomimportsoftware.amazon.awssdkcloudwatch-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.awssdkbom[2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)pomimportsoftware.amazon.awssdkemf-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.0com.examples3-logging-metric-publisher-demo1.0.0jarAWS S3 LoggingMetricPublisher DemoDemonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x1717UTF-82.31.662.24.3software.amazon.awssdkbom${aws.java.sdk.version}pomimportorg.apache.logging.log4jlog4j-bom${log4j.version}pomimportsoftware.amazon.awssdks3org.apache.logging.log4jlog4j-slf4j2-implorg.apache.logging.log4jlog4j-coreorg.apache.maven.pluginsmaven-compiler-plugin3.13.01717
```
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)`)
# AWS SDK for Java 2.x Applications de surveillance
La surveillance joue un rôle important dans le maintien de la fiabilité, de la disponibilité et des performances des applications utilisant le AWS SDK for Java 2.x. AWS fournit les outils de surveillance suivants pour surveiller le SDK for Java 2.x, signaler un problème et prendre des mesures automatiques le cas échéant :
+ *Amazon CloudWatch* surveille vos AWS ressources et les applications que vous utilisez AWS en temps réel. Vous pouvez collecter et suivre les métriques, créer des tableaux de bord personnalisés, et définir des alarmes qui vous informent ou prennent des mesures lorsqu’une métrique spécifique atteint un seuil que vous spécifiez. Par exemple, vous pouvez CloudWatch suivre l'utilisation du processeur ou d'autres indicateurs de vos EC2 instances Amazon et lancer automatiquement de nouvelles instances en cas de besoin. Pour plus d'informations, consultez le [guide de CloudWatch l'utilisateur Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/).
+ *Amazon CloudWatch Logs* vous permet de surveiller, de stocker et d'accéder à vos fichiers journaux à partir d' EC2 instances Amazon et d'autres sources. CloudTrail CloudWatch Les journaux peuvent surveiller les informations contenues dans les fichiers journaux et vous avertir lorsque certains seuils sont atteints. Vous pouvez également archiver vos données de journaux dans une solution de stockage hautement durable. Pour plus d'informations, consultez le [guide de l'utilisateur d'Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/).
+ *AWS CloudTrail*capture les appels d'API et les événements associés effectués par ou pour le compte de votre AWS compte et envoie les fichiers journaux dans un compartiment Amazon S3 que vous spécifiez. Vous pouvez identifier les utilisateurs et les comptes appelés AWS, l'adresse IP source à partir de laquelle les appels ont été effectués et la date des appels. Pour de plus amples informations, veuillez consulter le [Guide de l'utilisateur AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
# Journalisation avec le SDK pour Java 2.x
Il AWS SDK for Java 2.x utilise [SLF4J](https://www.slf4j.org/manual.html), qui est une couche d'abstraction qui permet d'utiliser l'un des nombreux systèmes de journalisation au moment de l'exécution.
Les systèmes de journalisation pris en charge incluent le Java Logging Framework et Apache [Log4j 2](https://logging.apache.org/log4j/2.x/), entre autres. Cette rubrique explique comment utiliser Log4j 2 comme système de journalisation pour travailler avec le SDK.
## Fichier de configuration Log4j 2
Vous utilisez généralement un fichier de configuration, nommé `log4j2.xml` Log4j 2. Vous trouverez ci-dessous des exemples de fichiers de configuration. Pour en savoir plus sur les valeurs utilisées dans le fichier de configuration, consultez le [manuel pour la configuration de Log4j](https://logging.apache.org/log4j/2.x/manual/configuration.html).
Le `log4j2.xml` fichier doit se trouver sur le chemin de classe au démarrage de l'application. Pour un projet Maven, placez le fichier dans le `/src/main/resources` répertoire.
Le fichier `log4j2.xml` de configuration spécifie des propriétés telles que le [niveau](https://logging.apache.org/log4j/2.x/manual/configuration.html#Loggers) de journalisation, l'endroit où la sortie de journalisation est envoyée (par exemple, [vers un fichier ou vers la console](https://logging.apache.org/log4j/2.x/manual/appenders.html)) et le [format de la sortie](https://logging.apache.org/log4j/2.x/manual/layouts.html). Le niveau de journalisation indique le niveau de détail généré par Log4j 2. [https://logging.apache.org/log4j/2.x/manual/architecture.html#](https://logging.apache.org/log4j/2.x/manual/architecture.html#) Le niveau de journalisation est défini de manière indépendante pour chaque hiérarchie. La principale hiérarchie de journalisation que vous utilisez avec le AWS SDK for Java 2.x est`software.amazon.awssdk`.
## Ajouter une dépendance à la journalisation
Pour configurer la liaison Log4j 2 pour SLF4 J dans votre fichier de compilation, utilisez ce qui suit.
------
#### [ Maven ]
Ajoutez les éléments suivants à votre `pom.xml` fichier.
```
...
org.apache.logging.log4jlog4j-slf4j2-implVERSION
...
```
------
#### [ Gradle–Kotlin DSL ]
Ajoutez ce qui suit à votre `build.gradle.kts` fichier.
```
...
dependencies {
...
implementation("org.apache.logging.log4j:log4j-slf4j2-impl:VERSION")
...
}
...
```
------
`2.20.0`À utiliser pour la version minimale de l'`log4j-slf4j2-impl`artefact. Pour la dernière version, utilisez la version publiée sur [Maven Central](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-slf4j2-impl). Remplacez *VERSION* par la version que vous utiliserez.
## Erreurs et avertissements spécifiques au SDK
Nous vous recommandons de toujours laisser la hiérarchie des enregistreurs « software.amazon.awssdk » définie sur « WARN » pour intercepter les messages importants provenant des bibliothèques clientes du SDK. Par exemple, si le client Amazon S3 détecte que votre application n'a pas correctement fermé une application `InputStream` et qu'elle est susceptible de provoquer une fuite de ressources, il le signale par le biais d'un message d'avertissement envoyé aux journaux. Il est ainsi possible de s'assurer que les messages sont enregistrés au cas où le client rencontrerait des problèmes de gestion des demandes ou des réponses.
Le `log4j2.xml` fichier suivant définit le paramètre sur `rootLogger` « WARN », ce qui entraîne l'affichage de messages d'avertissement et d'erreur provenant de tous les enregistreurs de l'application, *y compris* ceux de la hiérarchie « software.amazon.awssdk ». Vous pouvez également définir explicitement la hiérarchie de l'enregistreur « software.amazon.awssdk » sur « WARN » si elle est utilisée. ``
**Exemple de fichier de configuration Log4j2.xml**
Cette configuration enregistre les messages aux niveaux « ERROR » et « WARN » sur la console pour toutes les hiérarchies d'enregistreurs.
```
```
## Enregistrement du résumé des demandes/réponses
Chaque demande envoyée à un Service AWS génère un identifiant de AWS demande unique qui est utile si vous rencontrez un problème avec le traitement d'une demande par an Service AWS . AWS IDs les requêtes sont accessibles par programmation via [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId())des objets du SDK en cas d'échec d'un appel de service, et peuvent également être signalées via le niveau de journal « DEBUG » de l'enregistreur « software.amazon.awssdk.request ».
Le `log4j2.xml` fichier suivant permet de résumer les demandes et les réponses.
```
```
Voici un exemple de la sortie du journal:
```
2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=POST, protocol=https, host=dynamodb.us-east-1.amazonaws.com, encodedPath=/, headers=[amz-sdk-invocation-id, Content-Length, Content-Type, User-Agent, X-Amz-Target], queryParameters=[])
2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Received successful response: 200, Request ID: QS9DUMME2NHEDH8TGT9N5V53OJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended Request ID: not available
```
Si vous êtes intéressé uniquement par l'identifiant de demande, utilisez``.
## Journalisation du SDK au niveau du débogage
Si vous avez besoin de plus de détails sur le fonctionnement du SDK, vous pouvez définir le niveau de journalisation de l'`software.amazon.awssdk`enregistreur sur. `DEBUG` À ce niveau, le SDK produit une grande quantité de détails. Nous vous recommandons donc de définir ce niveau pour résoudre les erreurs à l'aide de tests d'intégration.
À ce niveau de journalisation, le SDK enregistre les informations relatives à la configuration, à la résolution des identifiants, aux intercepteurs d'exécution, à l'activité TLS de haut niveau, à la signature des demandes, etc.
Voici un échantillon d'instructions produites par le SDK au `DEBUG` niveau d'un `S3Client#listBuckets()` appel.
```
DEBUG s.a.a.r.p.AwsRegionProviderChain:57 - Unable to load region from software.amazon.awssdk.regions.providers.SystemSettingsRegionProvider@324dcd31:Unable to load region from system settings. Region must be specified either via environment variable (AWS_REGION) or system property (aws.region).
DEBUG s.a.a.c.i.h.l.ClasspathSdkHttpServiceProvider:85 - The HTTP implementation loaded is software.amazon.awssdk.http.apache.ApacheSdkHttpService@a23a01d
DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@69b2f8e5, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@6331250e, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@a10c1b5, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@644abb8f, software.amazon.awssdk.services.s3.auth.scheme.internal.S3AuthSchemeInterceptor@1a411233, software.amazon.awssdk.services.s3.endpoints.internal.S3ResolveEndpointInterceptor@70325d20, software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa, software.amazon.awssdk.services.s3.internal.handlers.StreamingRequestInterceptor@4d847d32, software.amazon.awssdk.services.s3.internal.handlers.CreateBucketInterceptor@5f462e3b, software.amazon.awssdk.services.s3.internal.handlers.CreateMultipartUploadRequestInterceptor@3d7fa3ae, software.amazon.awssdk.services.s3.internal.handlers.DecodeUrlEncodedResponseInterceptor@58065f0c, software.amazon.awssdk.services.s3.internal.handlers.GetBucketPolicyInterceptor@3605c4d3, software.amazon.awssdk.services.s3.internal.handlers.S3ExpressChecksumInterceptor@585c13de, software.amazon.awssdk.services.s3.internal.handlers.AsyncChecksumValidationInterceptor@187eb9a8, software.amazon.awssdk.services.s3.internal.handlers.SyncChecksumValidationInterceptor@726a6b94, software.amazon.awssdk.services.s3.internal.handlers.EnableTrailingChecksumInterceptor@6ad11a56, software.amazon.awssdk.services.s3.internal.handlers.ExceptionTranslationInterceptor@522b2631, software.amazon.awssdk.services.s3.internal.handlers.GetObjectInterceptor@3ff57625, software.amazon.awssdk.services.s3.internal.handlers.CopySourceInterceptor@1ee29c84, software.amazon.awssdk.services.s3.internal.handlers.ObjectMetadataInterceptor@7c8326a4]
DEBUG s.a.a.u.c.CachedSupplier:85 - (SsoOidcTokenProvider()) Cached value is stale and will be refreshed.
...
DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@51351f28, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@21618fa7, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@15f2eda3, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@34cf294c, software.amazon.awssdk.services.sso.auth.scheme.internal.SsoAuthSchemeInterceptor@4d7aaca2, software.amazon.awssdk.services.sso.endpoints.internal.SsoResolveEndpointInterceptor@604b1e1d, software.amazon.awssdk.services.sso.endpoints.internal.SsoRequestSetEndpointInterceptor@62566842]
...
DEBUG s.a.a.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=GET, protocol=https, host=portal.sso.us-east-1.amazonaws.com, encodedPath=/federation/credentials, headers=[amz-sdk-invocation-id, User-Agent, x-amz-sso_bearer_token], queryParameters=[role_name, account_id])
DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: smithy.api#noAuth
DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to portal.sso.us-east-1.amazonaws.com/18.235.195.183:443 with timeout 2000
...
DEBUG s.a.a.requestId:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available
DEBUG s.a.a.request:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available
DEBUG s.a.a.u.c.CachedSupplier:85 - (software.amazon.awssdk.services.sso.auth.SsoCredentialsProvider@b965857) Successfully refreshed cached value. Next Prefetch Time: 2024-04-25T22:03:10.097Z. Next Stale Time: 2024-04-25T22:05:30Z
DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Interceptor 'software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa' modified the message with its modifyHttpRequest method.
...
DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: aws.auth#sigv4
...
DEBUG s.a.a.a.s.Aws4Signer:85 - AWS4 Canonical Request: GET
...
DEBUG s.a.a.h.a.a.i.s.DefaultV4RequestSigner:85 - AWS4 String to sign: AWS4-HMAC-SHA256
20240425T210631Z
20240425/us-east-1/s3/aws4_request
aafb7784627fa7a49584256cb746279751c48c2076f813259ef767ecce304d64
DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to s3.us-east-1.amazonaws.com/52.217.41.86:443 with timeout 2000
...
```
Le `log4j2.xml` fichier suivant configure la sortie précédente.
```
```
## Activer l'enregistrement des câbles
Il peut être utile de voir les demandes et réponses exactes que le SDK for Java 2.x envoie et reçoit. Si vous avez besoin d'accéder à ces informations, vous pouvez les activer temporairement en ajoutant la configuration nécessaire en fonction du client HTTP utilisé par le client de service.
Par défaut, les clients de service synchrones, tels que le [S3Client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html), utilisent un Apache sous-jacent HttpClient, et les clients de service asynchrones, tels que le [S3 AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html), utilisent un client HTTP non bloquant Netty.
Voici une liste des clients HTTP que vous pouvez utiliser pour les deux catégories de clients de service :
| Clients HTTP synchrones | Clients HTTP asynchrones |
| --- | --- |
| [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) (par défaut) | [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) (par défaut) |
| [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) | [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html) |
| [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) | |
| [Apache 5 HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) |
Consultez l'onglet approprié ci-dessous pour connaître les paramètres de configuration que vous devez ajouter en fonction du client HTTP sous-jacent.
**Avertissement**
Nous vous recommandons d'utiliser uniquement la journalisation du réseau filaire à des fins de débogage. Désactivez-la dans vos environnements de production, car elle peut consigner des données sensibles. Elle enregistre l'intégralité de la demande ou de la réponse sans chiffrement, même pour un appel HTTPS. Pour les demandes ou les réponses volumineuses (par exemple, pour télécharger un fichier Amazon S3) ou pour les réponses, l'enregistrement détaillé des connexions peut également avoir un impact significatif sur les performances de votre application.
------
#### [ ApacheHttpClient ]
Ajoutez l'enregistreur « org.apache.http.wire » au fichier de `log4j2.xml` configuration et réglez le niveau sur « DEBUG ».
Le `log4j2.xml` fichier suivant active la journalisation complète pour Apache HttpClient.
```
```
Une dépendance Maven supplémentaire à l'égard de l'`log4j-1.2-api`artefact est requise pour l'enregistrement des connexions avec Apache, car celui-ci utilise la version 1.2 sous le capot.
L'ensemble complet des dépendances Maven pour log4j 2, y compris l'enregistrement des connexions pour le client HTTP Apache, est présenté dans les extraits de fichier de compilation suivants.
**Maven**
```
...
...
org.apache.logging.log4jlog4j-bomVERSIONpomimport
...
org.apache.logging.log4jlog4j-slf4j2-implorg.apache.logging.log4jlog4j-1.2-api
...
```
**Gradle-Kotlin DSL**
```
...
dependencies {
...
implementation(platform("org.apache.logging.log4j:log4j-bom:VERSION"))
implementation("org.apache.logging.log4j:log4j-slf4j2-impl")
implementation("org.apache.logging.log4j:log4j-1.2-api")
}
...
```
`2.20.0`À utiliser pour la version minimale de l'`log4j-bom`artefact. Pour la dernière version, utilisez la version publiée sur [Maven Central](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-bom). Remplacez *VERSION* par la version que vous utiliserez.
------
#### [ Apache5HttpClient ]
Ajoutez l'enregistreur « org.apache.hc.client5.http.wire » au fichier de configuration et définissez le niveau sur « DEBUG ». `log4j2.xml`
Le `log4j2.xml` fichier suivant active l'enregistrement filaire complet pour Apache5 HttpClient.
```
```
------
#### [ UrlConnectionHttpClient ]
Pour enregistrer les informations relatives aux clients du service qui utilisent le`UrlConnectionHttpClient`, créez d'abord un `logging.properties` fichier avec le contenu suivant :
```
handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=FINEST
sun.net.www.protocol.http.HttpURLConnection.level=ALL
```
Définissez la propriété du système JVM suivante avec le chemin complet de `logging.properties` :
```
-Djava.util.logging.config.file=/full/path/to/logging.properties
```
Cette configuration enregistrera uniquement les en-têtes de la demande et de la réponse, par exemple :
```
FINE: sun.net.www.MessageHeader@35a9782c11 pairs: {GET /fileuploadtest HTTP/1.1: null}{amz-sdk-invocation-id: 5f7e707e-4ac5-bef5-ba62-00d71034ffdc}{amz-sdk-request: attempt=1; max=4}{Authorization: AWS4-HMAC-SHA256 Credential=/20220927/us-east-1/s3/aws4_request, SignedHeaders=amz-sdk-invocation-id;amz-sdk-request;host;x-amz-content-sha256;x-amz-date;x-amz-te, Signature=e367fa0bc217a6a65675bb743e1280cf12fbe8d566196a816d948fdf0b42ca1a}{User-Agent: aws-sdk-java/2.17.230 Mac_OS_X/12.5 OpenJDK_64-Bit_Server_VM/25.332-b08 Java/1.8.0_332 vendor/Amazon.com_Inc. io/sync http/UrlConnection cfg/retry-mode/legacy}{x-amz-content-sha256: UNSIGNED-PAYLOAD}{X-Amz-Date: 20220927T133955Z}{x-amz-te: append-md5}{Host: tkhill-test1.s3.amazonaws.com}{Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2}{Connection: keep-alive}
FINE: sun.net.www.MessageHeader@70a36a6611 pairs: {null: HTTP/1.1 200 OK}{x-amz-id-2: sAFeZDOKdUMsBbkdjyDZw7P0oocb4C9KbiuzfJ6TWKQsGXHM/dFuOvr2tUb7Y1wEHGdJ3DSIxq0=}{x-amz-request-id: P9QW9SMZ97FKZ9X7}{Date: Tue, 27 Sep 2022 13:39:57 GMT}{Last-Modified: Tue, 13 Sep 2022 14:38:12 GMT}{ETag: "2cbe5ad4a064cedec33b452bebf48032"}{x-amz-transfer-encoding: append-md5}{Accept-Ranges: bytes}{Content-Type: text/plain}{Server: AmazonS3}{Content-Length: 67}
```
Pour voir les request/response corps, ajoutez-les `-Djavax.net.debug=all` aux propriétés de la JVM. Cette propriété supplémentaire enregistre de nombreuses informations, y compris toutes les informations SSL.
Dans la console ou le fichier journal, recherchez `"GET"` ou accédez rapidement `"POST"` à la section du journal contenant les demandes et réponses réelles. `"Plaintext before ENCRYPTION"`Recherchez des demandes et des réponses `"Plaintext after DECRYPTION"` pour voir le texte intégral des en-têtes et des corps.
------
#### [ NettyNioAsyncHttpClient ]
Si votre client de service asynchrone utilise la valeur par défaut`NettyNioAsyncHttpClient`, ajoutez deux enregistreurs supplémentaires à votre `log4j2.xml` fichier pour enregistrer les en-têtes HTTP et les corps de demande/réponse.
```
```
Voici un `log4j2.xml` exemple complet :
```
```
Ces paramètres enregistrent tous les détails et le request/response corps de l'en-tête.
------
#### [ AwsCrtAsyncHttpClient/AwsCrtHttpClient ]
Si vous avez configuré votre client de service pour utiliser une instance d'un client HTTP AWS CRT, vous pouvez enregistrer les détails en définissant les propriétés du système JVM ou par programmation.
| |
| --- |
| Log to a file at "Debug" level |
| À l'aide des propriétés du système :
// Execute this statement before constructing the SDK service client. Log.initLoggingToStdout(Log.LogLevel.Trace);
|
Pour des raisons de sécurité, au niveau « Trace », les clients HTTP AWS basés sur CRT enregistrent uniquement les en-têtes de réponse. Les en-têtes de demande, les corps de demande et les corps de réponse ne sont pas enregistrés.
------