使用 Quarkus 配置日志记录

Red Hat build of Quarkus 1.11

摘要

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

前言

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

先决条件

对红帽文档提供反馈

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

注意

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

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

  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 Logging 外,JBoss LogManager 还支持几个第三方日志记录 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 日志管理器。您不需要包含任何 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.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>

第 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";
          }
      }

      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";
          }
      }

      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 文件中配置日志输出:

    src/main/resources/application.properties

    <configuration_key>=<value>

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

    src/main/resources/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

第 3 章 设置运行时配置

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

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

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

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

过量日志记录对性能有影响。您可以调整最小日志级别,以仅收集应用程序的相关数据。减少日志卷可能会优化内存用量并改进应用程序的性能。例如,在原生执行中,最小级别检查(即 TraceEnabled)可以被折叠为 false,这会导致死代码删除。

流程

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

    src/main/resources/application.properties

    <configuration_key>=<value>

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

    src/main/resources/application.properties

    quarkus.log.level=INFO
    quarkus.log.category."org.hibernate".level=DEBUG

    注意

    当您通过命令行设置配置属性时,请确保转义 "。例如 -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>

    src/main/resources/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

3.1.1. 日志记录格式字符串

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

表 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

Newline

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

%N

进程名称

当前进程的名称

%p

级别

消息的日志记录级别

%r

相对时间

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

%s

简单消息

没有异常追踪的日志消息

%t

线程名称

线程名称

%t{id}

线程 ID

线程 ID

%z{<zone name>}

时区

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

%X{<MDC property name>}

映射关联上下文值

来自 Mapped mailboxs 上下文的值

%X

映射的过期上下文值

来自 Mapped mailboxs 上下文的所有值,格式为 {property.key=property.value}

%x

嵌套的过期上下文值

来自 Nested mailboxs 上下文的所有值,格式为 {value1.value2}

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

3.2. 日志记录类别设置

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

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

表 3.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] 默认情况下,配置的类别从根日志记录器类别继承所有附加的处理程序。
注意

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

3.3. 日志记录级别

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

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

日志级别描述

OFF

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

FATAL

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

ERROR

请求出现重大中断,或无法为请求提供服务。

WARN

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

INFO

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

DEBUG

传达生命周期或非请求绑定事件的额外信息,这些事件对调试非常有用。

TRACE

传递额外请求的调试信息的消息可能非常高。

ALL

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

注意

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

3.4. 根日志记录器配置

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

表 3.4. 根日志记录器配置属性

属性名称Default(默认)描述

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

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

注意

默认情况下,根日志记录器级别设置为 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

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

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

    src/main/resources/application.properties

    %<profile>.<configuration_key>=<value>

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

    src/main/resources/application.properties

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

4.1. JSON 日志记录配置属性

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

表 4.1. JSON 配置属性

配置属性描述类型Default(默认)

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

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

字符串

 

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>

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

第 6 章 其他资源

更新于 2023-05-16

法律通告

Copyright © 2023 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.