Archivo de configuración de Log4j 2 Añadir dependencia de registro Errores y advertencias específicos del SDK Registro de resumen de solicitud/respuesta Registro del SDK a nivel de depuración Habilite el registro de cables

Inicio de sesión con SDK para Java 2.x

AWS SDK for Java 2.x Utiliza SLF4J, que es una capa de abstracción que permite el uso de cualquiera de los varios sistemas de registro en tiempo de ejecución.

Los sistemas de registro compatibles incluyen Java Logging Framework y Apache Log4j 2, entre otros. En este tema se muestra cómo utilizar Log4j 2 como sistema de registro para trabajar con el SDK.

Archivo de configuración de Log4j 2

Por lo general, se utiliza un archivo de configuración, cuyo nombre es log4j2.xml con Log4j 2. A continuación, se muestran ejemplos de archivos de configuración. Para obtener más información acerca de los valores que se utilizan en el archivo de configuración, consulte el manual de configuración de Log4j.

El archivo log4j2.xml debe estar en la ruta de clases cuando se inicie la aplicación. Para un proyecto de Maven, coloque el archivo en el directorio <project-dir>/src/main/resources.

El archivo de configuración log4j2.xml especifica propiedades como el nivel de registro, dónde se envía la salida de registro (por ejemplo, a un archivo o a la consola) y el formato de la salida. El nivel de registro especifica el nivel de detalle que genera Log4j 2. Log4j 2 admite el concepto de varias jerarquías de registro. El nivel de registro se define de forma independiente para cada jerarquía. La jerarquía de registro principal que se utiliza con el es. AWS SDK for Java 2.x software.amazon.awssdk

Añadir dependencia de registro

Para configurar el enlace Log4j 2 para SLF4J en su archivo de compilación, utilice lo siguiente.

Utilice 2.20.0 para la versión mínima del artefacto log4j-slf4j2-impl. Para obtener la última versión, utilice la versión publicada en Maven Central. Sustituya VERSIÓN por la que vaya a utilizar.

Errores y advertencias específicos del SDK

Le recomendamos que deje siempre la jerarquía del registrador "software.amazon.awssdk" establecida en "WARN" para captar cualquier mensaje importante de las bibliotecas cliente del SDK. Por ejemplo, si el cliente Amazon S3 detecta que su aplicación no ha cerrado correctamente un InputStream y podría estar desperdiciando recursos, el cliente S3 informa de ello a través de un mensaje de advertencia a los archivos log. Esto también garantiza que se registren los mensajes si el cliente tiene algún problema con el tratamiento de las solicitudes o respuestas.

El siguiente archivo log4j2.xml establece rootLogger en «WARN», lo que genera mensajes de advertencia y de nivel de error de todos los registradores de la aplicación, incluidos los de la jerarquía «software.amazon.awssdk». Como alternativa, puede establecer explícitamente la jerarquía del registrador "software.amazon.awssdk" en "WARN" si se utiliza <Root level="ERROR">.

Ejemplo de archivo de configuración Log4j2.xml

Esta configuración registrará los mensajes en los niveles «ERROR» y «WARN» en la consola para todas las jerarquías de registradores.


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

Registro de resumen de solicitud/respuesta

Cada solicitud a an Servicio de AWS genera un identificador de AWS solicitud único que resulta útil si tienes algún problema con la forma en Servicio de AWS que an gestiona una solicitud. AWS Se puede acceder a los ID de solicitud mediante programación a través de SdkServiceExceptionlos objetos del SDK para cualquier llamada de servicio fallida, y también se pueden informar a través del nivel de registro «DEBUG» del registrador «software.amazon.awssdk.request».

El siguiente archivo log4j2.xml habilita un resumen de solicitudes y respuestas.


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

Este es un ejemplo del resultado del registro:


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 solo le interesa el identificador de solicitud, utilice <Logger name="software.amazon.awssdk.requestId" level="DEBUG" />.

Registro del SDK a nivel de depuración

Si necesitas más detalles sobre lo que hace el SDK, puedes configurar el nivel de registro del software.amazon.awssdk registrador en. DEBUG En este nivel, el SDK genera una gran cantidad de detalles, por lo que te recomendamos que establezcas este nivel para resolver los errores mediante pruebas de integración.

En este nivel de registro, el SDK registra información sobre la configuración, la resolución de credenciales, los interceptores de ejecución, la actividad de TLS de alto nivel, la firma de solicitudes y mucho más.

La siguiente es una muestra de las sentencias que genera el SDK a DEBUG nivel de una S3Client#listBuckets() llamada.


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

