Fichier de configuration Log4j 2 Ajouter une dépendance à la journalisation Erreurs et avertissements spécifiques au SDK Enregistrement du résumé des demandes/réponses Journalisation du SDK au niveau du débogage Activer l'enregistrement des câbles

Journalisation avec le SDK pour Java 2.x

Il AWS SDK for Java 2.x utilise SLF4J, 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, 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.

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 <project-dir>/src/main/resources répertoire.

Le fichier log4j2.xml de configuration spécifie des propriétés telles que le niveau de journalisation, l'endroit où la sortie de journalisation est envoyée (par exemple, vers un fichier ou vers la console) et le format de la sortie. Le niveau de journalisation indique le niveau de détail généré par Log4j 2. Log4j 2 prend en charge le concept de hiérarchies de journalisation multiples. 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 estsoftware.amazon.awssdk.

Ajouter une dépendance à la journalisation

Pour configurer la liaison Log4j 2 pour SLF4J dans votre fichier de compilation, utilisez ce qui suit.

2.20.0À utiliser pour la version minimale de l'log4j-slf4j2-implartefact. Pour la dernière version, utilisez la version publiée sur Maven Central. 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. <Root level="ERROR">

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.


<Configuration status="WARN">
 <Appenders>
  <Console name="ConsoleAppender" target="SYSTEM_OUT">
   <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n" />
  </Console>
 </Appenders>

 <Loggers>
  <Root level="WARN">
   <AppenderRef ref="ConsoleAppender"/>
  </Root>
 </Loggers>
</Configuration>

Enregistrement du résumé des demandes/réponses

Chaque demande envoyée à un AWS service 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 AWS service . AWS Les identifiants de demande sont accessibles par programmation via SdkServiceExceptiondes objets du SDK en cas d'échec d'un appel de service, et peuvent également être signalés 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.


<Configuration status="WARN">
 <Appenders>
  <Console name="ConsoleAppender" target="SYSTEM_OUT">
   <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n" />
  </Console>
 </Appenders>

 <Loggers>
  <Root level="ERROR">
   <AppenderRef ref="ConsoleAppender"/>
  </Root>
  <Logger name="software.amazon.awssdk" level="WARN" />
  <Logger name="software.amazon.awssdk.request" level="DEBUG" />
 </Loggers>
</Configuration>

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<Logger name="software.amazon.awssdk.requestId" level="DEBUG" />.

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


<Configuration status="WARN">
    <Appenders>
        <Console name="ConsoleAppender" target="SYSTEM_OUT">
            <PatternLayout pattern="%-5p %c{1.}:%L - %m%n" />
        </Console>
    </Appenders>

    <Loggers>
        <Root level="WARN">
            <AppenderRef ref="ConsoleAppender"/>
        </Root>
        <Logger name="software.amazon.awssdk" level="DEBUG" />
    </Loggers>
</Configuration>

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, utilisent un Apache sous-jacent HttpClient, et les clients de service asynchrones, tels que le S3 AsyncClient, 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(par défaut)	NettyNioAsyncHttpClient(par défaut)
UrlConnectionHttpClient	AwsCrtAsyncHttpClient

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.


<Configuration status="WARN">
 <Appenders>
  <Console name="ConsoleAppender" target="SYSTEM_OUT">
   <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n" />
  </Console>
 </Appenders>

 <Loggers>
  <Root level="WARN">
   <AppenderRef ref="ConsoleAppender"/>
  </Root>
  <Logger name="software.amazon.awssdk" level="WARN" />
  <Logger name="software.amazon.awssdk.request" level="DEBUG" />
  <Logger name="org.apache.http.wire" level="DEBUG" />
 </Loggers>
</Configuration>

Une dépendance Maven supplémentaire à l'égard de l'log4j-1.2-apiartefact 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


...
<dependencyManagement>
    ...
    <dependencies>
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-bom</artifactId>
            <version>VERSION</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
     </dependencies>
</dependencyManagement>
...
<!-- The following is needed for Log4j2 with SLF4J -->
<dependency>
   <groupId>org.apache.logging.log4j</groupId>
   <artifactId>log4j-slf4j2-impl</artifactId>
</dependency>

<!-- The following is needed for Apache HttpClient wire logging -->
<dependency>
   <groupId>org.apache.logging.log4j</groupId>
   <artifactId>log4j-1.2-api</artifactId>
</dependency>
...

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-bomartefact. Pour la dernière version, utilisez la version publiée sur Maven Central. Remplacez VERSION par la version que vous utiliserez.

UrlConnectionHttpClient

Pour enregistrer les informations relatives aux clients du service qui utilisent leUrlConnectionHttpClient, 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 :


<Request>  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=<deleted>/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}
<Response> 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 corps de demande/réponse, 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éfautNettyNioAsyncHttpClient, ajoutez deux enregistreurs supplémentaires à votre log4j2.xml fichier pour enregistrer les en-têtes HTTP et les corps de demande/réponse.


<Logger name="io.netty.handler.logging" level="DEBUG" />
<Logger name="io.netty.handler.codec.http2.Http2FrameLogger" level="DEBUG" />

Voici un log4j2.xml exemple complet :


<Configuration status="WARN">
    <Appenders>
        <Console name="ConsoleAppender" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n" />
        </Console>
    </Appenders>

    <Loggers>
        <Root level="WARN">
            <AppenderRef ref="ConsoleAppender"/>
        </Root>
        <Logger name="software.amazon.awssdk" level="WARN" />
        <Logger name="software.amazon.awssdk.request" level="DEBUG" />
        <Logger name="io.netty.handler.logging" level="DEBUG" />
        <Logger name="io.netty.handler.codec.http2.Http2FrameLogger" level="DEBUG" />
    </Loggers>
</Configuration>

Ces paramètres enregistrent tous les détails de l'en-tête et les corps de demande/réponse.

AwsCrtAsyncHttpClient

Si vous avez configuré votre client de service pour utiliser une instance deAwsCrtAsyncHttpClient, 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 :


-Daws.crt.log.level=Trace 
-Daws.crt.log.destination=File 
-Daws.crt.log.filename=<path to file>

Programmatiquement :


import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK service client.
Log.initLoggingToFile(Log.LogLevel.Trace, "<path to file>");

Log to the console at "Debug" level

À l'aide des propriétés du système :


-Daws.crt.log.level=Trace 
-Daws.crt.log.destination=Stdout

Programmatiquement :


import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK service client.
Log.initLoggingToStdout(Log.LogLevel.Trace);

Pour des raisons de sécurité, au niveau « Trace », seuls les AwsCrtAsyncHttpClient en-têtes de réponse sont enregistrés. Les en-têtes de demande, les corps de demande et les corps de réponse ne sont pas enregistrés.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Nouvelle tentative

Définissez le TTL de la JVM pour les recherches de noms DNS