Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Registrazione con l'SDK per Java 2.x

AWS SDK for Java 2.x Utilizza SLF4J, che è un livello di astrazione che consente l'uso di uno qualsiasi dei diversi sistemi di registrazione in fase di esecuzione.

I sistemi di registrazione supportati includono Java Logging Framework e Apache Log4j 2, tra gli altri. https://logging.apache.org/log4j/2.x/ Questo argomento mostra come utilizzare Log4j 2 come sistema di registrazione per lavorare con l'SDK.

File di configurazione Log4j 2

In genere si utilizza un file di configurazione, denominato log4j2.xml Log4j 2. File di configurazione di esempio sono mostrati di seguito. Per ulteriori informazioni sui valori utilizzati nel file di configurazione, consulta il manuale per la configurazione di Log4j.

Il log4j2.xml file deve trovarsi nel classpath all'avvio dell'applicazione. Per un progetto Maven, inserisci il file nella directory. <project-dir>/src/main/resources

Il file di log4j2.xml configurazione specifica proprietà come il livello di registrazione, il luogo in cui viene inviato l'output di registrazione (ad esempio, a un file o alla console) e il formato dell'output. Il livello di registrazione specifica il livello di dettaglio generato da Log4j 2. Log4j 2 supporta il concetto di gerarchie di registrazione multiple. Il livello di registrazione è impostato in modo indipendente per ogni gerarchia. La gerarchia di registrazione principale che usi con è. AWS SDK for Java 2.x software.amazon.awssdk

Aggiungi dipendenza dalla registrazione

Per configurare l'associazione Log4j 2 per SLF4J nel file di build, usa quanto segue.

Maven

Aggiungi i seguenti elementi al tuo file. pom.xml

...
<dependency>
   <groupId>org.apache.logging.log4j</groupId>
   <artifactId>log4j-slf4j2-impl</artifactId>
   <version>VERSION</version>
</dependency>
...

Gradle–Kotlin DSL

Aggiungi quanto segue al tuo build.gradle.kts file.

...
dependencies {
    ...
    implementation("org.apache.logging.log4j:log4j-slf4j2-impl:VERSION")
    ...
}
...

Usalo 2.20.0 per la versione minima dell'log4j-slf4j2-implartefatto. Per la versione più recente, usa la versione pubblicata su Maven central. Sostituisci VERSION con la versione che utilizzerai.

SDK-specific errori e avvertenze

Ti consigliamo di lasciare sempre la gerarchia dei logger «software.amazon.awssdk» impostata su «WARN» per rilevare eventuali messaggi importanti dalle librerie client dell'SDK. Ad esempio, se il client Amazon S3 rileva che l'applicazione non è stata chiusa correttamente InputStream e potrebbe perdere risorse, il client S3 lo segnala tramite un messaggio di avviso nei log. Questo garantisce inoltre che i messaggi vengono registrati se il client presenta problemi di gestione delle richieste o delle risposte.

Il log4j2.xml file seguente imposta «WARN», il rootLogger che causa l'emissione di messaggi di avviso e di errore da tutti i logger dell'applicazione, inclusi quelli nella gerarchia «software.amazon.awssdk». In alternativa, puoi impostare esplicitamente la gerarchia dei logger «software.amazon.awssdk» su «WARN», se utilizzata. <Root level="ERROR">

File di configurazione di esempio Log4j2.xml

Questa configurazione registrerà i messaggi ai livelli «ERROR» e «WARN» nella console per tutte le gerarchie di logger.

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

Ogni richiesta a an Servizio AWS genera un ID di AWS richiesta univoco utile in caso di problemi con il modo in cui an Servizio AWS gestisce una richiesta. AWS gli ID di richiesta sono accessibili a livello di codice tramite SdkServiceException oggetti nell'SDK per qualsiasi chiamata di servizio non riuscita e possono anche essere segnalati tramite il livello di registro «DEBUG» del logger «software.amazon.awssdk.request».

Il file seguente consente un riepilogo delle richieste e delle risposte. 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="ERROR">
   <AppenderRef ref="ConsoleAppender"/>
  </Root>
  <Logger name="software.amazon.awssdk" level="WARN" />
  <Logger name="software.amazon.awssdk.request" level="DEBUG" />
 </Loggers>
</Configuration>

Di seguito è riportato un esempio di output del log:

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

Se sei interessato solo all'uso dell'ID della richiesta<Logger name="software.amazon.awssdk.requestId" level="DEBUG" />.

Debug-level Registrazione SDK

Se hai bisogno di maggiori dettagli su ciò che sta facendo l'SDK, puoi impostare il livello di registrazione del logger su. software.amazon.awssdk DEBUG A questo livello, l'SDK fornisce una grande quantità di dettagli, quindi ti consigliamo di impostare questo livello per risolvere gli errori utilizzando i test di integrazione.

