quarkus：详细总结日志设置的方式

一、日志级别

这些是 Quarkus 使用的日志级别：

• OFF：关闭日志记录的特殊级别。
• FATAL：严重的服务故障/完全无法为任何类型的请求提供服务。
• ERROR：请求中的重大中断或无法为请求提供服务。
• WARN：可能不需要立即纠正的非关键服务错误或问题。
• INFO：服务生命周期事件或重要的相关极低频信息。
• DEBUG：传达有关生命周期或非请求绑定事件的额外信息的消息，这些信息可能有助于调试。
• TRACE：传达额外的每请求调试信息的消息可能频率很高。
• ALL：所有消息的特殊级别，包括自定义级别。

二、运行时配置

运行时日志记录在 application.properties 文件中配置，例如，将默认日志级别设置为 INFO 日志记录并包括 Hibernate DEBUG 日志：

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

将日志级别设置为低于 DEBUG 需要调整最低日志级别，可以通过 quarkus.log.min-level 全局属性或如上例所示的每个类别，以及调整日志级别本身。

最低日志记录级别设置了 Quarkus 可能需要生成的最低级别，从而为优化机会打开了大门。例如，在本机执行中，最低级别允许将较低级别的检查（例如 isTraceEnabled）折叠为 false，从而消除永远不会执行的代码的死代码。

三、记录类别

日志记录是在每个类别的基础上完成的。每个类别都可以独立配置。适用于某个类别的配置也将适用于该类别的所有子类别，除非有更具体的匹配子类别配置。对于每个类别，在（控制台/文件/系统日志）上配置的相同设置适用。这些也可以通过将一个或多个命名的处理程序附加到一个类别来覆盖。

属性名称	默认值	描述
quarkus.log.category.“<category-name>”.level	INFO	用于配置名为<category-name> 的类别的级别。引号是必要的。
quarkus.log.category.“<category-name>”.min-level	DEBUG	用于配置名为<category-name> 的类别的最低日志记录级别。引号是必要的。
quarkus.log.category.“<category-name>”.use-parent-handlers	true	指定此记录器是否应将其输出发送到其父记录器。
quarkus.log.category.“<category-name>”.handlers=[<handler>]	empty	要附加到特定类别的处理程序的名称。

四、根记录器配置Root logger configuration

根记录器类别单独处理，并通过以下属性进行配置：

属性名称	默认值	描述
quarkus.log.level	INFO	每个日志类别的默认日志级别。
quarkus.log.min-level	DEBUG	每个日志类别的默认最低日志级别。

如果给定记录器类别不存在级别配置，则检查封闭（父）类别。如果没有配置包含所讨论类别的类别，则使用根记录器配置。

五、记录格式

默认情况下，Quarkus 使用基于模式的日志格式化程序生成人类可读的文本日志。

您可以通过专用属性为每个日志处理程序配置格式。对于控制台处理程序，属性是 quarkus.log.console.format。

日志格式字符串支持以下符号：

符号	概要	说明
%%	%	呈现一个简单的 % 字符。
%c	Category	呈现类别名称。
%C	Source class	呈现源类名称。
%d{xxx}	Date	使用给定的日期格式字符串呈现日期，它使用 java.text.SimpleDateFormat 定义的语法。
%e	Exception	呈现抛出的异常（如果有）。
%F	Source file	呈现源文件名。
%h	Host name	呈现系统简单主机名。
%H	Qualified host name	呈现系统的完全限定主机名，它可能与简单主机名相同，具体取决于操作系统配置。
%i	Process ID	呈现当前进程 PID。
%l	Source location	呈现源位置信息，包括源文件名、行号、类名和方法名。
%L	Source line	呈现源行号。
%m	Full Message	呈现日志消息和异常（如果有）。
%M	Source method	呈现源方法名称。
%n	Newline	呈现特定于平台的行分隔符字符串。
%N	Process name	呈现当前进程的名称。
%p	Level	呈现消息的日志级别。
%r	Relative time	呈现自应用程序日志启动以来的时间（以毫秒为单位）。
%s	Simple message	只呈现日志消息，没有异常跟踪。
%t	Thread name	呈现线程名称。
%t{id}	Thread ID	呈现线程 ID。
%z{<zone name>}	Time zone	将输出的时区设置为 <zone name>。
%X{<MDC property name>}	映射诊断上下文值	呈现来自映射诊断上下文的值
%X	映射的诊断上下文值	以 {property.key=property.value} 格式呈现来自 Mapped Diagnostics Context 的所有值
%x	嵌套诊断上下文值	以 {value1.value2} 格式呈现嵌套诊断上下文中的所有值

