Log4j 2 配置文件添加日志依赖项 SDK特定的错误和警告请求/响应摘要记录详细的线路记录

使用适用于 Java 2.x 的开发工具包登录

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

支持的日志系统包括 Java 日志框架和 Apache Log4j 2 等。本主题向您介绍如何使用 Log4j 2 作为使用 SDK 的日志系统。

Log4j 2 配置文件

您通常使用以 Log4j 2 命名的log4j2.xml配置文件。配置文件示例如下所示。要了解有关配置文件中使用的值的更多信息，请参阅 Log4j 配置手册。

使用 Maven 时将log4j2.xml文件放在<project-dir>/src/main/resources目录中。

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

添加日志依赖项

要在编译文件中为 SLF4J 配置 Log4j 2 绑定，请使用以下内容。

2.20.0用于log4j-slf4j2-impl构件的最低版本。要获得最新版本，请使用发布到 Maven centra l 的版本。用你将要使用的版本替换 VERSION。

SDK特定的错误和警告

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

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

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>
 </Loggers>
</Configuration>

请求/响应摘要记录

对的每个请求都会AWS 服务生成一个唯一的AWS请求 ID，如果您在处理请求的方式上遇到问题，AWS 服务该请求将非常有用。 AWS对于任何失败的服务调用，都可以通过 SDK 中的SdkServiceException对象以编程方式访问请求 ID，也可以通过 “software.amazon.awssdk.request” 记录器的 “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="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 for Java 2.x 发送和接收的确切请求和响应可能很有用。如果您需要访问此信息，则可以通过根据服务客户端使用的 HTTP 客户端添加必要的配置来临时启用该信息。

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

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

同步 HTTP 客户端	异步HTTP 客户端
ApacheHttpClient（默认）	NettyNioAsyncHttpClient（默认）
UrlConnectionHttpClient	AwsCrtAsyncHttpClient

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

警告

我们建议只出于调试目的使用线路日志记录。由于线路日志记录可能记录敏感数据，因此应在您的生产环境中禁用它。它会记录完整的请求或响应而不加密，即使对于 HTTPS 调用也是如此。对于大型请求（例如，将文件上传到 Amazon S3）或响应，详细线路日志记录也可能显著影响应用程序的性能。

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 依赖工件，因为 Apache 在后台使用 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")
}
...

2.20.0用于log4j-bom构件的最低版本。要获得最新版本，请使用发布到 Maven centra l 的版本。用你将要使用的版本替换 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=all到 JVM 属性中。此附加属性记录了大量信息，包括所有 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

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

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 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 import software.amazon.awssdk.crt.Log;

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

出于安全原因，在 “跟踪” 级别，仅AwsCrtAsyncHttpClient记录响应标头。未记录请求标头、请求正文和响应正文。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

异常处理

设置 DNS 名称查找的 JVM TTL