File konfigurasi Log4j 2 Tambahkan ketergantungan logging Kesalahan dan peringatan khusus SDK Pencatatan ringkasan permintaan/tanggapan Pencatatan SDK tingkat debug Aktifkan pencatatan kawat

Logging dengan SDK for Java 2.x

AWS SDK for Java 2.x Menggunakan SLF4J, yang merupakan lapisan abstraksi yang memungkinkan penggunaan salah satu dari beberapa sistem logging saat runtime.

Sistem logging yang didukung termasuk Java Logging Framework dan Apache Log4j 2, antara lain. Topik ini menunjukkan cara menggunakan Log4j 2 sebagai sistem logging untuk bekerja dengan SDK.

File konfigurasi Log4j 2

Anda biasanya menggunakan file konfigurasi, bernama log4j2.xml dengan Log4j 2. Contoh file konfigurasi ditunjukkan di bawah ini. Untuk mempelajari lebih lanjut tentang nilai yang digunakan dalam file konfigurasi, lihat manual untuk konfigurasi Log4j.

log4j2.xmlFile harus berada di classpath saat aplikasi Anda dimulai. Untuk proyek Maven, letakkan file di direktori. <project-dir>/src/main/resources

File log4j2.xml konfigurasi menentukan properti seperti tingkat logging, di mana output logging dikirim (misalnya, ke file atau ke konsol), dan format output. Level logging menentukan tingkat detail yang keluaran Log4j 2. Log4j 2 mendukung konsep beberapa hierarki logging. Level logging diatur secara independen untuk setiap hierarki. Hirarki logging utama yang Anda gunakan dengan AWS SDK for Java 2.x adalahsoftware.amazon.awssdk.

Tambahkan ketergantungan logging

Untuk mengonfigurasi pengikatan Log4j 2 untuk SLF4J di file build Anda, gunakan yang berikut ini.

Gunakan 2.20.0 untuk versi minimum log4j-slf4j2-impl artefak. Untuk versi terbaru, gunakan versi yang diterbitkan ke pusat Maven. Ganti VERSION dengan versi yang akan Anda gunakan.

Kesalahan dan peringatan khusus SDK

Sebaiknya Anda selalu membiarkan hierarki logger “software.amazon.awssdk” disetel ke “WARN” untuk menangkap pesan penting apa pun dari pustaka klien SDK. Misalnya, jika klien Amazon S3 mendeteksi bahwa aplikasi Anda belum menutup InputStream dan dapat membocorkan sumber daya dengan benar, klien S3 melaporkannya melalui pesan peringatan ke log. Ini juga memastikan bahwa pesan dicatat jika klien memiliki masalah dalam menangani permintaan atau tanggapan.

log4j2.xmlFile berikut menetapkan rootLogger ke “WARN”, yang menyebabkan peringatan dan pesan tingkat kesalahan dari semua logger dalam aplikasi menjadi output, termasuk yang ada dalam hierarki “software.amazon.awssdk”. Atau, Anda dapat secara eksplisit mengatur hierarki logger “software.amazon.awssdk” ke “WARN” jika digunakan. <Root level="ERROR">

Contoh file konfigurasi Log4j2.xml

Konfigurasi ini akan mencatat pesan pada level “ERROR” dan “WARN” ke konsol untuk semua hierarki 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>

Pencatatan ringkasan permintaan/tanggapan

Setiap permintaan untuk AWS service menghasilkan ID AWS permintaan unik yang berguna jika Anda mengalami masalah dengan AWS service cara menangani permintaan. AWS ID permintaan dapat diakses secara terprogram melalui SdkServiceExceptionobjek di SDK untuk panggilan layanan yang gagal, dan juga dapat dilaporkan melalui level log “DEBUG” dari logger “software.amazon.awssdk.request”.

log4j2.xmlFile berikut memungkinkan ringkasan permintaan dan tanggapan.


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

Berikut adalah contoh dari output 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

Jika Anda tertarik hanya menggunakan ID permintaan<Logger name="software.amazon.awssdk.requestId" level="DEBUG" />.

Pencatatan SDK tingkat debug

Jika Anda memerlukan detail lebih lanjut tentang apa yang dilakukan SDK, Anda dapat mengatur tingkat logging software.amazon.awssdk logger ke. DEBUG Pada level ini, SDK mengeluarkan sejumlah besar detail, jadi kami sarankan Anda mengatur level ini untuk menyelesaikan kesalahan menggunakan pengujian integrasi.

Pada tingkat logging ini, SDK mencatat informasi tentang konfigurasi, resolusi kredensyal, pencegat eksekusi, aktivitas TLS tingkat tinggi, penandatanganan permintaan, dan banyak lagi.

