Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用SDK适用于 Java 2.x 的

用 Amazon SDK for Java 2.x 途 SLF4J，这是一个抽象层，允许在运行时使用多个日志系统中的任何一个。

支持的日志记录系统包括 Java Logging Framework、Apache Log4j 2 和其他系统。本主题向您展示如何使用 Log4j 2 作为处理的日志系统。SDK

Log4j 2 配置文件

您通常是将一个名为 log4j2.xml 的配置文件与 Log4j 2 结合使用。配置文件示例如下所示。要了解有关配置文件中使用的值的更多信息，请参阅 Log4j 配置手册。

应用程序启动时，该 log4j2.xml 文件必须位于类路径中。对于 Maven 项目，请将文件放在 <project-dir>/src/main/resources 目录中。

log4j2.xml 配置文件会指定日志记录级别、将日志记录输出发送到的位置（例如发送到文件或控制台）和输出格式等属性。日志级别指定 Log4j 2 输出的详细级别。Log4j 2 支持多个日志记录层次结构 的概念。可以为每级层次结构单独设置日志记录级别。与一起使用的主日志层次结构 Amazon SDK for Java 2.x 是software.amazon.awssdk。

添加日志记录依赖项

要在生成文件SLF4J中配置 Log4j 2 绑定，请使用以下命令。

Maven

在 pom.xml 文件中添加以下元素：

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

Gradle–Kotlin DSL

在 build.gradle.kts 文件中添加以下内容。

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

对于 log4j-slf4j2-impl 构件的最低版本，请使用 2.20.0。要获取最新版本，请使用发布到 Maven central 的版本。Replace（替换） VERSION 以及你将要使用的版本。

SDK-特定的错误和警告

我们建议您始终将 “software.amazon.awssdk” 记录器层次结构设置为 “”，以便从的WARN客户端库中捕获任何重要消息。SDK例如，如果 Amazon S3 客户端检测到应用程序没有正确关闭 InputStream 而且可能会泄漏资源，那么 S3 客户端将通过向日志中记录警告消息来进行报告。另外，由此可确保客户端在处理请求或响应遇到任何问题时会记录相应消息。

以下log4j2.xml文件将设置WARN为 “”，这会导致输出来自应用程序中所有记录器的警告和错误级别消息，包括 “software.amazon.awssdk” 层次结构中的记录器。rootLogger或者，如果使用 “software.amazon.awssdk” 记录器层次结构，则可以显式设置为 “”。WARN <Root level="ERROR">

Log4j2.xml 配置文件示例

此配置会将所有记录器层次结构的 “ERRORWARN” 和 “” 级别的消息记录到控制台。

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

请求/响应摘要日志记录

对的每个请求都会 Amazon Web Services 服务 生成一个唯一的 Amazon 请求 ID，如果您在如何处理请求时遇到问题， Amazon Web Services 服务 这会很有用。 Amazon SDK对于任何失败的服务调用，都可以通过中的SdkServiceException对象以编程方式访问请求IDs，也可以通过 “software.amazon.awssdk.reques DEBUG t” 记录器的 “” 日志级别报告请求。

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

以下是日志输出的示例：

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

如果您只对请求编号感兴趣，请使用 <Logger name="software.amazon.awssdk.requestId" level="DEBUG" />。

调试级日志 SDK

如果您需要有关正在执行的操作的SDK更多详细信息，可以将记录器的日志级别设置为。software.amazon.awssdk DEBUG在此级别上，它们会SDK输出大量细节，因此我们建议您设置此级别以使用集成测试来解决错误。

在此日志级别，记录有关配置、凭据解析、执行拦截器、高级TLS活动、请求签名等的信息。SDK

以下是 a SDK t 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
...

以下log4j2.xml文件配置了之前的输出。

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

启用线路记录

查看 for Java 2.x 发送和接收SDK的确切请求和响应可能很有用。如果您需要访问这些信息，则可以根据服务客户端使用的HTTP客户端添加必要的配置来临时将其启用。

默认情况下，同步服务客户端（例如 S3Client）使用底层 Apache HttpClient，而异步服务客户端（例如 S3）使用 Netty 非AsyncClient阻塞客户端。HTTP

以下是可用于这两类服务HTTP客户端的客户端明细：

请查阅下面的相应选项卡，了解需要根据底层HTTP客户端添加的配置设置。

ApacheHttpClient

将 “org.apache.http.wire” 记录器添加到log4j2.xml配置文件中，并将级别设置为 “”。DEBUG

以下log4j2.xml文件开启了 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>

使用 Apache 进行线路日志记录需要对 log4j-1.2-api 构件的额外 Maven 依赖项，因为它在后台使用 1.2。

以下编译文件片段显示了 log4j 2 的全套 Maven 依赖项，包括 Apache HTTP 客户端的线路日志。

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

对于 log4j-bom 构件的最低版本，请使用 2.20.0。要获取最新版本，请使用发布到 Maven central 的版本。Replace（替换） VERSION 以及你将要使用的版本。

UrlConnectionHttpClient

要记录使用 UrlConnectionHttpClient 的服务客户端的详细信息，请先创建一个包含以下内容的 logging.properties 文件：

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

使用以下完整路径设置以下JVM系统属性logging.properties：

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

此配置将仅记录请求和响应的标头，例如：

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

要查看请求/响应正文，请在属性中-Djavax.net.debug=allJVM添加。这个额外的属性记录了大量信息，包括所有SSL信息。

在日志控制台或日志文件中，搜索 "GET" 或 "POST" 以快速转到包含实际请求和响应的日志部分。使用 "Plaintext before ENCRYPTION" 搜索请求，使用 "Plaintext after DECRYPTION" 搜索响应，以查看标头和正文的全文。

NettyNioAsyncHttpClient

如果您的异步服务客户端使用默认值NettyNioAsyncHttpClient，请在log4j2.xml文件中再添加两个记录器来记录HTTP标头和请求/响应正文。

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

以下是完整 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>

这些设置记录所有标头详细信息和请求/响应正文。

AwsCrtAsyncHttpClient/AwsCrtHttpClient

如果您已将服务客户端配置为使用 Amazon CRT基于HTTP客户端的实例，则可以通过设置JVM系统属性或以编程方式记录详细信息。

Log to a file at "Debug" level
使用系统属性： -Daws.crt.log.level=Trace -Daws.crt.log.destination=File -Daws.crt.log.filename=<path to file>	使用编程方式： 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
使用系统属性： -Daws.crt.log.level=Trace -Daws.crt.log.destination=Stdout	使用编程方式： import software.amazon.awssdk.crt.Log; // Execute this statement before constructing the SDK service client. Log.initLoggingToStdout(Log.LogLevel.Trace);

出于安全考虑，在 “跟踪” 级别上， Amazon CRT基于HTTP客户端仅记录响应标头。不记录请求标头、请求正文和响应正文。