El siguiente log4j2.xml archivo configura la salida anterior.


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

Habilite el registro de cables

Puede ser útil ver exactamente las solicitudes y respuestas que el SDK para Java 2.x envía y recibe. Si necesita acceder a esta información, puede habilitarla temporalmente añadiendo la configuración necesaria en función del cliente HTTP que utilice el cliente del servicio.

De forma predeterminada, los clientes de servicios síncronos, como el S3Client, utilizan un Apache HttpClient subyacente y los clientes de servicios asíncronos, como el S3 AsyncClient, utilizan un cliente HTTP Netty sin bloqueo.

Este es un desglose de los clientes HTTP que puede utilizar para las dos categorías de clientes de servicio:

Clientes HTTP síncronos	Clientes HTTP asíncronos
ApacheHttpClient(predeterminado)	NettyNioAsyncHttpClient(predeterminado)
UrlConnectionHttpClient	AwsCrtAsyncHttpClient

Consulte la pestaña correspondiente a continuación para ver los ajustes de configuración que necesite añadir en función del cliente HTTP subyacente.

aviso

Le recomendamos que solo utilice en registro en red para fines de depuración. Deshabilítelo en sus entornos de producción, ya que puede registrar información confidencial. Registra la solicitud o respuesta completa sin cifrado, incluso para una llamada HTTPS. En el caso de solicitudes o respuestas de gran tamaño (por ejemplo, para cargar un archivo Amazon S3), el registro detallado de las conexiones también puede afectar considerablemente al rendimiento de la aplicación.

ApacheHttpClient

Añada el registrador «org.apache.http.wire» al archivo de configuración log4j2.xml y establezca el nivel en «DEBUG».

El siguiente log4j2.xml archivo activa el registro completo de cables para 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>

Se requiere una dependencia adicional de Maven en el artefacto log4j-1.2-api para el registro de cables con Apache, ya que utiliza 1.2 internamente.

El conjunto completo de dependencias de Maven para log4j 2, incluido el registro de conexiones para el cliente HTTP Apache, se muestra en los siguientes fragmentos de archivos de compilación.

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

Utilice 2.20.0 para la versión mínima del artefacto log4j-bom. Para obtener la última versión, utilice la versión publicada en Maven Central. Sustituya VERSIÓN por la que vaya a utilizar.

UrlConnectionHttpClient

Para registrar los detalles de los clientes del servicio que utilizan la UrlConnectionHttpClient, cree primero un archivo logging.properties con el siguiente contenido:


handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=FINEST
sun.net.www.protocol.http.HttpURLConnection.level=ALL

Defina la siguiente propiedad del sistema JVM con la ruta completa de logging.properties:


-Djava.util.logging.config.file=/full/path/to/logging.properties

Esta configuración registrará únicamente los encabezados de la solicitud y la respuesta, por ejemplo:


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

Para ver los cuerpos de la solicitud/respuesta, agregue -Djavax.net.debug=all a las propiedades de la JVM. Esta propiedad adicional registra una gran cantidad de información, incluida toda la información de SSL.

En la consola de registro o en el archivo de registro, busque "GET" o "POST" para ir rápidamente a la sección del registro que contiene las solicitudes y respuestas reales. Busque "Plaintext before ENCRYPTION" para las solicitudes y "Plaintext after DECRYPTION" para las respuestas para ver el texto completo de las cabeceras y los contenidos.

NettyNioAsyncHttpClient

Si su cliente de servicio asíncrono utiliza el NettyNioAsyncHttpClient predeterminado, añada dos registradores adicionales al su archivo log4j2.xml para registrar los encabezados HTTP y los textos de las solicitudes o respuestas.


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

Este es un ejemplo completo de log4j2.xml:


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

Esta configuración registra todos los detalles del encabezado y los contenidos de la solicitud/respuesta.

AwsCrtAsyncHttpClient

Si ha configurado su cliente de servicio para que utilice una instancia de AwsCrtAsyncHttpClient, puede registrar los detalles configurando las propiedades del sistema JVM o mediante programación.

Log to a file at "Debug" level

Uso de las propiedades del sistema:


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

Mediante programación:


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

Uso de las propiedades del sistema:


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

Mediante programación:


import software.amazon.awssdk.crt.Log;

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

Por motivos de seguridad, en el nivel de «Rastreo», el AwsCrtAsyncHttpClient solo registra los encabezados de respuesta. Los encabezados de las solicitudes, los textos de las solicitudes y los de respuesta no se registran.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Reintentos

Configurar el TTL de JVM para las búsquedas de nombres DNS