[參考](https://logback.qos.ch/manual/configuration.html#autoScan) [toc] ## 配置文件語法 logback配置文件的基本結構  ### 配置logger元素 使用`<logger>`元素配置記錄器。 `<logger>`元素只接受一個必需的`name`屬性，一個可選的`level`屬性和一個可選的`additivity`屬性，`additivity`允許值為true或false。 level屬性的值允許一個不區分大小寫的字符串值TRACE，DEBUG，INFO，WARN，ERROR，ALL或OFF。 特殊于大小寫不敏感的值INHERITED或其同義詞NULL將強制記錄器的級別從層次結構中的較高級別繼承。 如果您設置記錄器的級別并稍后決定它應該繼承其級別，這會派上用場。 `<logger>`元素可以包含零個或多個`<appender-ref>`元素; 這樣引用的每個`appender`都被添加到指定的`logger`中。 請注意，與log4j不同，logback-classic在配置給定記錄器時不會關閉也不會刪除任何先前引用的appender ### 配置root元素 `<root>`元素配置根記錄器。 它支持單個屬性，即level屬性。 它不允許任何其他屬性，因為additivity標志不適用于根記錄器。 此外，由于根記錄器已被命名為“ROOT”，因此它也不允許使用name屬性。 level屬性的值可以是不區分大小寫的字符串TRACE，DEBUG，INFO，WARN，ERROR，ALL或OFF之一。 請注意，根記錄器的級別不能設置為INHERITED或NULL。 與`<logger>`元素類似，`<root>`元素可以包含零個或多個`<appender-ref>`元素; 這樣引用的每個appender都被添加到根記錄器中。 請注意，與log4j不同，logback-classic在配置根記錄器時不會關閉也不會刪除任何先前引用的appender。 ### 例子 假設我們不再有興趣查看屬于“chapters.configuration”包的任何組件的任何DEBUG消息。 以下配置文件顯示了如何實現該目的。 ``` <configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <!-- encoders are assigned the type ch.qos.logback.classic.encoder.PatternLayoutEncoder by default --> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender> <logger name="chapters.configuration" level="INFO"/> <!-- Strictly speaking, the level attribute is not necessary since --> <!-- the level of the root level is set to DEBUG by default. --> <root level="DEBUG"> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 當上述配置文件作為MyApp3應用程序的參數給出時，它將產生以下輸出： ``` 17:34:07.578 [main] INFO chapters.configuration.MyApp3 - Entering application. 17:34:07.578 [main] INFO chapters.configuration.MyApp3 - Exiting application. ``` >請注意，“chapters.configuration.Foo”記錄器生成的級別DEBUG消息已被禁止。 另見Foo類。 您可以根據需要配置多個記錄器的級別。 在下一個配置文件中，我們將chapters.configuration記錄器的級別設置為INFO，但同時將chapters.configuration.Foo記錄器的級別設置為DEBUG。 ``` <configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern> %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n </pattern> </encoder> </appender> <logger name="chapters.configuration" level="INFO" /> <logger name="chapters.configuration.Foo" level="DEBUG" /> <root level="DEBUG"> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 使用此配置文件運行MyApp3將導致控制臺上的以下輸出： ``` 17:39:27.593 [main] INFO chapters.configuration.MyApp3 - Entering application. 17:39:27.593 [main] DEBUG chapters.configuration.Foo - Did it again! 17:39:27.593 [main] INFO chapters.configuration.MyApp3 - Exiting application. ``` 下表列出了記錄器及其級別。 | logger name | 指定級別 | 生效級別 | |---|---|---| | root | DEBUG | DEBUG | | chapters.configuration| INFO| INFO| | chapters.configuration.MyApp3| null| INFO| | chapters.configuration.Foo| DEBUG | DEBUG | 因此，MyApp3類中的INFO級別的兩個日志記錄語句以及Foo.doIt（）中的DEBUG消息都被啟用。 請注意，根記錄器的級別始終設置為非空值，默認情況下為DEBUG。 讓我們注意，基本選擇規則取決于被調用的記錄器的有效級別，而不是附加的記錄器的級別。 Logback將首先確定是否啟用了日志記錄語句，如果啟用，它將調用記錄器層次結構中找到的appender，而不管它們的級別如何。 配置文件sample4.xml就是一個例子： ``` <configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern> %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n </pattern> </encoder> </appender> <logger name="chapters.configuration" level="INFO" /> <!-- 關閉記錄器 (children can override) --> <root level="OFF"> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 下表列出了記錄器及其級別。 | logger name | 指定級別 | 生效級別 | |---|---|---| | root | OFF| OFF| | chapters.configuration| INFO| INFO| | chapters.configuration.MyApp3| null| INFO| | chapters.configuration.Foo| null| INFO| 名為`STDOUT`的ConsoleAppender是sample4.xml中唯一配置的appender，它附加到根級記錄器，其級別設置為`OFF`。 但是，使用配置腳本sample4.xml運行MyApp3將產生： ``` 17:52:23.609 [main] INFO chapters.configuration.MyApp3 - Entering application. 17:52:23.609 [main] INFO chapters.configuration.MyApp3 - Exiting application. ``` 因此，根記錄器的級別沒有明顯的效果，因為`chapters.configuration.MyApp3`和`chapters.configuration.Foo`類中的記錄器都為`INFO`級別啟用。 作為旁注，`chapters.configuration`記錄器憑借其在配置文件中的聲明而存在 - 即使Java源代碼沒有直接引用它。 ### 配置Appenders appender使用`<appender>`元素配置，該元素采用兩個必需屬性name和class。 name屬性指定appender的名稱，而class屬性指定要實例化的appender類的完全限定名稱。 `<appender>`元素可以包含零個或一個`<layout>`元素，零個或多個`<encoder>`元素以及零個或多個`<filter>`元素。 除了這三個公共元素之外，`<appender>`元素可以包含與appender類的JavaBean屬性相對應的任意數量的元素。 無縫支持給定logback組件的任何屬性是Joran的主要優勢之一，如后面的章節所述。 下圖說明了常見的結構。 請注意，對屬性的支持不可見。  `<layout>`元素采用必需的class屬性，指定要實例化的布局類的完全限定名稱。 與`<appender>`元素一樣，`<layout>`可以包含與layout實例的屬性對應的其他元素。 如果布局類是常見的`PatternLayout`，則可以省略class屬性，如默認類映射規則所指定。 `<encoder>`元素采用必需的class屬性，指定要實例化的編碼器類的完全限定名稱。如果編碼器類是`PatternLayoutEncoder`，則可以省略class屬性，如默認類映射規則所指定的那樣。 記錄到多個appender就像定義各種appender并在記錄器中引用它們一樣簡單，如下一個配置文件所示： ``` <configuration> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>myApp.log</file> <encoder> <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern> </encoder> </appender> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%msg%n</pattern> </encoder> </appender> <root level="debug"> <appender-ref ref="FILE" /> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 此配置腳本定義了兩個名為FILE和STDOUT的appender。 FILE appender將記錄到名為myApp.log的文件中。 此appender的編碼器是PatternLayoutEncoder，它輸出日志請求所在的日期，級別，線程名稱，記錄器名稱，文件名和行號，消息和行分隔符。 第二個稱為STDOUT的appender輸出到控制臺。 此appender的編碼器僅輸出消息字符串，后跟行分隔符。 appender通過在appender-ref元素中按名稱引用它們而附加到根記錄器。 請注意，每個appender都有自己的編碼器。 編碼器通常不被設計為由多個appender共享。 布局也是如此。 因此，logback配置文件不提供用于共享編碼器或布局的任何語法手段。 #### appender 累積 默認情況下，appender是累積的：記錄器將記錄到自身附加的appender（如果有的話）以及附加到其祖先的所有appender。 因此，將相同的appender附加到多個記錄器將導致日志記錄輸出重復。 ``` View as .groovy <configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender> <logger name="chapters.configuration"> <appender-ref ref="STDOUT" /> </logger> <root level="debug"> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 使用此配置運行MyApp3將產生以下輸出： ``` 14:25:36.343 [main] INFO chapters.configuration.MyApp3 - Entering application. 14:25:36.343 [main] INFO chapters.configuration.MyApp3 - Entering application. 14:25:36.359 [main] DEBUG chapters.configuration.Foo - Did it again! 14:25:36.359 [main] DEBUG chapters.configuration.Foo - Did it again! 14:25:36.359 [main] INFO chapters.configuration.MyApp3 - Exiting application. 14:25:36.359 [main] INFO chapters.configuration.MyApp3 - Exiting application. ``` 注意重復的輸出。 名為STDOUT的appender附加到兩個記錄器，root和chapters.configuration。 由于根記錄器是所有記錄器和章節的祖先。配置是chapters.configuration.MyApp3和chapters.configuration.Foo的父親，因此使用這兩個記錄器進行的每個記錄請求將輸出兩次，因為STDOUT被附加到 chapters.configuration和一次因為它附加到root。 Appender可加性不是新用戶的陷阱。 這是一個非常方便的回歸功能。 例如，您可以配置日志記錄，以便日志消息顯示在控制臺上（對于系統中的所有記錄器），而僅來自某些特定記錄器集的消息則流入特定的追加器。 ``` <configuration> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>myApp.log</file> <encoder> <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern> </encoder> </appender> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%msg%n</pattern> </encoder> </appender> <logger name="chapters.configuration"> <appender-ref ref="FILE" /> </logger> <root level="debug"> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 在此示例中，控制臺appender將記錄所有消息（對于系統中的所有記錄器），而只有來自chapters.configuration記錄器及其子記錄的記錄請求將進入myApp.log文件。 #### 重寫默認累積行為 如果默認累積行為證明不適合您的需要，您可以通過將additivity標志設置為false來覆蓋它。 因此，記錄器樹中的分支可以將輸出定向到與樹的其余部分不同的一組appender。 ``` <configuration> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>foo.log</file> <encoder> <pattern>%date %level [%thread] %logger{10} [%file : %line] %msg%n</pattern> </encoder> </appender> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%msg%n</pattern> </encoder> </appender> <logger name="chapters.configuration.Foo" additivity="false"> <appender-ref ref="FILE" /> </logger> <root level="debug"> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 這個例子，名為FILE的appender附加到chapters.configuration.Foo記錄器。 此外，chapters.configuration.Foo記錄器將其additivity標志設置為false，以使其日志記錄輸出將發送到名為FILE的appender，但不會發送到層次結構中較高的任何appender。 其他記錄器仍然無視chapters.configuration.Foo記錄器的可加性設置。 使用additivityFlag.xml配置文件運行MyApp3應用程序將從chapters.configuration.MyApp3記錄器輸出控制臺上的結果。 但是，chapters.configuration.Foo記錄器的輸出將出現在foo.log文件中，并且僅出現在該文件中。 #### FileAppender append元素,如果為true，則會在現有文件的末尾附加事件。 否則，如果append為false，則截斷任何現有文件。 默認情況下，append選項設置為true。 prudent元素,謹慎模式，即使存在可能在不同主機上運行的不同JVM中運行的其他FileAppender實例，FileAppender也會安全地寫入指定文件。 prudent模式的默認值為false。 盡管存在一些限制，但謹慎模式可與RollingFileAppender結合使用。 謹慎模式意味著append屬性自動設置為true。 謹慎更依賴于獨占文件鎖。 實驗表明，文件鎖定大約是編寫日志記錄事件的三倍（x3）。 在寫入位于本地硬盤上的文件的“普通”PC上，當謹慎模式關閉時，編寫單個日志記錄事件大約需要10微秒。 當謹慎模式打開時，輸出單個記錄事件大約需要30微秒。 這意味著當謹慎模式關閉時記錄吞吐量為每秒100'000個事件，而謹慎模式下每秒記錄大約33'000個事件。 ### 設置上下文名稱 如前一章所述，每個記錄器都附加到記錄器上下文。 默認情況下，記錄器上下文稱為“默認”。 但是，您可以在<contextName>配置指令的幫助下設置不同的名稱。 請注意，一旦設置，就無法更改記錄器上下文名稱。 設置上下文名稱是一種簡單而直接的方法，以便區分記錄到同一目標的多個應用程序。 ``` <configuration> <contextName>myAppName</contextName> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d %contextName [%t] %level %logger{36} - %msg%n</pattern> </encoder> </appender> <root level="debug"> <appender-ref ref="STDOUT" /> </root> </configuration> ``` 最后一個示例說明了記錄器上下文的命名。 在布局模式中添加contextName轉換字將輸出所述名稱。 ### 定義變量 變量可以在配置文件本身中一次定義一個，也可以從外部屬性文件或外部資源批量加載。 由于歷史原因，用于定義變量的XML元素是<property>，盡管在logback 1.0.7及更高版本中元素<variable>可以互換使用。 下一個示例顯示了在配置文件開頭聲明的變量。 然后在文件的下方使用它來指定輸出文件的位置。 ``` <configuration> <property name="USER_HOME" value="/home/sebastien" /> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>${USER_HOME}/myApp.log</file> <encoder> <pattern>%msg%n</pattern> </encoder> </appender> <root level="debug"> <appender-ref ref="FILE" /> </root> </configuration> ``` 下一個示例顯示使用System屬性來實現相同的結果。 該屬性未在配置文件中聲明，因此logback將在“系統”屬性中查找該屬性。 可以在命令行上設置Java系統屬性，如下所示： ``` java -DUSER_HOME="/home/sebastien" MyApp2 ``` ### 配置encoder 編碼器負責將事件轉換為字節數組，并將該字節數組寫入`OutputStream`。 編碼器在logback版本0.9.19中引入。 在以前的版本中，大多數appender依靠布局將事件轉換為字符串并使用`java.io.Writer`將其寫出來。 在以前版本的logback中，用戶可以在`FileAppender`中嵌套`PatternLayout`。 由于logback 0.9.19，`FileAppender`和子類需要一個編碼器而不再采用布局。 為什么突破變化？ 如下一章中詳細討論的，布局只能將事件轉換為字符串。 此外，由于布局無法控制何時寫出事件，因此布局無法將事件聚合到批處理中。 將此與編碼器進行對比，編碼器不僅可以完全控制寫出的字節格式，還可以控制何時（以及是否）寫出這些字節。 目前，`PatternLayoutEncoder`是唯一真正有用的編碼器。 它只包裝了一個完成大部分工作的`PatternLayout`。 因此，除了不必要的復雜性之外，編碼器看起來并沒有帶來太大的影響。 但是，我們希望隨著新的強大編碼器的出現，這種印象會發生變化。 #### LayoutWrappingEncoder 在版本0.9.19之前，許多appender依賴于Layout實例來控制日志輸出的格式。 由于存在大量基于布局界面的代碼，我們需要一種編碼器與布局互操作的方法。 LayoutWrappingEncoder填補了編碼器和布局之間的空白。 它實現了編碼器接口并包裝了一個布局，它將委托轉換為字符串的工作。 #### PatternLayoutEncoder 鑒于PatternLayout是最常用的布局，logback適用于PatternLayoutEncoder的這種常見用例，LayoutWrappingEncoder的擴展僅限于包裝PatternLayout的實例。 從logback版本0.9.19開始，只要FileAppender或其子類之一配置了PatternLayout，就必須使用PatternLayoutEncoder。 這在logback錯誤代碼的相關條目中進行了解釋。 #### pattern Logback經典船舶具有靈活的布局，稱為PatternLayout。與所有布局一樣，PatternLayout接受日志記錄事件并返回String。但是，可以通過調整PatternLayout的轉換模式來自定義此String。 PatternLayout的轉換模式與C編程語言中printf（）函數的轉換模式密切相關。轉換模式由文字文本和稱為轉換說明符的格式控制表達式組成。您可以在轉換模式中插入任何文字文本。每個轉換說明符都以百分號'％'開頭，后跟可選的格式修飾符，轉換字和大括號之間的可選參數。轉換字控制要轉換的數據字段，例如，記錄器名稱，級別，日期或線程名稱。格式修飾符控制字段寬度，填充和左對齊或右對齊。 正如已經多次提到的那樣，FileAppender和子類需要一個編碼器。因此，當與FileAppender或其子類一起使用時，PatternLayout必須包含在編碼器中。鑒于FileAppender / PatternLayout組合如此常見，logback附帶了一個名為PatternLayoutEncoder的編碼器，該編碼器僅用于包裝PatternLayout實例，以便可以將其視為編碼器。