使用 Quarkus 配置日志


Red Hat build of Quarkus 2.2

指南

摘要

配置日志记录以收集有关应用程序内发生的事件的信息。

前言

作为应用程序开发人员,您可以使用日志记录来查看和记录应用程序运行时发生的事件的消息。日志消息提供在开发和测试过程中用来调试应用程序的信息,并在生产环境中监控应用程序。

先决条件

对红帽文档提供反馈

我们非常感谢您对我们的技术内容提供反馈,并鼓励您告诉我们您的想法。如果您想添加评论,提供见解、纠正拼写错误甚至询问问题,您可以在文档中直接这样做。

注意

您必须有一个红帽帐户并登录到客户门户网站。

要从客户门户网站提交文档反馈,请执行以下操作:

  1. 选择 Multi-page HTML 格式。
  2. 点文档右上角的 反馈 按钮。
  3. 突出显示您要提供反馈的文本部分。
  4. 点高亮文本旁的添加反馈对话框。
  5. 在页面右侧的文本框中输入您的反馈,然后单击 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>
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

您可以通过为使用的第三方日志记录实现配置 JBoss Logging 适配器来防止这个错误。

流程

  • 根据您使用的日志记录库,将其中一个适配器添加到您的 pom.xml 文件中:

    • Apache Commons Logging:

      pom.xml

      <dependency>
          <groupId>org.jboss.logging</groupId>
          <artifactId>commons-logging-jboss-logging</artifactId>
      </dependency>
      Copy to Clipboard Toggle word wrap

    • Log4j:

      pom.xml

      <dependency>
          <groupId>org.jboss.logmanager</groupId>
          <artifactId>log4j-jboss-logmanager</artifactId>
      </dependency>
      Copy to Clipboard Toggle word wrap

    • Log4j2:

      pom.xml

      <dependency>
          <groupId>org.jboss.logmanager</groupId>
          <artifactId>log4j2-jboss-logmanager</artifactId>
      </dependency>
      Copy to Clipboard Toggle word wrap

    • SLF4j:

      pom.xml

      <dependency>
          <groupId>org.jboss.slf4j</groupId>
          <artifactId>slf4j-jboss-logmanager</artifactId>
      </dependency>
      Copy to Clipboard Toggle word wrap

第 2 章 为应用程序启用 JBoss Logging

当您想使用 JBoss Logging 来收集应用程序日志时,您必须向您要生成日志的每个类添加一个日志记录器。以下流程演示了如何以编程方式使用 API 方法或声明性地将日志记录添加到应用程序中。

流程

  1. 根据您的应用程序代码,使用以下方法之一:

    1. 创建一个 org.jboss.logging.Logger 实例,并通过为每个类调用静态方法 Logger.getLogger(Class) 初始化它:

      src/main/java/org/acme/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";
          }
      }
      Copy to Clipboard Toggle word wrap

      1
      为您要使用的每个类命名空间添加 org.jboss.logging.Logger import 语句。
      2
      添加对各个类日志记录器单例的引用。
      3
      为日志消息设置日志级别。
    2. 在您的 Bean 和资源类中注入已配置的 org.jboss.logging.Logger 实例:

      src/main/java/org/acme/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";
          }
      }
      Copy to Clipboard Toggle word wrap

      1
      为您要使用的每个类命名空间添加 org.jboss.logging.Logger import 语句。
      2
      声明类的完全限定类名称用作日志记录器名称,相当于初始化声明 org.jboss.logging.Logger.getLogger(ExampleResource.class)
      3
      为日志记录器设置名称。在本例中,日志记录器名称为 foo,相当于初始化声明 org.jboss.logging.Logger.getLogger("foo")
      注意

      日志记录器实例在内部缓存。您注入到 Bean 的日志记录器,为所有 Bean 实例共享,以避免与日志记录器实例化相关的可能性能。

  2. (可选)在 应用程序.properties 文件中配置日志输出:

    src/main/resources/application.properties

    <configuration_key>=<value>
    Copy to Clipboard Toggle word wrap

    例如,您可以创建一个日志文件并将输出输出到控制台以及文件:

    src/main/resources/application.properties

    quarkus.log.file.enable=true
    quarkus.log.file.path=/tmp/trace.log
    Copy to Clipboard Toggle word wrap

  3. 以开发模式运行应用程序:

    ./mvnw quarkus:dev
    Copy to Clipboard Toggle word wrap
  4. 导航到 http://localhost:8080/hello
  5. 根据您的配置,查看终端或日志文件中的日志消息。

    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
    Copy to Clipboard Toggle word wrap

第 3 章 设置运行时配置

您可以在 application.properties 文件中配置日志记录级别和日志类别设置。

日志记录类别是层级的。当您为类别设置日志记录级别时,配置会应用到该类别的所有子类别。

