日志记录

DeepSeek V3 中英对照 Logging

Spring Boot 使用 Commons Logging 进行所有内部日志记录，但底层的日志实现是开放的。默认配置提供了对 Java Util Logging、Log4j2 和 Logback 的支持。在每种情况下，日志记录器都预先配置为使用控制台输出，同时也可选择文件输出。

默认情况下，如果你使用 starters，Logback 会用于日志记录。同时包含了适当的 Logback 路由，以确保使用 Java Util Logging、Commons Logging、Log4J 或 SLF4J 的依赖库都能正常工作。

提示

Java 有很多可用的日志框架。如果上面的列表看起来令人困惑，请不要担心。通常，你不需要更改你的日志依赖，Spring Boot 的默认设置就能很好地工作。

提示

当你将应用程序部署到 servlet 容器或应用服务器时，使用 Java Util Logging API 执行的日志记录不会路由到应用程序的日志中。这可以防止容器或部署到容器中的其他应用程序执行的日志记录出现在你的应用程序日志中。

日志格式

Spring Boot 的默认日志输出类似于以下示例：

2025-01-23T11:42:36.681Z  INFO 125873 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Starting MyApplication using Java 17.0.14 with PID 125873 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2025-01-23T11:42:36.695Z  INFO 125873 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : No active profile set, falling back to 1 default profile: "default"
2025-01-23T11:42:39.235Z  INFO 125873 --- [myapp] [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port 8080 (http)
2025-01-23T11:42:39.254Z  INFO 125873 --- [myapp] [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2025-01-23T11:42:39.255Z  INFO 125873 --- [myapp] [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.34]
2025-01-23T11:42:39.337Z  INFO 125873 --- [myapp] [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2025-01-23T11:42:39.344Z  INFO 125873 --- [myapp] [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 2427 ms
2025-01-23T11:42:40.601Z  INFO 125873 --- [myapp] [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path '/'
2025-01-23T11:42:40.660Z  INFO 125873 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Started MyApplication in 5.215 seconds (process running for 6.387)
2025-01-23T11:42:40.682Z  INFO 125873 --- [myapp] [ionShutdownHook] o.s.b.w.e.tomcat.GracefulShutdown        : Commencing graceful shutdown. Waiting for active requests to complete
2025-01-23T11:42:40.712Z  INFO 125873 --- [myapp] [tomcat-shutdown] o.s.b.w.e.tomcat.GracefulShutdown        : Graceful shutdown complete

none

以下是输出的项目：

• 日期和时间：毫秒级精度，易于排序。

• 日志级别：ERROR、WARN、INFO、DEBUG 或 TRACE。

• 进程 ID。

• --- 分隔符：用于区分实际日志消息的开始。

• 应用程序名称：用方括号括起来（默认仅在设置了 spring.application.name 时记录）。

• 应用程序组：用方括号括起来（默认仅在设置了 spring.application.group 时记录）。

• 线程名称：用方括号括起来（在控制台输出中可能会被截断）。

• 关联 ID：如果启用了追踪功能（上例中未显示）。

• 日志记录器名称：通常是源类名（通常缩写）。

• 日志消息。

备注

Logback 没有 FATAL 级别。它被映射到 ERROR。

提示

如果你有 spring.application.name 属性但不希望它被记录在日志中，可以将 logging.include-application-name 设置为 false。

提示

如果你有 spring.application.group 属性但不希望它被记录，你可以将 logging.include-application-group 设置为 false。

提示

有关相关 ID 的更多详细信息，请参阅此文档。

控制台输出

默认的日志配置会将消息实时回显到控制台。默认情况下，会记录 ERROR 级别、WARN 级别和 INFO 级别的消息。你还可以通过在启动应用程序时添加 --debug 标志来启用“调试”模式。

$ java -jar myapp.jar --debug

shell

备注

你也可以在你的 application.properties 中指定 debug=true。

当启用调试模式时，会配置一组核心日志记录器（嵌入式容器、Hibernate 和 Spring Boot）以输出更多信息。启用调试模式并不会将您的应用程序配置为以 DEBUG 级别记录所有消息。

或者，你也可以通过使用 --trace 标志（或在 application.properties 中设置 trace=true）来启动你的应用程序，从而启用“trace”模式。这样做会为一些核心日志记录器（嵌入式容器、Hibernate 模式生成以及整个 Spring 组合）启用跟踪日志记录。

颜色编码输出

如果您的终端支持 ANSI，将使用彩色输出来提高可读性。您可以将 spring.output.ansi.enabled 设置为支持的值 来覆盖自动检测。

颜色编码通过使用 %clr 转换词进行配置。在最简单的形式中，转换器根据日志级别为输出着色，如下例所示：

%clr(%5p)

none

下表描述了日志级别与颜色的映射关系：

等级	颜色
FATAL	红色
ERROR	红色
WARN	黄色
INFO	绿色
DEBUG	绿色
TRACE	绿色

或者，你可以通过提供一个选项来指定应该使用的颜色或样式。例如，要使文本显示为黄色，请使用以下设置：

%clr(%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}){yellow}

none

支持以下颜色和样式：

• blue 蓝色

• cyan 青色

• faint 淡色

• green 绿色

• magenta 洋红色

• red 红色

• yellow 黄色

文件输出

默认情况下，Spring Boot 仅将日志输出到控制台，不会写入日志文件。如果你希望除了控制台输出外还写入日志文件，需要设置 logging.file.name 或 logging.file.path 属性（例如，在 application.properties 中）。如果同时设置了这两个属性，logging.file.path 会被忽略，仅使用 logging.file.name。

下表展示了如何一起使用 logging.* 属性：

表 1. 日志记录属性

logging.file.name	logging.file.path	描述
(无)	(无)	仅控制台日志记录。
特定文件（例如，my.log）	(无)	写入由 logging.file.name 指定的位置。该位置可以是绝对路径或相对于当前目录的路径。
(无)	特定目录（例如，/var/log）	将 spring.log 写入由 logging.file.path 指定的目录。该目录可以是绝对路径或相对于当前目录的路径。
特定文件	特定目录	写入由 logging.file.name 指定的位置，并忽略 logging.file.path。该位置可以是绝对路径或相对于当前目录的路径。

当日志文件达到 10 MB 时，会进行日志轮转。与控制台输出一样，默认情况下会记录 ERROR 级别、WARN 级别和 INFO 级别的消息。

提示

日志配置属性与实际使用的日志基础设施是独立的。因此，Spring Boot 并不管理特定的配置键（例如 Logback 的 logback.configurationFile）。

文件轮换

如果你正在使用 Logback，可以通过 application.properties 或 application.yaml 文件来微调日志轮转设置。对于其他日志系统，你需要直接自行配置轮转设置（例如，如果你使用 Log4j2，则可以添加 log4j2.xml 或 log4j2-spring.xml 文件）。

支持以下轮换策略属性：

名称	描述
logging.logback.rollingpolicy.file-name-pattern	用于创建日志归档的文件名模式。
logging.logback.rollingpolicy.clean-history-on-start	是否在应用程序启动时进行日志归档清理。
logging.logback.rollingpolicy.max-file-size	日志文件在被归档前的最大大小。
logging.logback.rollingpolicy.total-size-cap	日志归档在删除前可以占用的最大空间。
logging.logback.rollingpolicy.max-history	保留的归档日志文件的最大数量（默认为 7）。

日志级别

所有支持的日志系统都可以通过 Spring Environment（例如在 application.properties 中）使用 logging.level.<logger-name>=<level> 来设置日志级别，其中 level 可以是 TRACE、DEBUG、INFO、WARN、ERROR、FATAL 或 OFF 之一。可以通过 logging.level.root 来配置 root 日志记录器。

以下示例展示了 application.properties 中可能的日志配置：

Properties

logging.level.root=warn
logging.level.org.springframework.web=debug
logging.level.org.hibernate=error

properties

YAML

logging:
  level:
    root: "warn"
    org.springframework.web: "debug"
    org.hibernate: "error"

yaml

也可以通过环境变量来设置日志级别。例如，LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG 会将 org.springframework.web 的日志级别设置为 DEBUG。

备注

上述方法仅适用于包级别的日志记录。由于宽松绑定 总是将环境变量转换为小写，因此无法通过这种方式为单个类配置日志记录。如果需要为某个类配置日志记录，可以使用 SPRING_APPLICATION_JSON 变量。

日志组

将相关的日志记录器分组以便同时配置它们通常非常有用。例如，你可能经常需要更改 所有 与 Tomcat 相关的日志记录器的日志级别，但你很难记住所有顶级包的名称。

为了帮助实现这一点，Spring Boot 允许你在 Spring Environment 中定义日志组。例如，你可以通过将以下内容添加到 application.properties 文件中来定义一个名为 “tomcat” 的日志组：

Properties

logging.group.tomcat=org.apache.catalina,org.apache.coyote,org.apache.tomcat

properties

YAML

logging:
  group:
    tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"

yaml

一旦定义了日志组，你可以通过一行代码来更改组内所有日志记录器的级别：

Properties

logging.level.tomcat=trace

properties

YAML

logging:
  level:
    tomcat: "trace"

yaml

Spring Boot 包含了以下预定义的日志组，可以直接使用：

名称	日志记录器
web	org.springframework.core.codec, org.springframework.http, org.springframework.web, org.springframework.boot.actuate.endpoint.web, org.springframework.boot.web.servlet.ServletContextInitializerBeans
sql	org.springframework.jdbc.core, org.hibernate.SQL, LoggerListener

使用日志关闭钩子

为了在应用程序终止时释放日志资源，提供了一个关闭钩子，当 JVM 退出时，该钩子将触发日志系统清理。除非您的应用程序以 war 文件形式部署，否则此关闭钩子会自动注册。如果您的应用程序具有复杂的上下文层次结构，关闭钩子可能无法满足您的需求。如果确实如此，请禁用关闭钩子，并直接研究底层日志系统提供的选项。例如，Logback 提供了上下文选择器，允许每个 Logger 在其自己的上下文中创建。您可以使用 logging.register-shutdown-hook 属性来禁用关闭钩子。将其设置为 false 将禁用注册。您可以在 application.properties 或 application.yaml 文件中设置该属性：

Properties

logging.register-shutdown-hook=false

properties

YAML

logging:
  register-shutdown-hook: false

yaml

自定义日志配置

可以通过在类路径中包含适当的库来激活各种日志系统，并且可以通过在类路径的根目录或由以下 Spring Environment 属性指定的位置提供合适的配置文件来进行进一步的自定义：logging.config。

你可以通过使用 org.springframework.boot.logging.LoggingSystem 系统属性来强制 Spring Boot 使用特定的日志系统。该值应为 LoggingSystem 实现的完全限定类名。你也可以通过使用 none 值来完全禁用 Spring Boot 的日志配置。

备注

由于日志记录是在 ApplicationContext 创建之前初始化的，因此无法通过 Spring @Configuration 文件中的 @PropertySources 来控制日志记录。唯一可以更改日志系统或完全禁用它的是通过系统属性。

根据您的日志系统，以下文件会被加载：

日志系统	自定义配置
Logback	logback-spring.xml, logback-spring.groovy, logback.xml, 或 logback.groovy
Log4j2	log4j2-spring.xml 或 log4j2.xml
JDK (Java Util Logging)	logging.properties

备注

如果可能，我们建议您在日志配置中使用 -spring 变体（例如，使用 logback-spring.xml 而不是 logback.xml）。如果您使用标准配置位置，Spring 将无法完全控制日志的初始化。

注意

已知 Java Util Logging 在从 '可执行 jar' 运行时存在类加载问题，可能会导致问题。如果可能的话，我们建议您在从 '可执行 jar' 运行时避免使用它。

为了帮助进行自定义配置，一些其他属性会从 Spring Environment 传递到系统属性中。这样，这些属性就可以被日志系统配置所使用。例如，在 application.properties 中设置 logging.file.name 或将 LOGGING_FILE_NAME 作为环境变量，将会导致 LOG_FILE 系统属性被设置。下表描述了这些被传递的属性：

Spring 环境	系统属性	说明
logging.exception-conversion-word	LOG_EXCEPTION_CONVERSION_WORD	记录异常时使用的转换词。
logging.file.name	LOG_FILE	如果定义，它将在默认日志配置中使用。
logging.file.path	LOG_PATH	如果定义，它将在默认日志配置中使用。
logging.pattern.console	CONSOLE_LOG_PATTERN	在控制台（stdout）上使用的日志模式。
logging.pattern.dateformat	LOG_DATEFORMAT_PATTERN	日志日期格式的 Appender 模式。
logging.charset.console	CONSOLE_LOG_CHARSET	控制台日志记录使用的字符集。
logging.threshold.console	CONSOLE_LOG_THRESHOLD	控制台日志记录使用的日志级别阈值。
logging.pattern.file	FILE_LOG_PATTERN	在文件中使用的日志模式（如果启用了 LOG_FILE）。
logging.charset.file	FILE_LOG_CHARSET	文件日志记录使用的字符集（如果启用了 LOG_FILE）。
logging.threshold.file	FILE_LOG_THRESHOLD	文件日志记录使用的日志级别阈值。
logging.pattern.level	LOG_LEVEL_PATTERN	渲染日志级别时使用的格式（默认 %5p）。
logging.structured.format.console	CONSOLE_LOG_STRUCTURED_FORMAT	控制台日志记录使用的结构化日志格式。
logging.structured.format.file	FILE_LOG_STRUCTURED_FORMAT	文件日志记录使用的结构化日志格式。
PID	PID	当前进程 ID（如果可能且尚未定义为操作系统环境变量，则自动发现）。

如果你使用 Logback，以下属性也会被转移：

Spring 环境变量	系统属性	说明
logging.logback.rollingpolicy.file-name-pattern	LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN	滚动日志文件名的模式（默认值为 ${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz）。
logging.logback.rollingpolicy.clean-history-on-start	LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START	是否在启动时清理归档日志文件。
logging.logback.rollingpolicy.max-file-size	LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE	日志文件的最大大小。
logging.logback.rollingpolicy.total-size-cap	LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP	要保留的日志备份的总大小。
logging.logback.rollingpolicy.max-history	LOGBACK_ROLLINGPOLICY_MAX_HISTORY	要保留的归档日志文件的最大数量。

所有支持的日志系统在解析其配置文件时都可以查阅系统属性。有关示例，请参见 spring-boot.jar 中的默认配置：

• Logback

• Log4j 2

• Java Util logging

提示

如果你想在日志属性中使用占位符，你应该使用 Spring Boot 的语法，而不是底层框架的语法。特别是，如果你使用 Logback，你应该使用 : 作为属性名和其默认值之间的分隔符，而不是 :-。

提示

你可以通过仅覆盖 LOG_LEVEL_PATTERN（或使用 Logback 时的 logging.pattern.level）来向日志行添加 MDC 和其他临时内容。例如，如果你使用 logging.pattern.level=user:%X{user} %5p，那么默认的日志格式将包含一个 "user" 的 MDC 条目（如果存在的话），如下例所示。

2019-08-30 12:30:04.031 user:someone INFO 22174 --- [  nio-8080-exec-0] demo.Controller
处理认证请求

none

结构化日志

结构化日志记录是一种技术，其中日志输出以定义良好且通常为机器可读的格式编写。Spring Boot 支持结构化日志记录，并且默认支持以下 JSON 格式：

• Elastic 通用模式 (ECS)

• Graylog 扩展日志格式 (GELF)

• Logstash

要启用结构化日志记录，请将属性 logging.structured.format.console（用于控制台输出）或 logging.structured.format.file（用于文件输出）设置为您想要使用的格式的 ID。

如果你正在使用自定义日志配置，请更新你的配置以尊重 CONSOLE_LOG_STRUCTURED_FORMAT 和 FILE_LOG_STRUCTURED_FORMAT 系统属性。以 CONSOLE_LOG_STRUCTURED_FORMAT 为例：

Logback

<!-- 将你的 encoder 替换为 StructuredLogEncoder -->
<encoder class="org.springframework.boot.logging.logback.StructuredLogEncoder">
    <format>${CONSOLE_LOG_STRUCTURED_FORMAT}</format>
    <charset>${CONSOLE_LOG_CHARSET}</charset>
</encoder>

xml

你也可以参考 Spring Boot 中包含的默认配置：

• Logback 结构化控制台 Appender

• Logback 结构化文件 Appender

Log4j2

<!-- 将你的 PatternLayout 替换为 StructuredLogLayout -->
<StructuredLogLayout format="${sys:CONSOLE_LOG_STRUCTURED_FORMAT}" charset="${sys:CONSOLE_LOG_CHARSET}"/>

xml

你也可以参考 Spring Boot 中包含的默认配置：

• Log4j2 控制台 Appender

• Log4j2 控制台和文件 Appender

Elastic 通用模式

Elastic Common Schema 是一种基于 JSON 的日志格式。

要启用 Elastic Common Schema 日志格式，请将相应的 format 属性设置为 ecs：

Properties

logging.structured.format.console=ecs
logging.structured.format.file=ecs

properties

YAML

logging:
  structured:
    format:
      console: ecs
      file: ecs

yaml

日志行的格式如下：

{"@timestamp":"2024-01-01T10:15:00.067462556Z","log.level":"INFO","process.pid":39599,"process.thread.name":"main","service.name":"simple","log.logger":"org.example.Application","message":"No active profile set, falling back to 1 default profile: \"default\"","ecs.version":"8.11"}

json

这种格式还会将 MDC 中包含的每个键值对添加到 JSON 对象中。你还可以使用 SLF4J 流畅日志 API 通过 addKeyValue 方法将键值对添加到记录的 JSON 对象中。

service 的值可以通过 logging.structured.ecs.service 属性进行自定义：

Properties

logging.structured.ecs.service.name=MyService
logging.structured.ecs.service.version=1
logging.structured.ecs.service.environment=Production
logging.structured.ecs.service.node-name=Primary

properties

YAML

logging:
  structured:
    ecs:
      service:
        name: MyService
        version: 1.0
        environment: Production
        node-name: Primary

yaml

备注

如果未指定，logging.structured.ecs.service.name 将默认为 spring.application.name。

备注

如果未指定，logging.structured.ecs.service.version 将默认为 spring.application.version。

Graylog 扩展日志格式 (GELF)

Graylog 扩展日志格式 是一种基于 JSON 的日志格式，专为 Graylog 日志分析平台设计。

要启用 Graylog 扩展日志格式（Graylog Extended Log Format），请将相应的 format 属性设置为 gelf：

Properties

logging.structured.format.console=gelf
logging.structured.format.file=gelf

properties

YAML

logging:
  structured:
    format:
      console: gelf
      file: gelf

yaml

日志行看起来像这样：

{"version":"1.1","short_message":"No active profile set, falling back to 1 default profile: \"default\"","timestamp":1725958035.857,"level":6,"_level_name":"INFO","_process_pid":47649,"_process_thread_name":"main","_log_logger":"org.example.Application"}

json

这种格式还会将 MDC 中包含的每个键值对添加到 JSON 对象中。你也可以使用 SLF4J 流畅日志 API 通过 addKeyValue 方法将键值对添加到记录的 JSON 对象中。

可以使用 logging.structured.gelf 属性自定义多个字段：

Properties

logging.structured.gelf.host=MyService
logging.structured.gelf.service.version=1

properties

YAML

logging:
  structured:
    gelf:
      host: MyService
      service:
        version: 1.0

yaml

备注

如果未指定，logging.structured.gelf.host 将默认为 spring.application.name。

备注

如果未指定，logging.structured.gelf.service.version 将默认为 spring.application.version。

Logstash JSON 格式

Logstash JSON 格式 是一种基于 JSON 的日志记录格式。

要启用 Logstash JSON 日志格式，请将相应的 format 属性设置为 logstash：

Properties

logging.structured.format.console=logstash
logging.structured.format.file=logstash

properties

YAML

logging:
  structured:
    format:
      console: logstash
      file: logstash

yaml

日志行看起来是这样的：

{"@timestamp":"2024-01-01T10:15:00.111037681+02:00","@version":"1","message":"No active profile set, falling back to 1 default profile: \"default\"","logger_name":"org.example.Application","thread_name":"main","level":"INFO","level_value":20000}

json

这种格式还会将 MDC 中包含的每个键值对添加到 JSON 对象中。你也可以使用 SLF4J 流畅日志记录 API 通过 addKeyValue 方法将键值对添加到记录的 JSON 对象中。

如果你添加了 markers，它们将会在 JSON 中的 tags 字符串数组中显示出来。

自定义结构化日志 JSON

Spring Boot 会尝试为结构化日志输出中的 JSON 名称和值选择合理的默认值。然而，有时你可能需要根据自身需求对 JSON 进行一些小的调整。例如，你可能希望更改某些名称以匹配日志采集系统的预期。你也可能希望过滤掉某些成员，因为你觉得它们没有用处。

以下属性允许您更改结构化日志 JSON 的写入方式：

属性	描述
logging.structured.json.include 和 logging.structured.json.exclude	从 JSON 中过滤特定路径
logging.structured.json.rename	重命名 JSON 中的特定成员
logging.structured.json.add	向 JSON 中添加额外的成员

例如，以下示例将排除 log.level，将 process.id 重命名为 procid，并添加一个固定的 corpname 字段：

Properties

logging.structured.json.exclude=log.level
logging.structured.json.rename.process.id=procid
logging.structured.json.add.corpname=mycorp

properties

YAML

logging:
  structured:
    json:
      exclude: log.level
      rename:
        process.id: procid
      add:
        corpname: mycorp

yaml

提示

如需进行更高级的自定义，您可以编写自己的类，该类实现 StructuredLoggingJsonMembersCustomizer 接口，并使用 logging.structured.json.customizer 属性进行声明。您也可以通过将它们列在 META-INF/spring.factories 文件中来声明实现。

支持其他结构化日志格式

Spring Boot 中的结构化日志支持是可扩展的，允许你定义自己的自定义格式。要实现这一点，需要实现 StructuredLogFormatter 接口。在使用 Logback 时，泛型类型参数必须是 ILoggingEvent，而在使用 Log4j2 时，泛型类型参数必须是 LogEvent（这意味着你的实现是与特定的日志系统绑定的）。你的实现会在日志事件发生时被调用，并返回要记录的 String，如下例所示：

Java

import ch.qos.logback.classic.spi.ILoggingEvent;

import org.springframework.boot.logging.structured.StructuredLogFormatter;

class MyCustomFormat implements StructuredLogFormatter<ILoggingEvent> {

    @Override
    public String format(ILoggingEvent event) {
        return "time=" + event.getInstant() + " level=" + event.getLevel() + " message=" + event.getMessage() + "\n";
    }

}

java

Kotlin

import ch.qos.logback.classic.spi.ILoggingEvent
import org.springframework.boot.logging.structured.StructuredLogFormatter

class MyCustomFormat : StructuredLogFormatter<ILoggingEvent> {

    override fun format(event: ILoggingEvent): String {
        return "time=${event.instant} level=${event.level} message=${event.message}\n"
    }

}

kotlin

如示例所示，你可以返回任何格式，不一定是 JSON。

要启用您的自定义格式，请将属性 logging.structured.format.console 或 logging.structured.format.file 设置为您的实现类的完全限定类名。

你的实现可以使用一些构造函数参数，这些参数会自动注入。更多详细信息，请参阅 StructuredLogFormatter 的 JavaDoc。

Logback 扩展

Spring Boot 包含了许多对 Logback 的扩展，这些扩展可以帮助进行高级配置。你可以在 logback-spring.xml 配置文件中使用这些扩展。

备注

由于标准的 logback.xml 配置文件加载过早，因此无法在其中使用扩展。你需要使用 logback-spring.xml 或定义 logging.config 属性。

注意

扩展无法与 Logback 的配置扫描功能一起使用。如果你尝试这样做，对配置文件进行更改时会导致类似的错误日志记录：

ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]

none

特定配置文件的配置

<springProfile> 标签允许您根据当前激活的 Spring 配置文件选择性地包含或排除配置部分。配置文件部分可以在 <configuration> 元素内的任何位置使用。使用 name 属性来指定哪个配置文件接受该配置。<springProfile> 标签可以包含一个配置文件名称（例如 staging）或一个配置文件表达式。配置文件表达式允许表达更复杂的配置文件逻辑，例如 production & (eu-central | eu-west)。有关更多详细信息，请查阅 Spring Framework 参考指南。以下列表展示了三个示例配置文件：

<springProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</springProfile>

<springProfile name="dev | staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</springProfile>

<springProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</springProfile>

xml

环境属性

<springProperty> 标签允许你从 Spring Environment 中暴露属性，以便在 Logback 中使用。如果你想在 Logback 配置中访问 application.properties 文件中的值，这样做会很有用。该标签的工作方式与 Logback 的标准 <property> 标签类似。然而，你不需要指定直接的 value，而是指定属性的 source（来自 Environment）。如果你需要将属性存储在 local 范围之外的地方，可以使用 scope 属性。如果你需要一个备用值（以防属性未在 Environment 中设置），可以使用 defaultValue 属性。以下示例展示了如何暴露属性以供 Logback 使用：

<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
        defaultValue="localhost"/>
<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
    <remoteHost>${fluentHost}</remoteHost>
    ...
</appender>

xml

备注

source 必须以短横线命名法（kebab case）指定（例如 my.property-name）。但是，可以使用宽松的规则将属性添加到 Environment 中。

Log4j2 扩展

Spring Boot 包含了许多 Log4j2 的扩展，这些扩展可以帮助进行高级配置。你可以在任何 log4j2-spring.xml 配置文件中使用这些扩展。

备注

由于标准的 log4j2.xml 配置文件加载过早，因此无法在其中使用扩展。你需要使用 log4j2-spring.xml 或定义 logging.config 属性。

备注

这些扩展取代了 Log4J 提供的 Spring Boot 支持。你应该确保在你的构建中不包含 org.apache.logging.log4j:log4j-spring-boot 模块。

特定配置文件的配置

<SpringProfile> 标签允许你根据激活的 Spring 配置文件有条件地包含或排除配置部分。配置文件部分可以在 <Configuration> 元素内的任何地方使用。使用 name 属性来指定哪个配置文件接受该配置。<SpringProfile> 标签可以包含一个配置文件名称（例如 staging）或一个配置文件表达式。配置文件表达式允许表达更复杂的配置文件逻辑，例如 production & (eu-central | eu-west)。有关更多详细信息，请查阅 Spring Framework 参考指南。以下列表展示了三个示例配置文件：

<SpringProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</SpringProfile>

<SpringProfile name="dev | staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</SpringProfile>

<SpringProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</SpringProfile>

xml

环境属性查找

如果你想在 Log4j2 配置中引用 Spring Environment 的属性，你可以使用 spring: 前缀的 lookups。如果你想在 Log4j2 配置中访问 application.properties 文件中的值，这会非常有用。

以下示例展示了如何设置名为 applicationName 和 applicationGroup 的 Log4j2 属性，这些属性从 Spring 的 Environment 中读取 spring.application.name 和 spring.application.group：

<Properties>
    <Property name="applicationName">${spring:spring.application.name}</Property>
    <Property name="applicationGroup">${spring:spring.application.group}</Property>
</Properties>

xml

备注

查找键应使用 kebab case 格式（例如 my.property-name）。

Log4j2 系统属性

Log4j2 支持许多系统属性，这些属性可以用于配置各种项目。例如，log4j2.skipJansi 系统属性可以用于配置 ConsoleAppender 是否在 Windows 上尝试使用 Jansi 输出流。

在 Log4j2 初始化之后加载的所有系统属性都可以从 Spring Environment 中获取。例如，你可以在 application.properties 文件中添加 log4j2.skipJansi=false，以便在 Windows 上让 ConsoleAppender 使用 Jansi。

备注

只有在系统属性和操作系统环境变量中不包含要加载的值时，才会考虑使用 Spring 的 Environment。

注意

在 Log4j2 早期初始化期间加载的系统属性无法引用 Spring Environment。例如，Log4j2 用于选择默认 Log4j2 实现的属性在 Spring Environment 可用之前就已经被使用了。