使用 Quarkus 配置日志记录
第 1 章 使用 Quarkus 配置日志记录 复制链接链接已复制到粘贴板!
作为应用程序开发人员,您可以使用日志记录来查看和记录应用运行时发生的事件的消息。日志消息提供在开发和测试期间可用于调试应用程序的信息,并在生产环境中监控应用程序。
先决条件
已安装 OpenJDK 11 或 17,并设置
JAVA_HOME环境变量来指定 Java SDK 的位置。- 要下载 Red Hat OpenJDK,请登录到红帽客户门户网站,进入 Software Downloads。
已安装 Apache Maven 3.8.x,其中 x 是 6 或更高版本。
- 从 Apache Maven Project 网站下载 Maven。
您已创建了 Quarkus Maven 项目。
- 有关如何使用 Maven 创建 Quarkus 应用程序的详情,请参阅使用 Apache Maven 开发和编译 Quarkus 应用程序。
使开源包含更多 复制链接链接已复制到粘贴板!
红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。详情请查看 CTO Chris Wright 的信息。
1.1. JBoss LogManager 和支持的日志记录框架 复制链接链接已复制到粘贴板!
Quarkus 使用 JBoss LogManager 日志记录后端来收集和管理日志数据。您可以使用 JBoss Logging 收集有关 Quarkus 内部事件的数据,以及应用程序中的事件。您可以在 application.properties 文件中配置日志行为。
除 JBoss Logging 外,JBoss LogManager 还支持几个第三方日志记录 API。JBoss LogManager 合并了所有支持的日志记录 API 的日志。
用于日志的支持的 API:
Quarkus 使用 JBoss Logging 处理其所有日志记录功能。当您使用依赖于不同日志记录 API 的库时,您需要将这个库从依赖项中排除,并将 JBoss Logging 配置为使用第三方 API 的日志记录适配器。
1.1.1. 添加 Apache Log4j 日志记录框架 复制链接链接已复制到粘贴板!
Apache Log4j 是一个日志记录框架,其中包括日志记录后端和日志记录 API。由于 Quarkus 使用 JBoss LogManager 后端,您可以将 log4j2-jboss-logmanager 库添加到项目中,并使用 Log4j 作为日志记录 API。添加 Log4j 库会将 Log4j 日志路由到 JBoss Log Manager。您不需要包含任何 Log4j 依赖项。
流程
将
log4j2-jboss-logmanager库作为依赖项添加到项目的pom.xml文件中:pom.xml文件示例<dependency> <groupId>org.jboss.logmanager</groupId> <artifactId>log4j2-jboss-logmanager</artifactId> </dependency>log4j2-jboss-logmanager是 Log4J 版本 2 API 的库。如果要使用旧的 Log4J 版本 1 API,您必须改为添加log4j-jboss-logmanager。
1.1.2. 使用日志记录适配器 复制链接链接已复制到粘贴板!
Quarkus 依赖于 JBoss Logging 库来满足所有日志记录要求。
当使用对其他日志记录库(如 Apache Commons Logging、Log4j 或 SLF4j)的库时,您必须从依赖项中排除这些日志记录库,并使用 JBoss Logging 提供的其中一个适配器。您不需要为作为 Quarkus 扩展依赖项的库添加适配器。
第三方日志记录实现不包括在原生可执行文件中,您的应用程序可能无法编译,并显示类似如下的错误消息:
Caused by java.lang.ClassNotFoundException: org.apache.commons.logging.impl.LogFactoryImpl
您可以通过为您使用的第三方日志记录实施配置 JBoss Logging 适配器来防止这个错误。
流程
根据您使用的日志记录库,将其中一个适配器添加到
pom.xml文件中:Apache Commons Logging:
pom.xml文件示例<dependency> <groupId>org.jboss.logging</groupId> <artifactId>commons-logging-jboss-logging</artifactId> </dependency>Log4j:
pom.xml文件示例<dependency> <groupId>org.jboss.logmanager</groupId> <artifactId>log4j-jboss-logmanager</artifactId> </dependency>Log4j2:
pom.xml文件示例<dependency> <groupId>org.jboss.logmanager</groupId> <artifactId>log4j2-jboss-logmanager</artifactId> </dependency>SLF4j:
pom.xml文件示例<dependency> <groupId>org.jboss.slf4j</groupId> <artifactId>slf4j-jboss-logmanager</artifactId> </dependency>
1.2. 为应用程序启用 JBoss Logging 复制链接链接已复制到粘贴板!
当您要使用 JBoss Logging 来收集应用程序日志时,您必须将日志记录器添加到您要生成日志的每个类。
以下流程演示了如何使用以下命令以编程方式向应用程序添加日志记录:
- API 方法
- 使用注解声明
流程
根据您的应用程序代码,使用以下方法之一:
创建
org.jboss.logging.Logger实例,并通过为每个类调用静态方法Logger.getLogger (Class)来初始化它:ExampleResource.java文件import org.jboss.logging.Logger;1 import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; @Path("/hello") public class ExampleResource { private static final Logger LOG = Logger.getLogger(ExampleResource.class);2 @GET @Produces(MediaType.TEXT_PLAIN) public String hello() { LOG.info("Hello");3 return "hello"; } }在 Bean 和资源类中注入配置的
org.jboss.logging.Logger实例:ExampleResource.java文件import javax.inject.Inject; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; import org.jboss.logging.Logger;1 import io.quarkus.arc.log.LoggerName; @Path("/hello") public class ExampleResource { @Inject Logger log;2 @LoggerName("foo") Logger fooLog;3 @GET @Produces(MediaType.TEXT_PLAIN) public String hello() { log.info("Simple!"); fooLog.info("Goes to foo logger!"); return "hello"; } }注意日志记录器实例在内部缓存。您注入 Bean 的日志记录器是为所有 bean 实例共享,以避免与日志记录器实例化相关的可能性能损失。
(可选)在
application.properties文件中配置日志输出:例如,您可以创建一个日志文件并将输出输出到控制台和文件中:
application.properties文件示例quarkus.log.file.enable=true quarkus.log.file.path=/tmp/trace.log在开发模式下运行应用程序:
在开发模式下运行应用程序
./mvnw quarkus:dev-
进入
http://localhost:8080/hello。 根据您的配置,查看终端或日志文件中的日志消息。
将日志级别设置为
INFO的ExampleResource.class输出示例:输出示例
2021-05-21 15:38:39,751 INFO [io.quarkus] (Quarkus Main Thread) my-project my-version on JVM (powered by Quarkus 1.13.3.Final) started in 1.189s. Listening on: http://localhost:8080 2021-05-21 15:38:39,765 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated. 2021-05-21 15:38:39,766 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, resteasy] 2021-05-21 15:38:58,790 INFO [ExampleResource] (executor-thread-1) Hello
1.3. 设置运行时配置 复制链接链接已复制到粘贴板!
您可以在 application.properties 文件中配置日志记录级别和类别。
日志记录类别是分级。当您为类别设置日志级别时,配置会应用到该类别的所有子类。
有两个日志记录级别设置: 日志级别和最小日志记录级别。默认日志记录级别为 INFO,默认的最小日志记录级别为 DEBUG。您可以使用 quarkus.log. level 和 属性或类别全局调整。
quarkus.log.min-level
当您在最小日志记录级别下设置日志级别时,您必须调整最小日志记录级别。否则,最小日志记录级别的值会覆盖日志级别。
过度日志记录对性能有影响。您可以调整最小日志记录级别,以仅收集与应用程序相关的数据。减少日志卷可能会优化内存用量并改进应用程序的性能。例如,在原生执行中,最小级别启用较低级别的检查(isTraceEnabled)被折叠为 false,这会导致代码删除。
流程
在
application.properties文件中配置日志记录:以下示例演示了如何将默认日志记录级别设置为
INFO日志记录,并包含 HibernateDEBUG日志:application.properties文件示例quarkus.log.level=INFO quarkus.log.category."org.hibernate".level=DEBUG注意当您使用命令行设置配置属性时,请使用
"转义。Example
-
-Dquarkus.log.category.\"org.hibernate\".level=TRACE
-
1.3.1. 配置日志记录格式 复制链接链接已复制到粘贴板!
Quarkus 使用基于模式的日志格式器来生成人类可读的文本日志。日志条目显示时间戳、日志记录级别、类名称、线程 ID 和消息。您可以使用专用配置属性自定义每个日志处理程序的格式。
先决条件
- 有一个 Quarkus Maven 项目。
流程
为
quarkus.log.console.format设置值来配置控制台处理器,如下所示:application.properties文件示例quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n此配置会产生以下日志消息格式:
14:11:07 INFO [ExampleResource] (executor-thread-199) Hello
1.3.1.1. 日志记录格式字符串 复制链接链接已复制到粘贴板!
下表显示了可用于配置日志消息格式的日志记录格式字符串符号。
| 符号 | 概述 | 描述 |
|---|---|---|
|
|
|
简单 |
|
| 类别 | 类别名称 |
|
| 源类 | 源类名称 [a] |
|
| Date |
给定日期格式字符串的日期,它遵循 |
|
| 例外 | 异常堆栈追踪 |
|
| 源文件 | 源文件名 [a] |
|
| 主机名 | 系统简单主机名 |
|
| 合格主机名 | 系统的完全限定主机名。根据操作系统配置,它可能与简单主机名相同。 |
|
| 进程 ID | 当前进程 PID |
|
| 源位置 | 源位置(源文件名、行号、类名称和方法名称) [a] |
|
| 源行 | 源行号 [a] |
|
| 完整消息 | 包括异常追踪的日志消息 |
|
| 源方法 | 源方法名称 [a] |
|
| newline | 特定于平台的行分隔符字符串 |
|
| 进程名称 | 当前进程的名称 |
|
| 级别 | 消息的日志记录级别 |
|
| 相对时间 | 应用程序日志开始的相对时间(以毫秒为单位) |
|
| 简单消息 | 没有异常追踪的日志消息 |
|
| 线程名称 | 线程名称 |
|
| 线程 ID | 线程 ID |
|
| 时区 |
输出的时区,格式为 < |
|
| 映射诊断上下文值 | 映射诊断上下文中的值 |
|
| 映射诊断上下文值 | 来自 Mapped Diagnostics Context 的所有值,格式为 {property.key=property.value} |
|
| 嵌套诊断上下文值 | {value1.value2} 格式的 Nested Diagnostics Context 的所有值 |
[a]
检查调用者信息的格式序列可能会影响性能。
| ||
1.3.2. 日志记录类别设置 复制链接链接已复制到粘贴板!
您可以使用日志记录类别根据它们的严重性或它们所属的组件来组织日志消息。每个类别都可以独立配置。
对于每个类别,相同的设置适用于 console、file 和 syslog。您可以通过将一个或多个指定处理程序附加到类别来覆盖设置。
| 属性名称 | default | 描述 |
|---|---|---|
|
|
|
配置 < |
|
|
|
配置 < |
|
|
| 启用日志记录器将其输出发送到父日志记录器。 |
|
|
| 要附加到特定类别的处理程序的名称。 |
[a]
有些扩展定义了特定类别的自定义默认日志记录级别,以减少日志记录。在配置中设置日志级别会覆盖任何扩展的日志记录级别。
[b]
默认情况下,配置的类别从根日志记录器类别继承所有附加的处理程序。
| ||
在将日志记录类别名称放在属性名称中时,将日志记录类别名称放在双引号中,以转义通常属于类别名称的句点(.)。
1.3.3. 日志记录级别 复制链接链接已复制到粘贴板!
您可以使用日志记录级别按严重性对日志进行分类,或者它们对 Quarkus 应用程序的健康状态和稳定性的影响。通过日志记录级别,您可以从纯信息的事件过滤关键事件。
| 日志记录级别 | 描述 |
|---|---|
| OFF | 用于关闭日志记录的特殊级别。 |
| FATAL | 关键服务故障或无法完成服务请求。 |
| ERROR | 请求出现重大中断,或者无法服务请求。 |
| WARN | 非关键服务错误或可能不需要立即纠正的问题。 |
| INFO | 服务生命周期事件或重要相关的非常频率信息。 |
| DEBUG | 提供有关生命周期或非请求绑定事件的额外调试信息的消息。 |
| TRACE | 传递的消息具有高频率,可提供额外每个请求的调试信息。 |
| ALL | 包括自定义级别在内的所有消息的特殊级别。 |
另外,您可以使用 java.util.logging 软件包中描述的日志级别名称。
1.3.4. 根日志记录器配置 复制链接链接已复制到粘贴板!
根日志记录器类别位于日志记录器层次结构的顶部,其配置在日志配置的顶级。根日志记录器捕获发送到服务器的指定日志记录级别或更高级别的所有日志消息,不会由日志记录类别捕获。
| 属性名称 | default | 描述 |
|---|---|---|
|
|
| 每个日志记录类别的默认日志记录级别。 |
|
|
| 每个日志记录类别的默认最小日志记录级别。 |
1.3.5. Quarkus 日志处理程序 复制链接链接已复制到粘贴板!
日志处理程序是一个日志记录组件,将日志事件发送到接收者。Quarkus 包括以下日志处理程序:
1.3.6. 日志配置示例 复制链接链接已复制到粘贴板!
本节演示了如何为 Quarkus 项目配置日志记录示例。
application.properties 文件示例
# Format log messages to have shorter time and shorter category prefixes.
quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Remove color from log messages.
quarkus.console.color=false
# Enable console DEBUG logging with the exception of Quarkus logs that have a logging level set to INFO.
quarkus.log.console.level=DEBUG
quarkus.log.category."io.quarkus".level=INFO
application.properties 文件示例
# Enable file logging and set a path to the log file.
quarkus.log.file.enable=true
quarkus.log.file.path=/tmp/trace.log
# Enable TRACE log messages in a log file.
quarkus.log.file.level=TRACE
# Set a format for the log file output.
quarkus.log.file.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Set logging level to TRACE for specific categories.
quarkus.log.category."io.quarkus.smallrye.jwt".level=TRACE
quarkus.log.category."io.undertow.request.security".level=TRACE
默认情况下,根日志记录器级别设置为 INFO。当您要收集较低级别的日志时,更改根日志记录器配置,如 DEBUG 或 TRACE。
application.properties 文件示例
# Set path to the log file.
quarkus.log.file.path=/tmp/trace.log
# Configure console format.
quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Configure a console log handler.
quarkus.log.handler.console."STRUCTURED_LOGGING".format=%e%n
# Configure a file log handler.
quarkus.log.handler.file."STRUCTURED_LOGGING_FILE".enable=true
quarkus.log.handler.file."STRUCTURED_LOGGING_FILE".format=%e%n
# Configure the category and associate it with the two named handlers.
quarkus.log.category."io.quarkus.category".level=INFO
quarkus.log.category."io.quarkus.category".handlers=STRUCTURED_LOGGING,STRUCTURED_LOGGING_FILE
1.4. 配置 JSON 日志记录格式 复制链接链接已复制到粘贴板!
您可以将控制台日志的输出格式改为 JSON,以便更轻松地处理和存储日志信息,以便稍后进行分析。
要配置 JSON 日志记录格式,您需要将 quarkus-logging-json 扩展添加到 Quarkus 项目。quarkus-logging-json 扩展替换了控制台配置中的输出格式配置。
- 控制台配置项(如格式字符串和颜色设置)将被忽略。
- 其他控制台配置项目(包括控制异步日志记录和日志记录级别)继续应用。
流程
将
quarkus-logging-json扩展添加到应用程序的pom.xml文件中:pom.xml文件示例<dependencies> <!-- ... your other dependencies are here ... --> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-logging-json</artifactId> </dependency> </dependencies>(可选)在
application.properties文件中为 JSON 日志记录设置特定于配置集的配置:以下示例演示了如何为开发和测试配置集禁用 JSON 日志记录:
application.properties文件示例%dev.quarkus.log.console.json=false %test.quarkus.log.console.json=false
1.4.1. JSON 日志记录配置属性 复制链接链接已复制到粘贴板!
您可以使用以下配置属性配置 JSON 日志记录扩展:
| 配置属性 | 描述 | 类型 | default |
|---|---|---|---|
|
| 启用 JSON 控制台格式扩展。 | 布尔值 |
|
|
| 启用 JSON 记录的用户打印。 [a] | 布尔值 |
|
|
|
日期的格式。 | string |
|
|
| 特殊记录分隔符.默认情况下,line 用作分隔符。 | string | |
|
|
区的 ID。 | string |
|
|
| 异常的输出类型。 |
|
|
|
| 启用日志的详细打印。详情包括源类名称、源文件名、源方法名称和源行号。 [b] | 布尔值 |
|
[a]
有些处理器和 JSON 解析器可能无法读取用户打印的输出。
[b]
打印详细信息可能比较昂贵,因为值是从调用者检索的。
| |||
1.5. 为 @QuarkusTest 配置日志记录 复制链接链接已复制到粘贴板!
如果要为 @QuarkusTest 配置日志记录,则需要相应地设置 maven-surefire-plugin。您必须使用 java.util.logging.manager 系统属性指定 LogManager。
流程
使用
java.util.logging.manager系统属性设置LogManager:pom.xml文件示例<build> <plugins> <plugin> <artifactId>maven-surefire-plugin</artifactId> <version>${surefire-plugin.version}</version> <configuration> <systemPropertyVariables> <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>1 <quarkus.log.level>DEBUG</quarkus.log.level>2 <maven.home>${maven.home}</maven.home> </systemPropertyVariables> </configuration> </plugin> </plugins> </build>