Spring Boot中文文檔——26日誌

26.日誌

Spring Boot 使用 Commons Logging 記錄所有內部日誌，但開放日誌的底層實現。爲 Java Util Logging 、Log4J2 和 Logback 提供了默認配置。在每種情況下，日誌記錄器都預先配置爲使用控制檯輸出，並且還提供可選的文件輸出。
默認情況下，如果您使用了 Starter，則使用 Logback 進行日誌記錄。還包括合適的 Logback 路由，以確保在使用 Java Util Logging、Commons Logging、Log4J 或 SLF4J 的依賴庫都能正常工作。

Java 有很多日誌框架可供使用。如果以上列表讓您感到困惑，請不要擔心。通常，您不需要更改日誌依賴，並且 Spring Boot 提供的默認配置可以保證日誌正常工作。

26.1日誌格式

Spring Boot 默認日誌輸出類似於以下示例：

2014-03-05 10:57:51.112  INFO 45469 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet Engine: Apache Tomcat/7.0.52
2014-03-05 10:57:51.253  INFO 45469 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2014-03-05 10:57:51.253  INFO 45469 --- [ost-startStop-1] o.s.web.context.ContextLoader            : Root WebApplicationContext: initialization completed in 1358 ms
2014-03-05 10:57:51.698  INFO 45469 --- [ost-startStop-1] o.s.b.c.e.ServletRegistrationBean        : Mapping servlet: 'dispatcherServlet' to [/]
2014-03-05 10:57:51.702  INFO 45469 --- [ost-startStop-1] o.s.b.c.embedded.FilterRegistrationBean  : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]

輸出以下項：

• 日期和時間：毫秒精度，易於排序。
• 日誌級別：ERROR、WARN、INFO、DEBUG 或 TRACE。
• 進程 ID。
• 一個 --- 分隔符，用於區分實際日誌內容的開始。
• 線程名稱：在方括號中（可能會截斷控制檯輸出）。
• 日誌記錄器名稱：這通常是源類名稱（通常爲縮寫）。
• 日誌內容。

Logback 沒有 FATAL 級別。該級別映射到 ERROR。

26.2.控制檯輸出

默認日誌配置會在寫入時將消息回顯到控制檯。默認情況下，會記錄 ERROR、WARN 和 INFO 級別的日誌。您還可以通過使用--debug標誌啓動應用程序來啓用調試模式。

$ java -jar myapp.jar --debug

您還可以在 application.properties 中指定 debug=true。

啓用調試模式後，核心日誌記錄器（內嵌容器、Hibernate 和 Spring Boot）將被配置爲輸出更多日誌信息。啓用調試模式不會將應用程序配置爲使用 DEBUG 級別記錄所有日誌內容。

或者，您可以通過使用 --trace 標誌（或在 application.properties 中的設置 trace=true）啓動應用程序來啓用跟蹤模式。這樣做可以爲選擇的核心日誌記錄器（內嵌容器、Hibernate 模式生成和整個 Spring 組合）啓用日誌追蹤。

26.2.1.着色輸出

如果您的終端支持 ANSI，則可以使用顏色輸出來提高可讀性。您可以將 spring.output.ansi.enabled設置爲受支持的值以覆蓋自動檢測。

可使用 ％clr轉換字配置顏色編碼。最簡單形式是，轉換器根據日誌級別對輸出進行着色，如下所示：

%clr(%5p)

下表描述日誌級別與顏色的映射關係：

級別	顏色
FATAL	紅（Red)
ERROR	紅（Red）
WARN	黃（Yellow）
INFO	綠（Green）
DEBUG	綠（Green）
TRACE	綠（Green）

或者，您可以通過將其作爲轉換選項指定應使用的顏色或樣式。例如，要將文本變爲黃色，請使用以下設置：

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

支持以下顏色和樣式：

• blue
• cyan
• faint
• green
• magenta
• red
• yellow

26.3.文件輸出

默認情況下，Spring Boot 僅記錄到控制檯，不會寫入日誌文件。想除了控制檯輸出之外還要寫入日誌文件，則需要設置logging.file 或logging.path 屬性（例如，在 application.properties 中）。

下表展示瞭如何與 logging.* 屬性一起使用：

表 26.1、Logging 屬性

logging.file	logging.path	示例	描述
（無）	（無）		僅在控制檯輸出
指定文件	(無)	my.log	寫入指定的日誌文件。名稱可以是絕對位置或相對於當前目錄。
（無）	指定目錄	/var/log	將 spring.log 寫入指定的目錄。名稱可以是絕對位置或相對於當前目錄。

日誌文件在達到 10MB 時會輪轉，並且與控制檯輸出一樣，默認情況下會記錄 ERROR、WARN 和 INFO 級別的內容。可以使用 logging.file.max-size屬性更改大小限制。除非已設置logging.file.max-history屬性，否則以前輪轉的文件將無限期歸檔。