六、替代控制台日志记录格式

可以更改控制台日志的输出格​​式。这在 Quarkus 应用程序的输出由服务捕获的环境中很有用，例如，该服务可以处理和存储日志信息以供以后分析。

JSON 记录格式

为了配置 JSON 日志记录格式，可以使用 quarkus-logging-json 扩展。将此扩展添加到您的构建文件中，如下面的代码片段所示：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-logging-json</artifactId>
</dependency>

默认情况下，此扩展的存在将替换控制台配置中的输出格式配置。这意味着格式字符串和颜色设置（如果有）将被忽略。其他控制台配置项，包括那些控制异步日志记录和日志级别的配置项，将继续应用。

对于某些人来说，在开发模式下使用人类可读（非结构化）的日志记录和在生产模式下使用 JSON 日志记录（结构化）是有意义的。这可以使用不同的配置文件来实现，如以下配置所示。

在开发和测试模式的 application.properties 中禁用 JSON 日志记录

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

七、Log Handlers

日志处理程序是负责将日志事件发送给接收者的日志记录组件。 Quarkus 带有三种不同的日志处理程序：控制台、文件和系统日志。

控制台日志处理程序

• 默认情况下启用控制台日志处理程序。它将所有日志事件输出到应用程序的控制台（通常是系统的标准输出）。

记录过滤器

• 日志处理程序（如控制台日志处理程序）可以有一个与之关联的过滤器，其目的是确定一条记录是否应该实际记录或不记录。
• 这些过滤器是通过在实现 java.util.logging.Filter 的（最终）类上放置 @io.quarkus.logging.LoggingFilter 注释并设置 name 属性来注册的。
• 最后，使用适当处理程序的过滤器配置属性附加过滤器。

比方说，我们想从控制台日志中过滤掉包含部分文本的日志记录。文本本身是应用程序配置的一部分，不是硬编码的。我们可以这样写一个过滤器：

import io.quarkus.logging.LoggingFilter;
import java.util.logging.Filter;
import java.util.logging.LogRecord;

@LoggingFilter(name = "my-filter")
public final class TestFilter implements Filter {

    private final String part;

    public TestFilter(@ConfigProperty(name = "my-filter.part") String part) {
        this.part = part;
    }

    @Override
    public boolean isLoggable(LogRecord record) {
        return !record.getMessage().contains(part);
    }
}

并以通常的 Quarkus 方式配置它（例如使用 application.properties），如下所示：

my-filter.part=TEST

我们会像这样将此过滤器注册到控制台处理程序：

quarkus.log.console.filter=my-filter

八、文件日志处理程序

默认情况下禁用文件日志处理程序。它将所有日志事件输出到应用程序主机上的文件中。它支持日志文件轮换。

九、Syslog 日志处理程序

Syslog 是一种协议，用于使用 RFC 5424 定义的协议在类 Unix 系统上发送日志消息。

系统日志处理程序将所有日志事件发送到系统日志服务器（默认情况下，系统日志服务器是应用程序的本地服务器）。默认情况下禁用。

十、使用示例

控制台调试日志记录，Quarkus 日志（信息）除外，无颜色，缩短时间，缩短类别前缀

quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
quarkus.log.console.level=DEBUG
quarkus.console.color=false

quarkus.log.category."io.quarkus".level=INFO

文件跟踪记录配置

quarkus.log.file.enable=true
# Send output to a trace.log file under the /tmp directory
quarkus.log.file.path=/tmp/trace.log
quarkus.log.file.level=TRACE
quarkus.log.file.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Set 2 categories (io.quarkus.smallrye.jwt, io.undertow.request.security) to TRACE level
quarkus.log.min-level=TRACE
quarkus.log.category."io.quarkus.smallrye.jwt".level=TRACE
quarkus.log.category."io.undertow.request.security".level=TRACE

附加到类别的命名处理程序

