版本：4.0.2

本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

Logging

QWen Max 中英对照 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 的默认日志输出类似于以下示例：

2026-01-22T14:07:51.080Z  INFO 88932 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Starting MyApplication using Java 25.0.2 with PID 88932 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2026-01-22T14:07:51.093Z  INFO 88932 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : No active profile set, falling back to 1 default profile: "default"
2026-01-22T14:07:53.217Z  INFO 88932 --- [myapp] [           main] o.s.boot.tomcat.TomcatWebServer          : Tomcat initialized with port 8080 (http)
2026-01-22T14:07:53.268Z  INFO 88932 --- [myapp] [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2026-01-22T14:07:53.269Z  INFO 88932 --- [myapp] [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/11.0.15]
2026-01-22T14:07:53.370Z  INFO 88932 --- [myapp] [           main] b.w.c.s.WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 2074 ms
2026-01-22T14:07:54.298Z  INFO 88932 --- [myapp] [           main] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 8080 (http) with context path '/'
2026-01-22T14:07:54.322Z  INFO 88932 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Started MyApplication in 4.599 seconds (process running for 5.54)
2026-01-22T14:07:54.344Z  INFO 88932 --- [myapp] [ionShutdownHook] o.s.boot.tomcat.GracefulShutdown         : Commencing graceful shutdown. Waiting for active requests to complete
2026-01-22T14:07:54.359Z  INFO 88932 --- [myapp] [tomcat-shutdown] o.s.boot.tomcat.GracefulShutdown         : Graceful shutdown complete

以下项目将被输出：

日期和时间：毫秒级精度，且易于排序。
日志级别：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。

提示

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

控制台输出

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

$ java -jar myapp.jar --debug

备注

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

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

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

如果你想禁用基于控制台的日志记录，可以将 logging.console.enabled 属性设置为 false。

彩色编码输出

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

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

%clr(%5p)

下表描述了日志级别到颜色的映射：

Level	Color
`FATAL`	Red
`ERROR`	Red
`WARN`	Yellow
`INFO`	Green
`DEBUG`	Green
`TRACE`	Green

或者，你可以通过在转换时提供选项来指定应使用的颜色或样式。例如，要使文本变为黄色，请使用以下设置：

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

支持以下颜色和样式：

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`	说明
(none)	(none)	仅输出到控制台。
指定文件（例如 `my.log`）	(none)	写入到 `logging.file.name` 指定的位置。该位置可以是绝对路径，也可以是相对于当前目录的路径。
(none)	指定目录（例如 `/var/log`）	在 `logging.file.path` 指定的目录下写入 `spring.log`。该目录可以是绝对路径，也可以是相对于当前目录的路径。
指定文件	指定目录	写入到 `logging.file.name` 指定的位置，并忽略 `logging.file.path`。该位置可以是绝对路径，也可以是相对于当前目录的路径。

当日志文件达到 10 MB 时会进行轮转，并且与控制台输出一样，默认记录 ERROR 级别、WARN 级别和 INFO 级别的消息。请注意，Log4J2 需要在此类配置中设置 logging.file.path。

提示

日志记录属性独立于实际的日志记录基础设施。因此，特定的配置键（例如 Logback 的 logback.configurationFile）不由 Spring Boot 管理。

文件轮转

如果你使用的是 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
YAML

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

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

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

备注

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

Log Groups

通常，能够将相关的 logger 分组在一起非常有用，这样就可以同时对它们进行配置。例如，你可能经常需要更改所有与 Tomcat 相关的 logger 的日志级别，但却很难记住顶层包名。

为此，Spring Boot 允许你在 Spring Environment 中定义日志组。例如，你可以通过在 application.properties 中添加以下内容来定义一个 “tomcat” 组：

Properties
YAML

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

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

一旦定义好，你可以用一行代码更改该组中所有 logger 的日志级别：

Properties
YAML

logging.level.tomcat=trace

logging:
  level:
    tomcat: "trace"

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

使用日志关闭钩子

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

Properties
YAML

logging.register-shutdown-hook=false

logging:
  register-shutdown-hook: false

自定义日志配置

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

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

备注

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

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

日志系统	自定义配置文件
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 转移到 System properties。这使得日志系统配置能够使用这些属性。例如，在 application.properties 中设置 logging.file.name，或以环境变量 LOGGING_FILE_NAME 的形式设置，都会导致 LOG_FILE 系统属性被设置。下表描述了被转移的属性：

Spring Environment	System Property	Comments
`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 Environment	System Property	Comments
`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`	要保留的归档日志文件的最大数量。

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

提示

如果你想在日志记录属性中使用占位符，应使用 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
Handling authenticated request

结构化日志

结构化日志记录是一种以明确定义的、通常为机器可读格式输出日志的技术。Spring Boot 支持结构化日志记录，并且开箱即用地支持以下 JSON 格式：

Elastic Common Schema (ECS)
Graylog Extended Log Format (GELF)
Logstash

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

如果你正在使用 Custom Log Configuration，请更新你的配置以遵循 CONSOLE_LOG_STRUCTURED_FORMAT 和 FILE_LOG_STRUCTURED_FORMAT 系统属性。以 CONSOLE_LOG_STRUCTURED_FORMAT 为例：

Logback
Log4j2

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

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

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

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

Elastic Common Schema

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

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

Properties
YAML

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

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

一条日志行看起来像这样：

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

此格式还会将 MDC 中包含的每个键值对添加到 JSON 对象中。你也可以使用 SLF4J fluent logging API，通过 addKeyValue 方法向记录的 JSON 对象中添加键值对。

可以使用 logging.structured.ecs.service 属性来自定义 service 的值：

Properties
YAML

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

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

备注

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

备注

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

Graylog Extended Log Format (GELF)

Graylog Extended Log Format 是一种基于 JSON 的日志格式，用于 Graylog 日志分析平台。

要启用 Graylog Extended Log Format，请将相应的 format 属性设置为 gelf：

Properties
YAML

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

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

一条日志行看起来像这样：

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

此格式还会将 MDC 中包含的每个键值对添加到 JSON 对象中。你也可以使用 SLF4J fluent logging API，通过 addKeyValue 方法向记录的 JSON 对象中添加键值对。

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

Properties
YAML

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

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

备注

如果未指定，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
YAML

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

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

一条日志行看起来像这样：

{"@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}

此格式还会将 MDC 中包含的每个键值对添加到 JSON 对象中。你也可以使用 SLF4J fluent logging API，通过 addKeyValue 方法向记录的 JSON 对象中添加键值对。

如果你添加了 markers，这些标记将会以 tags 字符串数组的形式出现在 JSON 中。

自定义结构化日志 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
YAML

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

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

提示

对于更高级的自定义，你可以使用 StructuredLoggingJsonMembersCustomizer 接口。你可以通过 logging.structured.json.customizer 属性引用一个或多个实现。你也可以在 META-INF/spring.factories 文件中列出这些实现来声明它们。

自定义结构化日志的堆栈跟踪

每当记录带有异常的消息时，完整的堆栈跟踪都会包含在 JSON 输出中。这些信息可能会给你的日志摄入系统带来较高的处理开销，因此你可能需要调整堆栈跟踪的打印方式。

为此，你可以使用以下一个或多个属性：

属性	描述
`logging.structured.json.stacktrace.root`	使用 `last` 将根项最后打印（与 Java 相同），或使用 `first` 将根项首先打印。
`logging.structured.json.stacktrace.max-length`	应打印的最大长度
`logging.structured.json.stacktrace.max-throwable-depth`	每个堆栈跟踪应打印的最大帧数（包括公共帧和被抑制的帧）
`logging.structured.json.stacktrace.include-common-frames`	是否应包含公共帧或将其移除
`logging.structured.json.stacktrace.include-hashes`	是否应包含堆栈跟踪的哈希值

例如，以下内容将使用 root first 堆栈跟踪，限制其长度，并包含哈希值。

Properties
YAML

logging.structured.json.stacktrace.root=first
logging.structured.json.stacktrace.max-length=1024
logging.structured.json.stacktrace.include-common-frames=true
logging.structured.json.stacktrace.include-hashes=true

logging:
  structured:
    json:
      stacktrace:
        root: first
        max-length: 1024
        include-common-frames: true
        include-hashes: true

提示

如果你需要完全控制堆栈跟踪的打印，可以将 logging.structured.json.stacktrace.printer 设置为一个 StackTracePrinter 实现类的名称。你也可以将其设置为 logging-system，以强制使用常规日志系统的堆栈跟踪输出。

你的 StackTracePrinter 实现类还可以包含一个接受 StandardStackTracePrinter 的构造函数参数，以便在根据属性创建的堆栈跟踪打印机基础上进行进一步自定义。

支持其他结构化日志格式

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

Java
Kotlin

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

}

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

}