有两个日志记录级别设置:日志级别和最低日志记录级别。默认的日志记录级别为 INFO,默认的最小日志记录级别为 DEBUG。您可以使用 quarkus.log.levelquarkus.log.min-level 属性或 category 来全局调整。

当您在最小日志记录级别下设置日志记录级别时,还必须调整最小日志记录级别。否则,最小日志级别的值会覆盖日志级别。

过量日志记录对性能有影响。您可以调整最小日志级别来只收集与应用程序相关的数据。减少日志卷可能会优化内存用量并改进应用程序的性能。例如,以原生执行级别可启用较低级别的检查(israceEnabled)来折叠到 false,这会导致死代码淘汰。

流程

  • application.properties 文件中配置日志记录:

    src/main/resources/application.properties

    <configuration_key>=<value>
    Copy to Clipboard Toggle word wrap

    以下示例演示了如何将默认日志级别设置为 INFO 日志记录,并包含 Hibernate DEBUG 日志:

    src/main/resources/application.properties

    quarkus.log.level=INFO
    quarkus.log.category."org.hibernate".level=DEBUG
    Copy to Clipboard Toggle word wrap

    注意

    当您使用命令行设置配置属性时,请确保转义 "。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>
    Copy to Clipboard Toggle word wrap

    src/main/resources/application.properties

    quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
    Copy to Clipboard Toggle word wrap

    这个配置会生成以下日志消息格式:

    14:11:07 INFO  [ExampleResource] (executor-thread-199) Hello
    Copy to Clipboard Toggle word wrap

3.1.1. 日志记录格式字符串

下表显示了可用于配置日志消息格式的字符串符号。

Expand
表 3.1. 支持的日志记录格式符号
符号概述描述

%%

%

简单的 % 字符。

%c

类别

类别名称

%C

源类

源类名称 [a]

%d{xxx}

Date

给定日期格式字符串的日期,遵循 java.text.SimpleDateFormat

%e

例外

异常堆栈追踪

%F

源文件

源文件名 [a]

%h

主机名

系统简单主机名

%H

限定主机名

系统的完全限定主机名。根据操作系统配置,它可能和简单主机名相同。

%i

进程 ID

当前进程 PID

%l

源位置

源位置(源文件名、行号、类名称和方法名称) [a]

%L

源行

源行号 [a]

%m

完整信息

包括异常追踪的日志消息

%M

源方法

源方法名称 [a]

%n

换行符

特定于平台的行分隔符字符串

%N

进程名称

当前进程的名称

%p

级别

消息的日志记录级别

%r

相对时间

应用程序日志开始以来的相对时间(毫秒)

%s

简单消息

没有例外追踪的日志消息

%t

线程名称

线程名称

%t{id}

线程 ID

线程 ID

%z{<zone name>}

时区

输出的时区,格式为 < zone name&gt;

%x{<MDC 属性 name>}

映射的诊断上下文值

映射诊断上下文中的值

%X

映射的诊断上下文值

来自映射诊断上下文的所有值,格式为 {property.key=property.value}

%x

嵌套的诊断上下文值

嵌套的 Diagnostics 上下文中的所有值,格式为 {value1.value2}

[a] 格式化检查调用者信息的序列可能会影响性能。

3.2. 日志类别设置

您可以使用日志类别根据严重性或它们所属的组件来组织日志消息。您可以独立配置每个类别。

对于每个类别,同一设置都适用于 console、file 和 syslog。您可以通过将一个或多个指定的处理程序附加到类别来覆盖设置。

Expand
表 3.2. 日志类别配置属性
属性名称默认描述

quarkus.log.category."<category-name>".level

INFO [a]

配置 < category-name> 类别的 级别。

quarkus.log.category."<category-name>".min-level

DEBUG

配置 < category-name& gt; 类别的最小日志记录级别。

quarkus.log.category."<category-name>".use-parent-handlers

true

启用日志记录器,将其输出发送到父日志记录器。

quarkus.log.category."<category-name>".handlers=[<handler>]

empty [b]

要附加到特定类别的处理程序的名称。

[a] 有些扩展定义了特定类别的自定义默认日志记录级别,以减少日志 noise。在配置中设置日志级别会覆盖任何定义的日志记录级别。
[b] 默认情况下,配置的类别从根日志记录器类别继承所有附加的处理程序。
注意

在属性名称中使用日志类别名称时,您必须将日志类别名称放在双引号内,以转义通常是类别名称一部分的句点(.)。

3.3. 日志级别

您可以使用日志级别根据严重性对日志进行分类,或它们对 Quarkus 应用程序的健康状态和稳定性的影响。通过日志记录级别,您可以从纯信息的事件过滤关键事件。

Expand
表 3.3. Quarkus 支持以下日志记录级别:
日志级别描述

OFF

关闭日志记录的特殊级别。

