使用 Quarkus 配置日志
指南
摘要
前言 复制链接链接已复制到粘贴板!
作为应用程序开发人员,您可以使用日志记录来查看和记录应用程序运行时发生的事件的消息。日志消息提供在开发和测试过程中用来调试应用程序的信息,并在生产环境中监控应用程序。
先决条件
安装 OpenJDK(JDK)11,将
JAVA_HOME环境变量设置为指定 Java SDK 的位置。- 登录红帽客户门户网站,从 Software Downloads 页面下载 Open JDK 的 Red Hat build。
已安装 Apache Maven 3.6.2 或更高版本。
- 从 Apache Maven Project 网站下载 Maven。
具有 Quarkus Maven 项目。
- 如需有关如何使用 Maven 创建 Quarkus 应用程序的信息,请参阅使用 Apache Maven 开发和编译 Quarkus 应用程序。
对红帽文档提供反馈 复制链接链接已复制到粘贴板!
我们非常感谢您对我们的技术内容提供反馈,并鼓励您告诉我们您的想法。如果您想添加评论,提供见解、纠正拼写错误甚至询问问题,您可以在文档中直接这样做。
您必须有一个红帽帐户并登录到客户门户网站。
要从客户门户网站提交文档反馈,请执行以下操作:
- 选择 Multi-page HTML 格式。
- 点文档右上角的 反馈 按钮。
- 突出显示您要提供反馈的文本部分。
- 点高亮文本旁的添加反馈对话框。
- 在页面右侧的文本框中输入您的反馈,然后单击 Submit。
每次提交反馈时,我们都会自动创建跟踪问题。打开在点 Submit 后显示的链接,并开始监视问题或添加更多注释。
感谢您的宝贵反馈。
使开源包含更多 复制链接链接已复制到粘贴板!
红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情,请参阅我们的首席技术官 Chris Wright 提供的消息。
第 1 章 JBoss LogManager 及支持的日志记录框架 复制链接链接已复制到粘贴板!
Quarkus 使用 JBoss LogManager 日志记录后端来收集和管理日志数据。您可以使用 JBoss Logging 收集有关 Quarkus 内部事件的数据,以及应用程序内的事件。您可以在 application.properties 文件中配置日志记录行为。
JBoss LogManager 在 JBoss Logging 之外支持多个第三方日志记录 API。JBoss LogManager 合并了所有支持的日志记录 API 的日志。
Quarkus 使用 JBoss Logging 处理其所有日志记录功能。当使用依赖于不同日志记录 API 的库时,您需要将这个库从依赖项中排除并配置 JBoss Logging,以将日志适配器用于第三方 API。
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>
<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.2. 使用日志记录适配器 复制链接链接已复制到粘贴板!
Quarkus 依赖于 JBoss Logging 库来满足所有日志要求。
当您使用依赖于其他日志记录库的库(如 Apache Commons Logging、Log4j 或 SLF4j)时,您必须将这些日志记录库从依赖项中排除,并使用 JBoss Logging 提供的其中一个适配器。您不需要为作为 Quarkus 扩展的依赖项的库添加适配器。
第三方日志记录实施没有包含在原生可执行文件中,应用程序可能无法使用类似如下的错误消息进行编译:
Caused by java.lang.ClassNotFoundException: org.apache.commons.logging.impl.LogFactoryImpl
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><dependency> <groupId>org.jboss.logging</groupId> <artifactId>commons-logging-jboss-logging</artifactId> </dependency>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Log4j:
pom.xml
<dependency> <groupId>org.jboss.logmanager</groupId> <artifactId>log4j-jboss-logmanager</artifactId> </dependency><dependency> <groupId>org.jboss.logmanager</groupId> <artifactId>log4j-jboss-logmanager</artifactId> </dependency>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Log4j2:
pom.xml
<dependency> <groupId>org.jboss.logmanager</groupId> <artifactId>log4j2-jboss-logmanager</artifactId> </dependency><dependency> <groupId>org.jboss.logmanager</groupId> <artifactId>log4j2-jboss-logmanager</artifactId> </dependency>Copy to Clipboard Copied! Toggle word wrap Toggle overflow SLF4j:
pom.xml
<dependency> <groupId>org.jboss.slf4j</groupId> <artifactId>slf4j-jboss-logmanager</artifactId> </dependency><dependency> <groupId>org.jboss.slf4j</groupId> <artifactId>slf4j-jboss-logmanager</artifactId> </dependency>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
第 2 章 为应用程序启用 JBoss Logging 复制链接链接已复制到粘贴板!
当您想使用 JBoss Logging 来收集应用程序日志时,您必须向您要生成日志的每个类添加一个日志记录器。以下流程演示了如何以编程方式使用 API 方法或声明性地将日志记录添加到应用程序中。
流程
根据您的应用程序代码,使用以下方法之一:
创建一个
org.jboss.logging.Logger实例,并通过为每个类调用静态方法Logger.getLogger(Class)初始化它:src/main/java/org/acme/ExampleResource.java
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在您的 Bean 和资源类中注入已配置的
org.jboss.logging.Logger实例:src/main/java/org/acme/ExampleResource.java
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意日志记录器实例在内部缓存。您注入到 Bean 的日志记录器,为所有 Bean 实例共享,以避免与日志记录器实例化相关的可能性能。
(可选)在
应用程序.properties文件中配置日志输出:src/main/resources/application.properties
<configuration_key>=<value>
<configuration_key>=<value>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如,您可以创建一个日志文件并将输出输出到控制台以及文件:
src/main/resources/application.properties
quarkus.log.file.enable=true quarkus.log.file.path=/tmp/trace.log
quarkus.log.file.enable=true quarkus.log.file.path=/tmp/trace.logCopy to Clipboard Copied! Toggle word wrap Toggle overflow 以开发模式运行应用程序:
./mvnw quarkus:dev
./mvnw quarkus:devCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
导航到
http://localhost:8080/hello。 根据您的配置,查看终端或日志文件中的日志消息。
ExampleResource.class输出示例,日志记录级别设置为INFO: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
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) HelloCopy to Clipboard Copied! Toggle word wrap Toggle overflow
第 3 章 设置运行时配置 复制链接链接已复制到粘贴板!
您可以在 application.properties 文件中配置日志记录级别和日志类别设置。
日志记录类别是层级的。当您为类别设置日志记录级别时,配置会应用到该类别的所有子类别。
有两个日志记录级别设置:日志级别和最低日志记录级别。默认的日志记录级别为 INFO,默认的最小日志记录级别为 DEBUG。您可以使用 quarkus.log.level 和 quarkus.log.min-level 属性或 category 来全局调整。
当您在最小日志记录级别下设置日志记录级别时,还必须调整最小日志记录级别。否则,最小日志级别的值会覆盖日志级别。
过量日志记录对性能有影响。您可以调整最小日志级别来只收集与应用程序相关的数据。减少日志卷可能会优化内存用量并改进应用程序的性能。例如,以原生执行级别可启用较低级别的检查(israceEnabled)来折叠到 false,这会导致死代码淘汰。
流程
在
application.properties文件中配置日志记录:src/main/resources/application.properties
<configuration_key>=<value>
<configuration_key>=<value>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 以下示例演示了如何将默认日志级别设置为
INFO日志记录,并包含 HibernateDEBUG日志:src/main/resources/application.properties
quarkus.log.level=INFO quarkus.log.category."org.hibernate".level=DEBUG
quarkus.log.level=INFO quarkus.log.category."org.hibernate".level=DEBUGCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注意当您使用命令行设置配置属性时,请确保转义
"。For example-Dquarkus.log.category.\"org.hibernate\".level=TRACE.
3.1. 配置日志记录格式 复制链接链接已复制到粘贴板!
Quarkus 使用基于模式的日志格式者,可生成人类可读的文本日志。日志条目显示时间戳、日志级别、类名称、线程 ID 和消息。您可以使用专用配置属性自定义每个日志处理程序的格式。
先决条件
- 具有 Quarkus Maven 项目。
流程
为
quarkus.log.console.format设置值来配置控制台处理器:src/main/resources/application.properties
quarkus.log.console.format=<logging_format_string>
quarkus.log.console.format=<logging_format_string>Copy to Clipboard Copied! Toggle word wrap Toggle overflow src/main/resources/application.properties
quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%nquarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%nCopy to Clipboard Copied! Toggle word wrap Toggle overflow 这个配置会生成以下日志消息格式:
14:11:07 INFO [ExampleResource] (executor-thread-199) Hello
14:11:07 INFO [ExampleResource] (executor-thread-199) HelloCopy to Clipboard Copied! Toggle word wrap Toggle overflow
3.1.1. 日志记录格式字符串 复制链接链接已复制到粘贴板!
下表显示了可用于配置日志消息格式的字符串符号。
| 符号 | 概述 | 描述 |
|---|---|---|
|
|
|
简单的 |
|
| 类别 | 类别名称 |
|
| 源类 | 源类名称 [a] |
|
| Date |
给定日期格式字符串的日期,遵循 |
|
| 例外 | 异常堆栈追踪 |
|
| 源文件 | 源文件名 [a] |
|
| 主机名 | 系统简单主机名 |
|
| 限定主机名 | 系统的完全限定主机名。根据操作系统配置,它可能和简单主机名相同。 |
|
| 进程 ID | 当前进程 PID |
|
| 源位置 | 源位置(源文件名、行号、类名称和方法名称) [a] |
|
| 源行 | 源行号 [a] |
|
| 完整信息 | 包括异常追踪的日志消息 |
|
| 源方法 | 源方法名称 [a] |
|
| 换行符 | 特定于平台的行分隔符字符串 |
|
| 进程名称 | 当前进程的名称 |
|
| 级别 | 消息的日志记录级别 |
|
| 相对时间 | 应用程序日志开始以来的相对时间(毫秒) |
|
| 简单消息 | 没有例外追踪的日志消息 |
|
| 线程名称 | 线程名称 |
|
| 线程 ID | 线程 ID |
|
| 时区 |
输出的时区,格式为 < |
|
| 映射的诊断上下文值 | 映射诊断上下文中的值 |
|
| 映射的诊断上下文值 | 来自映射诊断上下文的所有值,格式为 {property.key=property.value} |
|
| 嵌套的诊断上下文值 | 嵌套的 Diagnostics 上下文中的所有值,格式为 {value1.value2} |
[a]
格式化检查调用者信息的序列可能会影响性能。
| ||
3.2. 日志类别设置 复制链接链接已复制到粘贴板!
您可以使用日志类别根据严重性或它们所属的组件来组织日志消息。您可以独立配置每个类别。
对于每个类别,同一设置都适用于 console、file 和 syslog。您可以通过将一个或多个指定的处理程序附加到类别来覆盖设置。
| 属性名称 | 默认 | 描述 |
|---|---|---|
|
|
|
配置 < |
|
|
|
配置 < |
|
|
| 启用日志记录器,将其输出发送到父日志记录器。 |
|
|
| 要附加到特定类别的处理程序的名称。 |
[a]
有些扩展定义了特定类别的自定义默认日志记录级别,以减少日志 noise。在配置中设置日志级别会覆盖任何定义的日志记录级别。
[b]
默认情况下,配置的类别从根日志记录器类别继承所有附加的处理程序。
| ||
在属性名称中使用日志类别名称时,您必须将日志类别名称放在双引号内,以转义通常是类别名称一部分的句点(.)。
3.3. 日志级别 复制链接链接已复制到粘贴板!
您可以使用日志级别根据严重性对日志进行分类,或它们对 Quarkus 应用程序的健康状态和稳定性的影响。通过日志记录级别,您可以从纯信息的事件过滤关键事件。
| 日志级别 | 描述 |
|---|---|
| OFF | 关闭日志记录的特殊级别。 |
| FATAL | 关键服务故障或无法完成服务请求。 |
| ERROR | 对请求或无法服务请求的中断。 |
| WARN | 非关键服务错误或不需要立即更正的问题。 |
| INFO | 服务生命周期事件或重要相关 f-low-frequency 信息。 |
| DEBUG | 传达有关生命周期或非请求绑定事件的额外信息(对于调试非常有用)。 |
| TRACE | 布置额外每个请求的调试信息(可能非常高的频率)的信息。 |
| ALL | 所有消息的特殊级别,包括自定义级别。 |
另外,您还可以使用 java.util.logging 软件包中描述的日志记录级别名称。
3.4. 根日志记录器配置 复制链接链接已复制到粘贴板!
根日志记录器类别位于日志记录器层次结构的顶部。根日志记录器捕获指定日志记录级别或更高的所有日志消息,它们发送到服务器,不被日志记录类别捕获。根日志记录器类别在日志配置的顶层配置。
| 属性名称 | 默认 | 描述 |
|---|---|---|
|
|
| 每个日志记录类别的默认日志记录级别。 |
|
|
| 每个日志记录类别的默认最小日志记录级别。 |
3.5. Quarkus 日志处理程序 复制链接链接已复制到粘贴板!
日志处理器是一个日志组件,它向接收者发送日志事件。Quarkus 包括以下日志处理程序:
syslog 处理程序将所有日志事件发送到 syslog 服务器(默认为 syslog 服务器在与应用程序相同的主机上运行)。syslog 处理程序默认为禁用。
3.6. 日志配置示例 复制链接链接已复制到粘贴板!
本节演示了如何为您的 Quarkus 项目配置日志记录。
src/main/resources/application.properties
src/main/resources/application.properties
默认情况下,根日志记录器级别设为 INFO。当您想要为较低级别收集日志时,如 DEBUG 或 TRACE,您需要更改根日志记录器配置。
src/main/resources/application.properties
第 4 章 配置 JSON 日志记录格式 复制链接链接已复制到粘贴板!
您可以将控制台日志的输出格式更改为 JSON,以便更轻松地处理和存储日志信息以便稍后进行分析。
要配置 JSON 日志记录格式,您需要在 Quarkus 项目中添加 quarkus-logging-json 扩展。quarkus-logging-json 扩展替换了控制台配置中的输出格式配置。将忽略格式字符串和颜色设置等控制台配置项。其他控制台配置项,包括那些控制异步日志记录和日志记录级别,继续应用。
流程
将
quarkus-logging-json扩展添加到应用程序的pom.xml文件中:pom.xml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow (可选)在
application.properties文件中为 JSON 日志记录设置配置集相关配置:src/main/resources/application.properties
%<profile>.<configuration_key>=<value>
%<profile>.<configuration_key>=<value>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 以下示例演示了如何为开发和测试配置集禁用 JSON 日志记录:
src/main/resources/application.properties
%dev.quarkus.log.console.json=false %test.quarkus.log.console.json=false
%dev.quarkus.log.console.json=false %test.quarkus.log.console.json=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.1. JSON 日志记录配置属性 复制链接链接已复制到粘贴板!
您可以使用以下配置属性配置 JSON 日志扩展:
| 配置属性 | 描述 | 类型 | 默认 |
|---|---|---|---|
|
| 启用 JSON 控制台格式化扩展。 | 布尔值 |
|
|
| 启用 JSON 记录的优质打印。[a] | 布尔值 |
|
|
|
日期的格式。 | 字符串 |
|
|
| 特殊记录分隔符.默认情况下,换行符用作分隔符。 | 字符串 | |
|
|
区的 ID。 | 字符串 |
|
|
| 例外的输出类型。 |
|
|
|
| 启用详细打印日志。详情包括源类名称、源文件名、源方法名称和源行号。[b] | 布尔值 |
|
[a]
有些处理器和 JSON 解析器可能无法读取打印的输出。
[b]
在从调用者检索值时,打印详细信息可能非常昂贵。
| |||
第 5 章 为 @QuarkusTest配置日志记录 复制链接链接已复制到粘贴板!
如果要为您的 @QuarkusTest 配置日志记录,您需要相应地设置 maven-surefire-plugin。您必须使用 java.util.logging.manager 系统属性指定 LogManager。