Spring Boot 參考指南（日誌記錄）

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標誌啓動應用程序來啓用「debug」模式。

$ java -jar myapp.jar --debug

你還能夠在 application.properties中指定 debug=true。

啓用調試模式時，將配置核心日誌記錄器（嵌入式容器、Hibernate和Spring Boot）的選擇，以輸出更多信息，啓用調試模式不會將應用程序配置爲使用DEBUG級別記錄全部消息。

或者，你能夠啓用「trace」模式，經過使用--trace標誌啓動應用程序（或在application.properties中trace=true），這樣作可使trace日誌記錄用於選擇核心日誌記錄器（嵌入式容器、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	樣例	描述
(none)	(none)		只控制檯記錄日誌
指定文件	(none)	my.log	寫入指定的日誌文件，名稱能夠是一個確切的位置或相對於當前目錄
(none)	指定文件	/var/log	寫如spring.log到指定的目錄，名稱能夠是一個確切的位置或相對於當前目錄

日誌文件在達到10MB時就會回滾，與控制檯輸出同樣，默認狀況下會記錄ERROR-級別、WARN-級別和INFO-級別的消息，可使用logging.file.max-size屬性更改大小限制，除非logging.file.max-history屬性已被設置，不然以前回滾的文件將被無限期地歸檔。

日誌系統在應用程序生命週期的早期初始化，所以，在經過 @PropertySource註解加載的屬性文件中沒有發現日誌屬性。

日誌記錄屬性獨立於實際的日誌記錄基礎設施，所以，特定的配置鍵（例如Logback的logback.configurationFile）不是由spring Boot管理的。

26.4 日誌級別

全部受支持的日誌系統均可以在Spring Environment中經過使用logging.level.<logger-name>=<level>（例如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 自定義日誌配置

能夠經過在類路徑中包含適當的庫來激活各類日誌系統，還能夠經過在類路徑的根目錄中或在如下Spring Environment屬性（logging.config）指定的位置中提供合適的配置文件來進一步定製。

你能夠經過使用org.springframework.boot.logging.LoggingSystem來強制Spring Boot使用特定的日誌系統，值應該是LoggingSystem實現的徹底限定類名，你還能夠徹底經過使用none值來禁用Spring Boot的日誌配置。

由於日誌是在建立 ApplicationContext以前初始化的，沒法在Spring @Configuration文件中控制來自 @PropertySources的logging，更改日誌系統或徹底禁用日誌系統的惟一方法是經過系統屬性。

依賴於你的日誌系統，加載下列文件：

Logging系統	自定義
Logback	logback-spring.xml，logback-spring.groovy，logback.xml，或logback.groovy
Log4j2	log4j2-spring.xml或log4j2.xml
JDK (Java Util Logging)	logging.properties

若是可能的話，咱們建議你對logging配置使用 -spring變體（例如， logback-spring.xml而不是 logback.xml），若是使用標準配置位置，Spring不能徹底控制日誌初始化。

Java Util Logging存在已知的類加載問題，當從「可執行jar」運行時，會致使問題，若是可能的話，咱們建議你在運行「可執行jar」時避免使用它。

爲了幫助定製，一些其餘屬性從Spring Environment轉移到系統屬性，以下表所示：

Spring環境	系統屬性	註釋
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	日誌日期格式的附加模式，（只支持默認的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

若是但願在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.6 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.6.1 特殊配置文件配置

經過<springProfile>標籤，你能夠根據激活的Spring配置文件選擇包含或排除配置的部分。在<configuration>元素中的任何地方都支持配置文件部分，使用name屬性指定哪一個配置文件接受配置，可使用逗號分隔的列表指定多個配置文件，下面的清單顯示了三個示例配置文件：

<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.6.2 環境屬性

經過<springProperty>標記，能夠從Spring Environment中公開屬性，以便在Logback中使用，若是你但願在Logback配置中從application.properties文件中訪問值，那麼這樣作是頗有用的，標籤的工做方式與Logback的標準<property>標籤相似。可是，不是指定直接value，而是指定屬性的source（來自Environment）。若是你須要將屬性存儲在本地範圍以外的其餘地方，則可使用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（例如 my.property-name），可是，可使用寬鬆的規則將屬性添加到 Environment中。

---

上一篇：配置文件

下一篇：開發Web應用程序