如示例中所示，你可以返回任意格式，不一定要是 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]]

特定于 Profile 的配置

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

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

环境属性

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

备注

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 模块。

特定于 Profile 的配置

<SpringProfile> 标签允许你根据激活的 Spring 配置文件（profiles）选择性地包含或排除配置中的某些部分。配置文件片段可以在 <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>

环境属性查找

如果你想在 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>

备注

查找键应使用短横线分隔命名（kebab case），例如 my.property-name。

Log4j2 系统属性

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

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

备注

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

注意

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

日志格式​

控制台输出​

彩色编码输出​

文件输出​

文件轮转​

日志级别​

Log Groups​

使用日志关闭钩子​

自定义日志配置​

结构化日志​

Elastic Common Schema​

Graylog Extended Log Format (GELF)​

Logstash JSON 格式​

自定义结构化日志 JSON​

自定义结构化日志的堆栈跟踪​

支持其他结构化日志格式​

Logback 扩展​

特定于 Profile 的配置​

环境属性​

Log4j2 扩展​

特定于 Profile 的配置​

环境属性查找​

Log4j2 系统属性​

日志格式

控制台输出

彩色编码输出

文件输出

文件轮转

日志级别

Log Groups

使用日志关闭钩子

自定义日志配置

结构化日志

Elastic Common Schema

Graylog Extended Log Format (GELF)

Logstash JSON 格式

自定义结构化日志 JSON

自定义结构化日志的堆栈跟踪

支持其他结构化日志格式

Logback 扩展

特定于 Profile 的配置

环境属性

Log4j2 扩展

特定于 Profile 的配置

环境属性查找

Log4j2 系统属性