Berikut ini adalah contoh pernyataan yang dihasilkan oleh SDK pada DEBUG tingkat untuk panggilanS3Client#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
...

log4j2.xmlFile berikut mengkonfigurasi output sebelumnya.


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

Aktifkan pencatatan kawat

Hal ini dapat berguna untuk melihat permintaan dan tanggapan yang tepat bahwa SDK for Java 2.x mengirim dan menerima. Jika Anda memerlukan akses ke informasi ini, Anda dapat mengaktifkannya sementara dengan menambahkan konfigurasi yang diperlukan tergantung pada klien HTTP yang digunakan klien layanan.

Secara default, klien layanan sinkron, seperti S3Client, menggunakan Apache yang mendasari HttpClient, dan klien layanan asinkron, seperti S3 AsyncClient, menggunakan klien HTTP non-blocking Netty.

Berikut adalah rincian klien HTTP yang dapat Anda gunakan untuk dua kategori klien layanan:

Klien HTTP sinkron	Klien HTTP Asinkron
ApacheHttpClient(default)	NettyNioAsyncHttpClient(default)
UrlConnectionHttpClient	AwsCrtAsyncHttpClient

Lihat tab yang sesuai di bawah ini untuk pengaturan konfigurasi yang perlu Anda tambahkan tergantung pada klien HTTP yang mendasarinya.

Awas

Kami menyarankan Anda hanya menggunakan wire logging untuk tujuan debugging. Nonaktifkan di lingkungan produksi Anda karena dapat mencatat data sensitif. Ini mencatat permintaan atau respons penuh tanpa enkripsi, bahkan untuk panggilan HTTPS. Untuk permintaan besar (misalnya, untuk mengunggah file ke Amazon S3) atau tanggapan, pencatatan kawat verbose juga dapat memengaruhi kinerja aplikasi Anda secara signifikan.

ApacheHttpClient

Tambahkan logger “org.apache.http.wire” ke file log4j2.xml konfigurasi dan atur levelnya ke “DEBUG”.

log4j2.xmlFile berikut menyalakan pencatatan kawat penuh untuk 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>

Ketergantungan Maven tambahan pada log4j-1.2-api artefak diperlukan untuk wire logging dengan Apache karena menggunakan 1.2 di bawah tenda.

Set lengkap dependensi Maven untuk log4j 2, termasuk wire logging untuk klien HTTP Apache ditampilkan dalam cuplikan file build berikut.

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

Gunakan 2.20.0 untuk versi minimum log4j-bom artefak. Untuk versi terbaru, gunakan versi yang diterbitkan ke pusat Maven. Ganti VERSION dengan versi yang akan Anda gunakan.

UrlConnectionHttpClient

Untuk mencatat detail untuk klien layanan yang menggunakanUrlConnectionHttpClient, pertama buat logging.properties file dengan konten berikut:


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

Mengatur properti sistem JVM berikut dengan jalur lengkap dari: logging.properties


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

Konfigurasi ini akan mencatat satu-satunya header permintaan dan respons, misalnya:


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

Untuk melihat badan permintaan/respons, tambahkan -Djavax.net.debug=all ke properti JVM. Properti tambahan ini mencatat banyak informasi, termasuk semua informasi SSL.

Di dalam konsol log atau file log, cari "GET" atau "POST" dengan cepat pergi ke bagian log yang berisi permintaan dan tanggapan aktual. "Plaintext before ENCRYPTION"Cari permintaan dan tanggapan "Plaintext after DECRYPTION" untuk melihat teks lengkap header dan badan.

NettyNioAsyncHttpClient

Jika klien layanan asinkron Anda menggunakan defaultNettyNioAsyncHttpClient, tambahkan dua logger tambahan ke log4j2.xml file Anda untuk mencatat header HTTP dan badan permintaan/respons.


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

Berikut adalah log4j2.xml contoh lengkapnya:


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

Pengaturan ini mencatat semua detail header dan badan permintaan/respons.

AwsCrtAsyncHttpClient

Jika Anda telah mengonfigurasi klien layanan Anda untuk menggunakan instanceAwsCrtAsyncHttpClient, Anda dapat mencatat detail dengan menyetel properti sistem JVM atau secara terprogram.

Log to a file at "Debug" level

Menggunakan properti sistem:


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

Secara terprogram:


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

Menggunakan properti sistem:


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

Secara terprogram:


import software.amazon.awssdk.crt.Log;

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

Untuk alasan keamanan, pada level “Trace” AwsCrtAsyncHttpClient log hanya header respons. Header permintaan, badan permintaan, dan badan respons tidak dicatat.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Percobaan ulang

Mengatur JVM TTL untuk pencarian nama DNS