适用于 Java 的 AWS 开发工具包
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

记录 AWS SDK for Java 调用

AWS SDK for Java通过 Slf4j 进行检测,它是一个抽象层,支持在运行时使用多种日志记录系统中的一个。

支持的日志记录系统包括 Java Logging Framework、Apache Log4j 和其他系统。本主题介绍如何使用 Log4j。无需对您的应用程序代码进行任何更改,就可以使用开发工具包的日志记录功能。

要了解有关 Log4j 的更多信息,请参阅 Apache 网站

添加 Log4J JAR

要将 Log4j 与开发工具包结合使用,您需要从 Log4j 网站下载 Log4j JAR 或通过在 pom.xml 文件中的 Log4j 上添加依赖项来使用 Maven。该开发工具包不包括 JAR。

Log4j 配置文件

Log4j 使用配置文件 log4j2.xml。配置文件示例如下所示。要了解有关配置文件中使用的值的更多信息,请参阅 Log4j 配置手册

将配置文件置于类路径上的目录中。Log4j JAR 和 log4j2.xml 文件不需要位于同一目录中。

log4j2.xml 配置文件会指定日志记录级别、发送日志记录输出的位置(例如发送到文件或控制台)和输出格式等属性。日志级别是记录器生成输出的粒度。Log4j 支持多个日志记录层次结构的概念。可以为每级层次结构单独设置日志记录级别。AWS SDK for Java 支持以下两个日志记录层次结构:

  • software.amazon.awssdk

  • org.apache.http.wire

设置类路径

Log4j JAR 和 log4j2.xml 文件都必须位于类路径中。要为 Maven 中的 Sl4j 配置 log4j 绑定,您可以将以下内容添加到 pom.xml:

<dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-slf4j-impl</artifactId> </dependency>

如果您使用 Eclipse IDE,可以打开菜单并导航到 Project | Properties | Java Build Path 来设置类路径。

特定服务的错误消息和警告

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

以下 log4j2.xml 文件将 rootLogger 设置为 WARN,也就是包含“software.amazon.awssdk”层次结构中所有记录器发送的警告和错误消息。您也可以将 software.amazon.awssdk 记录器显式设置为 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> <Logger name="software.amazon.awssdk" level="WARN" /> </Loggers> </Configuration>

请求/响应摘要日志记录

对 AWS 服务的所有请求都会生成一个 AWS 请求 ID,如果您遇到与 AWS 服务处理请求有关的问题,可以使用它。如果调用任何服务失败,可以通过开发工具包中的 Exception 对象以编程方式访问 AWS 请求 ID,还可以通过“software.amazon.awssdk.request”记录器中的 DEBUG 日志级别报告 AWS 请求 ID。

以下 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" /> </Loggers> </Configuration>

以下是日志输出的示例:

2018-01-28 19:31:56 [main] DEBUG software.amazon.awssdk.request:Logger.java:78 - Sending Request: software.amazon.awssdk.http.DefaultSdkHttpFullRequest@3a80515c

详细线路日志记录

在某些情况下,查看 AWS SDK for Java 发送和接收的确切请求和响应可能很有用。如果确实需要访问相关信息,可以通过 Apache HttpClient 记录器临时启用它。如果在 apache.http.wire 记录器中启用 DEBUG 级别,会记录所有请求和响应数据。

警告

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

以下 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。如果启用了线路日志记录,请将以下内容添加到 pom.xml 文件。

<dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-1.2-api</artifactId> </dependency>