使用适用于 Java 的 SDK 2.x 进行日志记录 - Amazon SDK for Java 2.x
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

使用适用于 Java 的 SDK 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 的版本。将 VERSION 替换为您将要使用的版本。

特定于 SDK 的错误消息和警告

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

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

Log4j2.xml 配置文件示例

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

<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 Service的所有请求都会生成一个唯一的 Amazon 请求 ID,如果您遇到与 Amazon Web Service如何处理请求有关的问题,可以使用它。如果调用任何服务时失败,可以通过 SDK 中的 SdkServiceException 对象来编程访问 Amazon 请求 ID,该 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" />

详细线路日志记录

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

默认情况下,同步服务客户端(例如 S3Client)使用底层 Apache HttpClient,而异步服务客户端(例如 S3)使用 Netty 非阻AsyncClient塞 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 依赖项,因为它在后台使用 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 的版本。将 VERSION 替换为您将要使用的版本。

UrlConnectionHttpClient

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

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

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

-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

如果您已将服务客户端配置为使用 AwsCrtAsyncHttpClient 的实例,则可以通过设置 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);

出于安全考虑,在“跟踪”级别,AwsCrtAsyncHttpClient 仅记录响应标头,不记录请求标头、请求正文和响应正文。