使用 Quarkus 配置日志记录


Red Hat build of Quarkus 2.13

摘要

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

第 1 章 使用 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 的日志。

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 方法
  • 使用注解声明

流程

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

    1. 创建 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";
          }
      }

      1
      为您要使用的每个类命名空间添加 org.jboss.logging.Logger import 语句。
      2
      添加对各个类的日志记录器单例的引用。
      3
      为日志消息设置日志记录级别。
    2. 在 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";
          }
      }

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

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

  2. (可选)在 application.properties 文件中配置日志输出:

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

    application.properties 文件示例

    quarkus.log.file.enable=true
    quarkus.log.file.path=/tmp/trace.log

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

    在开发模式下运行应用程序

    ./mvnw quarkus:dev

  4. 进入 http://localhost:8080/hello
  5. 根据您的配置,查看终端或日志文件中的日志消息。

    将日志级别设置为 INFOExampleResource.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 日志记录,并包含 Hibernate DEBUG 日志:

    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. 日志记录格式字符串

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

Expand
表 1.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

newline

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

%N

进程名称

当前进程的名称

%p

级别

消息的日志记录级别

%r

相对时间

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

%s

简单消息

没有异常追踪的日志消息

%t

线程名称

线程名称

%T{id}

线程 ID

线程 ID

%z{<zone name>}

时区

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

%x{<MDC 属性 name>}

映射诊断上下文值

映射诊断上下文中的值

%X

映射诊断上下文值

来自 Mapped Diagnostics Context 的所有值,格式为 {property.key=property.value}

%x

嵌套诊断上下文值

{value1.value2} 格式的 Nested Diagnostics Context 的所有值

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

1.3.2. 日志记录类别设置

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

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

Expand
表 1.2. 日志记录类别配置属性
属性名称default描述

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

在将日志记录类别名称放在属性名称中时,将日志记录类别名称放在双引号中,以转义通常属于类别名称的句点(.)。

1.3.3. 日志记录级别

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

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

OFF

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

FATAL

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

ERROR

请求出现重大中断,或者无法服务请求。

WARN

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

INFO

服务生命周期事件或重要相关的非常频率信息。

DEBUG

提供有关生命周期或非请求绑定事件的额外调试信息的消息。

TRACE

传递的消息具有高频率,可提供额外每个请求的调试信息。

ALL

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

注意

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

1.3.4. 根日志记录器配置

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

Expand
表 1.4. 根日志记录器配置属性
属性名称default描述

quarkus.log.level

INFO

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

quarkus.log.min-level

DEBUG

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

1.3.5. Quarkus 日志处理程序

日志处理程序是一个日志记录组件,将日志事件发送到接收者。Quarkus 包括以下日志处理程序:

控制台日志处理程序
控制台日志处理程序默认为启用。它将所有日志事件输出到应用程序的控制台(通常是系统的 stdout)。
文件日志处理程序
文件日志处理程序默认为禁用。它将所有日志事件输出到应用程序主机上的文件中。文件日志处理程序支持日志文件轮转。
syslog 日志处理程序

syslog 是一个在类似 Unix 的系统上发送日志消息的协议。syslog 协议的规格在 RFC 5424 中定义。

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

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。当您要收集较低级别的日志时,更改根日志记录器配置,如 DEBUGTRACE

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 扩展替换了控制台配置中的输出格式配置。

  • 控制台配置项(如格式字符串和颜色设置)将被忽略。
  • 其他控制台配置项目(包括控制异步日志记录和日志记录级别)继续应用。

流程

  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>

  2. (可选)在 application.properties 文件中为 JSON 日志记录设置特定于配置集的配置:

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

    application.properties 文件示例

    %dev.quarkus.log.console.json=false
    %test.quarkus.log.console.json=false

1.4.1. JSON 日志记录配置属性

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

Expand
表 1.5. JSON 配置属性
配置属性描述类型default

quarkus.log.console.json

启用 JSON 控制台格式扩展。

布尔值

true

quarkus.log.console.json.pretty-print

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

布尔值

false

quarkus.log.console.json.date-format

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

string

default

quarkus.log.console.json.record-delimiter

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

string

 

quarkus.log.console.json.zone-id

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

string

default

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

异常的输出类型。

详细、格式化、详细和格式化

详细

quarkus.log.console.json.print-details

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

布尔值

false

[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>

    1
    添加 org.jboss.logmanager.LogManager
    2
    为所有日志记录类别启用调试日志记录。

法律通告

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2026 Red Hat
返回顶部