FATAL

关键服务故障或无法完成服务请求。

ERROR

对请求或无法服务请求的中断。

WARN

非关键服务错误或不需要立即更正的问题。

INFO

服务生命周期事件或重要相关 f-low-frequency 信息。

DEBUG

传达有关生命周期或非请求绑定事件的额外信息(对于调试非常有用)。

TRACE

布置额外每个请求的调试信息(可能非常高的频率)的信息。

ALL

所有消息的特殊级别,包括自定义级别。

注意

另外,您还可以使用 java.util.logging 软件包中描述的日志记录级别名称。

3.4. 根日志记录器配置

根日志记录器类别位于日志记录器层次结构的顶部。根日志记录器捕获指定日志记录级别或更高的所有日志消息,它们发送到服务器,不被日志记录类别捕获。根日志记录器类别在日志配置的顶层配置。

Expand
表 3.4. 根日志记录器配置属性
属性名称默认描述

quarkus.log.level

INFO

每个日志记录类别的默认日志记录级别。

quarkus.log.min-level

DEBUG

每个日志记录类别的默认最小日志记录级别。

3.5. Quarkus 日志处理程序

日志处理器是一个日志组件,它向接收者发送日志事件。Quarkus 包括以下日志处理程序:

控制台日志处理器
控制台日志处理程序被默认启用。它将所有日志事件输出到应用程序的控制台(通常用于系统的 stdout)。
文件日志处理程序
文件日志处理程序默认为禁用。它将所有日志事件输出到应用程序主机上的文件中。文件日志处理程序支持日志文件轮转。
syslog 日志处理器
syslog 是一个在类似 Unix 的系统中发送日志消息的协议。syslog 协议的规格在 RFC 5424 中定义。

syslog 处理程序将所有日志事件发送到 syslog 服务器(默认为 syslog 服务器在与应用程序相同的主机上运行)。syslog 处理程序默认为禁用。

3.6. 日志配置示例

本节演示了如何为您的 Quarkus 项目配置日志记录。

src/main/resources/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.log.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
Copy to Clipboard Toggle word wrap

src/main/resources/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
Copy to Clipboard Toggle word wrap

注意

默认情况下,根日志记录器级别设为 INFO。当您想要为较低级别收集日志时,如 DEBUGTRACE,您需要更改根日志记录器配置。

src/main/resources/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
Copy to Clipboard Toggle word wrap

第 4 章 配置 JSON 日志记录格式

您可以将控制台日志的输出格式更改为 JSON,以便更轻松地处理和存储日志信息以便稍后进行分析。

要配置 JSON 日志记录格式,您需要在 Quarkus 项目中添加 quarkus-logging-json 扩展。quarkus-logging-json 扩展替换了控制台配置中的输出格式配置。将忽略格式字符串和颜色设置等控制台配置项。其他控制台配置项,包括那些控制异步日志记录和日志记录级别,继续应用。

流程

  1. 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>
    Copy to Clipboard Toggle word wrap

  2. (可选)在 application.properties 文件中为 JSON 日志记录设置配置集相关配置:

    src/main/resources/application.properties

    %<profile>.<configuration_key>=<value>
    Copy to Clipboard Toggle word wrap

    以下示例演示了如何为开发和测试配置集禁用 JSON 日志记录:

    src/main/resources/application.properties

    %dev.quarkus.log.console.json=false
    %test.quarkus.log.console.json=false
    Copy to Clipboard Toggle word wrap

4.1. JSON 日志记录配置属性

您可以使用以下配置属性配置 JSON 日志扩展:

Expand
表 4.1. JSON 配置属性
配置属性描述类型默认

quarkus.log.console.json

启用 JSON 控制台格式化扩展。

布尔值

true

quarkus.log.console.json.pretty-print

启用 JSON 记录的优质打印。[a]

布尔值

false

quarkus.log.console.json.date-format

日期的格式。默认 字符串设置要使用的默认格式。

字符串

default

quarkus.log.console.json.record-delimiter

特殊记录分隔符.默认情况下,换行符用作分隔符。

字符串

 

quarkus.log.console.json.zone-id

区的 ID。默认 字符串设置要使用的默认区。

字符串

default

quarkus.log.console.json.exception-output-type

例外的输出类型。

详细、格式化、详细格式

详细

quarkus.log.console.json.print-details

启用详细打印日志。详情包括源类名称、源文件名、源方法名称和源行号。[b]

布尔值

false

[a] 有些处理器和 JSON 解析器可能无法读取打印的输出。
[b] 在从调用者检索值时,打印详细信息可能非常昂贵。

第 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>
    Copy to Clipboard Toggle word wrap

    1
    添加 org.jboss.logmanager.LogManager
    2
    为所有日志类别启用调试日志记录。
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

Theme

© 2025 Red Hat