Fichier de configuration Log4j 2 Ajouter une dépendance de journalisation SDK-specific erreurs et avertissements Request/response journalisation récapitulative Debug-level Journalisation du SDK Activer l'enregistrement des câbles

Journalisation avec le SDK pour Java 2.x

Il AWS SDK for Java 2.x utilise SLF4J, une couche d'abstraction qui permet d'utiliser l'un des nombreux systèmes de journalisation lors 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 dans le chemin de classe au démarrage de votre 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 spécifie 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 hiérarchie de journalisation principale que vous utilisez avec le AWS SDK for Java 2.x estsoftware.amazon.awssdk.

Ajouter une dépendance de journalisation

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

À utiliser 2.20.0 pour la version minimale de l'log4j-slf4j2-implartefact. Pour la dernière version, utilisez la version publiée sur Maven Central. VERSIONRemplacez-la par la version que vous allez utiliser.

SDK-specific erreurs et avertissements

Nous vous recommandons de toujours laisser la hiérarchie des enregistreurs « software.amazon.awssdk » réglée sur « WARN » pour détecter tout message important provenant des bibliothèques clientes du SDK. Par exemple, si le client Amazon S3 détecte que votre application n'a pas été correctement fermée InputStream et qu'il est possible qu'il y ait une fuite de ressources, il le signale par un message d'avertissement dans les 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 des enregistreurs « software.amazon.awssdk » sur « WARN » si elle est utilisée. <Root level="ERROR">

Exemple Log4j2.xml de fichier de configuration

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>

Request/response journalisation récapitulative

Chaque demande adressée à an Service AWS génère un identifiant de AWS demande unique qui est utile si vous rencontrez un problème avec la façon dont an Service AWS traite une demande. AWS Les ID de demande sont accessibles par programmation via SdkServiceException des objets du SDK pour tout appel de service échoué, 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écapituler 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'ID de demande, utilisez<Logger name="software.amazon.awssdk.requestId" level="DEBUG" />.

Debug-level Journalisation du SDK

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 génère 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 des informations sur la configuration, la résolution des informations d'identification, les intercepteurs d'exécution, l'activité TLS de haut niveau, la signature des demandes, etc.

Voici un exemple d'instructions sorties 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 les réponses exactes que le SDK pour 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, et les clients de service asynchrones HttpClient, tels que le S3AsyncClient, 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
Apache5HttpClient (par défaut)	NettyNioAsyncHttpClient (par défaut)
UrlConnectionHttpClient	AwsCrtAsyncHttpClient
AwsCrtHttpClient
ApacheHttpClient

Consultez l'onglet approprié ci-dessous pour connaître les paramètres de configuration à 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 volumineuses (par exemple, pour télécharger un fichier Amazon S3) ou les réponses, la journalisation détaillée des fils 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 des câbles 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 supplémentaire de Maven à l'égard de l'log4j-1.2-apiartefact est requise pour la journalisation des câbles 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 la journalisation des câbles pour le client HTTP Apache, est illustré dans les extraits de fichier de construction 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>
...

DSL Gradle-Kotlin


...
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")
}
...

À utiliser 2.20.0 pour la version minimale de l'log4j-bomartefact. Pour la dernière version, utilisez la version publiée sur Maven Central. VERSIONRemplacez-la par la version que vous allez utiliser.

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 la journalisation complète des câbles pour Apache5 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.hc.client5.http.wire" level="DEBUG" />
 </Loggers>
</Configuration>

UrlConnectionHttpClient

Pour enregistrer les informations relatives aux clients du service qui utilisent leUrlConnectionHttpClient, créez d'abord un logging.properties fichier contenant 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é 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 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 de journal 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 et les corps HTTP. request/response


<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 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 AWS CRT-based HTTP, 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 », les clients AWS CRT-based HTTP 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.

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

Surveillance

Points de terminaison