# Send output to a trace.log file under the /tmp directory
quarkus.log.file.path=/tmp/trace.log
quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Configure a named handler that logs to console
quarkus.log.handler.console."STRUCTURED_LOGGING".format=%e%n
# Configure a named handler that logs to file
quarkus.log.handler.file."STRUCTURED_LOGGING_FILE".enable=true
quarkus.log.handler.file."STRUCTURED_LOGGING_FILE".format=%e%n
# Configure the category and link the two named handlers to it
quarkus.log.category."io.quarkus.category".level=INFO
quarkus.log.category."io.quarkus.category".handlers=STRUCTURED_LOGGING,STRUCTURED_LOGGING_FILE

附加到根记录器的命名处理程序

# configure a named file handler that sends the output to 'quarkus.log'
quarkus.log.handler.file.CONSOLE_MIRROR.enable=true
quarkus.log.handler.file.CONSOLE_MIRROR.path=quarkus.log
# attach the handler to the root logger
quarkus.log.handlers=CONSOLE_MIRROR

十一、日志记录配置参考

配置属性在构建时固定 - 所有其他配置属性在运行时都可以覆盖

配置属性	类型	默认值
quarkus.log.level 根类别的日志级别，用作所有类别的默认日志级别。JBoss Logging 支持 Apache 风格的日志级别：FATAL、ERROR、WARN、INFO、DEBUG、TRACE	Level	INFO
quarkus.log.handlers 要链接到根类别的其他处理程序的名称。这些处理程序在 consoleHandlers、fileHandlers 或 syslogHandlers 中定义。环境变量：QUARKUS_LOG_HANDLERS	list of string
quarkus.log.file.enable 如果应该启用文件日志记录 环境变量：QUARKUS_LOG_FILE_ENABLE	boolean	false
quarkus.log.file.format 日志格式 环境变量：QUARKUS_LOG_FILE_FORMAT	string	%d{yyyy-MM-dd HH:mm:ss,SSS} %h %N[%i] %-5p [%c{3.}] (%t) %s%e%n
quarkus.log.file.level 要写入文件的日志级别。环境变量：QUARKUS_LOG_FILE_LEVEL	Level	ALL
quarkus.log.file.path将写入日志的文件的名称。环境变量：QUARKUS_LOG_FILE_PATH	File	quarkus.log
quarkus.log.file.filter链接到文件处理程序的过滤器的名称。环境变量：QUARKUS_LOG_FILE_FILTER	string
quarkus.log.file.encoding使用的字符编码，环境变量：QUARKUS_LOG_FILE_ENCODING	Charset
quarkus.log.file.async是否异步记录，环境变量：QUARKUS_LOG_FILE_ASYNC	boolean	false
quarkus.log.file.async.queue-length，刷新写入之前使用的队列长度，环境变量：QUARKUS_LOG_FILE_ASYNC_QUEUE_LENGTH	int	512
quarkus.log.file.async.overflow，确定当队列已满时是否阻止发布者（而不是丢弃消息），环境变量：QUARKUS_LOG_FILE_ASYNC_OVERFLOW	block, discard	block
quarkus.log.file.rotation.max-file-size执行轮换后日志文件的最大文件大小。环境变量：QUARKUS_LOG_FILE_ROTATION_MAX_FILE_SIZE	MemorySize	10M
quarkus.log.handler.file.“file-handlers”.rotation.max-backup-index要保留的最大备份数。环境变量：QUARKUS_LOG_HANDLER_FILE__FILE_HANDLERS__ROTATION_MAX_BACKUP_INDEX	int	5
quarkus.log.handler.file.“file-handlers”.rotation.file-suffix文件处理程序旋转文件后缀。使用时，文件将根据其后缀旋转。示例文件后缀：.yyyy-MM-dd环境变量：QUARKUS_LOG_HANDLER_FILE__FILE_HANDLERS__ROTATION_FILE_SUFFIX	string
quarkus.log.handler.file.“file-handlers”.rotation.rotate-on-boot指示是否在服务器初始化时轮换日志文件。您需要设置最大文件大小或配置文件后缀才能使其正常工作。环境变量：QUARKUS_LOG_HANDLER_FILE__FILE_HANDLERS__ROTATION_ROTATE_ON_BOOT	boolean	true