A questo livello di registrazione, l'SDK registra le informazioni sulla configurazione, la risoluzione delle credenziali, gli intercettatori di esecuzione, l'attività TLS di alto livello, la firma delle richieste e molto altro.

Di seguito è riportato un esempio di istruzioni emesse dall'SDK a livello per una chiamata. DEBUG S3Client#listBuckets()

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

Il log4j2.xml file seguente configura l'output precedente.

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

Abilita la registrazione via cavo

Può essere utile visualizzare le richieste e le risposte esatte inviate e ricevute dall'SDK per Java 2.x. Se è necessario accedere a queste informazioni, è possibile abilitarle temporaneamente aggiungendo la configurazione necessaria in base al client HTTP utilizzato dal client di servizio.

Per impostazione predefinita, i client di servizio sincroni, come S3Client, utilizzano un Apache sottostante, mentre i client di servizio asincroni HttpClient, come il S3AsyncClient, utilizzano un client HTTP Netty non bloccante.

Ecco una ripartizione dei client HTTP che puoi utilizzare per le due categorie di client di servizio:

Consulta la scheda appropriata di seguito per le impostazioni di configurazione da aggiungere in base al client HTTP sottostante.

ApacheHttpClient

Aggiungete il logger «org.apache.http.wire» al file di configurazione e impostate il log4j2.xml livello su «DEBUG».

Il seguente log4j2.xml file attiva la registrazione completa per 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>

È necessaria un'ulteriore dipendenza Maven dall'log4j-1.2-apiartefatto per la registrazione cablata con Apache poiché utilizza 1.2 sotto il cofano.

Il set completo di dipendenze Maven per log4j 2, inclusa la registrazione via cavo per il client HTTP Apache, è mostrato nei seguenti frammenti di file di build.

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

Usalo 2.20.0 per la versione minima dell'artefatto. log4j-bom Per la versione più recente, usa la versione pubblicata su Maven central. Sostituisci VERSION con la versione che utilizzerai.

Apache5HttpClient

Aggiungi il logger «org.apache.hc.client5.http.wire» al file di configurazione e imposta il livello su «DEBUG». log4j2.xml

log4j2.xmlIl seguente file attiva la registrazione completa per 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

Per registrare i dettagli dei client di servizio che utilizzano ilUrlConnectionHttpClient, crea innanzitutto un logging.properties file con i seguenti contenuti:

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

Imposta la seguente proprietà del sistema JVM con il percorso completo di: logging.properties

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

Questa configurazione registrerà solo le intestazioni della richiesta e della risposta, ad esempio:

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

Per vedere i request/response corpi, aggiungi -Djavax.net.debug=all le proprietà della JVM. Questa proprietà aggiuntiva registra una grande quantità di informazioni, incluse tutte le informazioni SSL.

Nella console di registro o nel file di registro, cerca "GET" o vai rapidamente "POST" alla sezione del registro contenente le richieste e le risposte effettive. "Plaintext before ENCRYPTION"Cerca le richieste e le risposte "Plaintext after DECRYPTION" per visualizzare il testo completo delle intestazioni e del corpo.

NettyNioAsyncHttpClient

Se il tuo client di servizio asincrono utilizza l'impostazione predefinitaNettyNioAsyncHttpClient, aggiungi due logger aggiuntivi al tuo log4j2.xml file per registrare le intestazioni e i corpi HTTP. request/response

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

Ecco un esempio completo: 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>

Queste impostazioni registrano tutti i dettagli e i request/response corpi delle intestazioni.

AwsCrtAsyncHttpClient/AwsCrtHttpClient

Se hai configurato il tuo client di servizio per utilizzare un'istanza di un client AWS CRT-based HTTP, puoi registrare i dettagli impostando le proprietà del sistema JVM o a livello di codice.

Log to a file at "Debug" level
Utilizzo delle proprietà del sistema: -Daws.crt.log.level=Trace -Daws.crt.log.destination=File -Daws.crt.log.filename=<path to file>	A livello di programmazione: 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
Utilizzo delle proprietà del sistema: -Daws.crt.log.level=Trace -Daws.crt.log.destination=Stdout	A livello di programmazione: import software.amazon.awssdk.crt.Log; // Execute this statement before constructing the SDK service client. Log.initLoggingToStdout(Log.LogLevel.Trace);

Per motivi di sicurezza, a livello «Trace» i client AWS CRT-based HTTP registrano solo le intestazioni di risposta. Le intestazioni delle richieste, i corpi delle richieste e i corpi delle risposte non vengono registrati.