日誌記錄系統在應用程序生命週期的早期開始初始化。因此，通過 @PropertySource 註解加載的屬性文件中是找不到日誌屬性的。

日誌屬性獨立於實際的日誌底層。因此，spring Boot 不管理特定的配置 key（例如 Logback 的 logback.configurationFile）。

26.4.日誌等級

所有受支持的日誌記錄系統都可以使用logging.level.<logger-name>=<level> 來設置 Spring Environment 中的記錄器等級（例如，在 application.properties 中）。其中 level 是 TRACE、DEBUG、INFO、WARN、ERROR、FATAL 和 OFF 其中之一。可以使用 logging.level.root 配置 root 記錄器。

以下示例展示了 application.properties 中默認的日誌記錄設置：

logging.level.root=WARN
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR

26.5.日誌組

將相關記錄器組合在一起以便可以同時配置，這通常很有用。例如，您可以更改所有 Tomcat 相關記錄器的日誌記錄級別，但您無法輕鬆記住頂層的包名。
爲了解決這個問題，Spring Boot 允許您在 Spring Environment 中定義日誌記錄組。例如，以下通過將 tomcat 組添加到 application.properties 來定義 tomcat 組：

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

定義後，您可以使用一行配置來更改組中所有記錄器的級別：

logging.level.tomcat=TRACE

Spring Boot 包含以下預定義的日誌記錄組，可以直接使用：

名稱	日誌記錄器
web	org.springframework.core.codec、org.springframework.http、org.springframework.web
sql	org.springframework.jdbc.core、org.hibernate.SQL

26.6.自定義日誌配置

可以通過在 classpath 中引入適合的庫來激活各種日誌記錄系統，並且可以通過在 classpath 的根目錄中或在以下 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 傳輸到 System 屬性，如下表所述：

Spring Environment	系統屬性	說明
logging.exception-conversion-word	LOG_EXCEPTION_CONVERSION_WORD	記錄異常時使用的轉換字。
logging.file	LOG_FILE	如果已定義，則在默認日誌配置中使用它。
logging.file.max-size	LOG_FILE_MAX_SIZE	最大日誌文件大小（如果啓用了 LOG_FILE）。（僅支持默認的 Logback 設置。）
logging.file.max-history	LOG_FILE_MAX_HISTORY	要保留的歸檔日誌文件最大數量（如果啓用了 LOG_FILE）。（僅支持默認的 Logback 設置。）
logging.path	LOG_PATH	如果已定義，則在默認日誌配置中使用它。
logging.pattern.console	CONSOLE_LOG_PATTERN	要在控制檯上使用的日誌模式（stdout）。（僅支持默認的 Logback 設置。）
logging.pattern.dateformat	LOG_DATEFORMAT_PATTERN	日誌日期格式的 Appender 模式。（僅支持默認的 Logback 設置。）
logging.pattern.file	FILE_LOG_PATTERN	要在文件中使用的日誌模式（如果啓用了 LOG_FILE）。（僅支持默認的 Logback 設置。）
logging.pattern.level	LOG_LEVEL_PATTERN	渲染日誌級別時使用的格式（默認值爲 ％5p）。（僅支持默認的 Logback 設置。）
PID	PID	當前進程 ID（如果可能，則在未定義爲 OS 環境變量時發現）。

所有受支持的日誌記錄系統在解析其配置文件時都可以參考系統屬性。有關示例，請參閱 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 項（如果存在），如下所示: 2015-09-30 12:30:04.031 user:someone INFO 22174 --- [ nio-8080-exec-0] demo.Controller Handling authenticated request

26.7.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]]

26.7.1.特定 Profile 配置

<springProfile> 標籤允許您根據激活的 Spring profile 選擇性地包含或排除配置部分。在 <configuration>元素中的任何位置都支持配置 profile。使用 name 屬性指定哪個 proifle 接受配置。<springProfile> 標記可以包含簡單的 profile 名稱（例如 staging）或 profile 表達式。profile 表達式允許表達更復雜的 profile 邏輯，例如 production & (eu-central | eu-west)。有關詳細信息，請查閱參考指南。以下清單展示了三個示例 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>

26.7.2.環境屬性

使用 <springProperty> 標記可以讓您暴露 Spring 環境（Environment）中的屬性，以便在 Logback 中使用。如果在 Logback 配置中訪問來自 application.properties 文件的值，這樣做很有用。標籤的工作方式與 Logback 的標準 <property> 標籤類似。但是，您可以指定屬性（來自 Environment）的 source，而不是指定直接的 value。如果需要將屬性存儲在 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>

必須以 kebab 風格（短橫線小寫風格）指定 source（例如 my.property-name）。但可以使用寬鬆規則將屬性添加到 Environment 中。