Log4j 2 berkas konfigurasi Tambahkan ketergantungan logging SDK-specific kesalahan dan peringatan Request/response pencatatan ringkasan Debug-level Pencatatan SDK Aktifkan pencatatan kawat

Logging dengan SDK untuk 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.

Log4j 2 berkas konfigurasi

Anda biasanya menggunakan file konfigurasi, dinamai 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 <project-dir>/src/main/resources direktori.

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 dikeluarkan 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 mengkonfigurasi 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 Maven central. Ganti VERSION dengan versi yang akan Anda gunakan.

SDK-specific kesalahan dan peringatan

Sebaiknya Anda selalu membiarkan hierarki logger “software.amazon.awssdk” diatur ke “WARN” untuk menangkap pesan penting dari pustaka klien SDK. Misalnya, jika klien Amazon S3 mendeteksi bahwa aplikasi Anda belum menutup sumber daya dengan benar InputStream dan dapat membocorkan sumber daya, 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 menyetel rootLogger ke “WARN”, yang menyebabkan peringatan dan pesan tingkat kesalahan dari semua logger dalam aplikasi akan dikeluarkan, termasuk yang ada di hierarki “software.amazon.awssdk”. Atau, Anda dapat secara eksplisit mengatur hierarki logger “software.amazon.awssdk” ke “WARN” jika digunakan. <Root level="ERROR">

Contoh file Log4j2.xml konfigurasi

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>

Request/response pencatatan ringkasan

Setiap permintaan ke an Layanan AWS menghasilkan ID AWS permintaan unik yang berguna jika Anda mengalami masalah dengan cara menangani permintaan. Layanan AWS AWS ID permintaan dapat diakses secara terprogram melalui SdkServiceException objek di SDK untuk panggilan layanan yang gagal, dan juga dapat dilaporkan melalui tingkat 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 keluaran 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" />.

Debug-level Pencatatan SDK

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

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

Berikut ini adalah contoh pernyataan yang dikeluarkan oleh SDK di DEBUG level untuk S3Client#listBuckets() panggilan.


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

Akan berguna untuk melihat permintaan dan tanggapan yang tepat yang dikirim dan diterima SDK untuk Java 2.x. 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 mendasarinya HttpClient, dan klien layanan asinkron, seperti S3AsyncClient, menggunakan klien HTTP non-pemblokiran Netty.

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

Klien HTTP Sinkron	Klien HTTP Asinkron
Apache5HttpClient (default)	NettyNioAsyncHttpClient (default)
UrlConnectionHttpClient	AwsCrtAsyncHttpClient
AwsCrtHttpClient
ApacheHttpClient

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 pencatatan kawat 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 kabel verbose juga dapat berdampak signifikan pada kinerja aplikasi Anda.

ApacheHttpClient

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

log4j2.xmlFile berikut mengaktifkan pencatatan kabel 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 pencatatan kawat dengan Apache karena menggunakan 1.2 di bawah kap.

Set lengkap dependensi Maven untuk log4j 2, termasuk pencatatan kawat 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>
...

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

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

Apache5HttpClient

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

log4j2.xmlFile berikut mengaktifkan pencatatan kabel penuh untuk Apac HttpClient he5.


<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

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

Tetapkan properti sistem JVM berikut dengan path 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 request/response tubuh, 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 dan badan HTTP. request/response


<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 request/response badan.

AwsCrtAsyncHttpClient/AwsCrtHttpClient

Jika Anda telah mengonfigurasi klien layanan Anda untuk menggunakan instance klien AWS CRT-based HTTP, 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 tingkat “Trace” klien AWS CRT-based HTTP hanya mencatat header respons. Header permintaan, badan permintaan, dan badan tanggapan 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

Pemantauan

Titik akhir