logback官方文檔閱讀筆記（五）

前言

logback官方文檔

本文關於官方文檔第三章：Logback configuration。

本文爲官方文檔第三章的第二份筆記，第三章第一份筆記請見：logback官方文檔閱讀筆記（四）

正文

---

配置文件(xml)的基本結構

As will be demonstrated over and over, the syntax of logback configuration files is extremely flexible. As such, it is not possible to specify the allowed syntax with a DTD file or an XML schema. Nevertheless, the very basic structure of the configuration file can be described as, <configuration> element, containing zero or more <appender> elements, followed by zero or more <logger> elements, followed by at most one <root> element. The following diagram illustrates this basic structure.

基本結構爲

配置文件(xml)的注意事項：大小寫

Since logback version 0.9.17, tag names pertaining to explicit rules are case insensitive. For example, <logger>, <Logger> and <LOGGER> are valid configuration elements and will be interpreted in the same way. Note that XML well-formedness rules still apply, if you open a tag as <xyz> you must close it as </xyz>, </XyZ> will not work. As for implicit rules, tag names are case sensitive except for the first letter. Thus, <xyz> and <Xyz> are equivalent but not <xYz>. Implicit rules usually follow the camelCase convention, common in the Java world. Since it is not easy to tell when a tag is associated with an explicit action and when it is associated with an implicit action, it is not trivial to say whether an XML tag is case-sensitive or insensitive with respect to the first letter. If you are unsure which case to use for a given tag name, just follow the camelCase convention which is almost always the correct convention.

簡單來講，就是像logger,appender，filter這樣的內置的有效指令元素的標籤名不區分大小寫。對於搞不清楚什麼成分的，使用駝峯命名法。

配置文件(xml)的logger元素的配置語法

Configuring loggers, or the<logger>element

A logger is configured using the <logger> element. A <logger> element takes exactly one mandatory name attribute, an optional level attribute, and an optional additivity attribute, admitting the values true or false. The value of the level attribute admitting one of the case-insensitive string values TRACE, DEBUG, INFO, WARN, ERROR, ALL or OFF. The special case-insensitive value INHERITED, or its synonym NULL, will force the level of the logger to be inherited from higher up in the hierarchy. This comes in handy if you set the level of a logger and later decide that it should inherit its level.

配置logger的appender

The <logger> element may contain zero or more <appender-ref> elements; each appender thus referenced is added to the named logger. Note that unlike log4j, logback-classic does not close nor remove any previously referenced appenders when configuring a given logger.

<appender-ref>怎麼寫其實沒說明白。經過在文檔中以'appender-ref'爲關鍵詞搜索，就獲得的例子，能夠推測其使用方式如圖：

再過幾節有幾段文字再度談及了logger引用appender。

Configuring the root logger, or the<root>element

It supports a single attribute, namely the level attribute. It does not allow any other attributes because the additivity flag does not apply to the root logger. Moreover, since the root logger is already named as "ROOT", it does not allow a name attribute either. The value of the level attribute can be one of the case-insensitive strings TRACE, DEBUG, INFO, WARN, ERROR, ALL or OFF. Note that the level of the root logger cannot be set to INHERITED or NULL.

Appender並不能限制logger的輸出

Let us note that the basic-selection rule depends on the effective level of the logger being invoked, not the level of the logger where appenders are attached. Logback will first determine whether a logging statement is enabled or not, and if enabled, it will invoke the appenders found in the logger hierarchy, regardless of their level.

這段話最後一句頗有意思，'regardless of their level'，這裏的這個their中的它，指的最合句子結構和語境的，實際上是Appender。也就是說Appender可能也有級別問題。

appender元素必需屬性

An appender is configured with the <appender> element, which takes two mandatory attributes name and class. The name attribute specifies the name of the appender whereas the class attribute specifies the fully qualified name of the appender class to instantiate.

<appender>元素標籤必需(mandatory)的兩個屬性爲name和class。即要用appender標籤，至少也會有這樣的代碼：<appender class="..." name="...">...</appender>。

可選的加強appender的組件：layout,encoder,filter.

The <appender> element may contain zero or one <layout> elements, zero or more <encoder> elements and zero or more <filter> elements. Apart from these three common elements, <appender> elements may contain any number of elements corresponding to JavaBean properties of the appender class. Seamlessly supporting any property of a given logback component is one of the major strengths of Joran as discussed in a later chapter.

The <layout> element takes a mandatory class attribute specifying the fully qualified name of the layout class to instantiate. As with the <appender> element, <layout> may contain other elements corresponding to properties of the layout instance. Since it's such a common case, if the layout class is PatternLayout, then the class attribute can be omitted as specified by default class mapping rules.

The <encoder> element takes a mandatory class attribute specifying the fully qualified name of the encoder class to instantiate. Since it's such a common case, if the encoder class is PatternLayoutEncoder, then the class attribute can be omitted as specified by default class mapping rules.

這裏官方文檔不具體說一說二者的做用，也不提二者有專門的篇章——官方文檔第五章，第六章——來講明它們，一個字，菜。

這裏重複出現的

if the encoder class is .... , then the class attribute can be omitted as specified by 一個url rules.

點擊URL查看，並結合接下來的例子，以及對這兩個組件元素描述時，使用 mandatory 修飾 class 這個屬性，就能夠明白。這段反覆出現的話就一個意思，其實<encoder>`<layout>`的 class 屬性不寫全限定名甚至直接不賦值也行，咱們有默認值的啦。

而後在打開的url中，迎面而來的表格有一個 parent class，乍一看看不懂。但回過頭來看以後給的xml示例，發現appender元素必然有一個帶類全限定名的class屬性，好比ch.qos.logback.core.FileAppender，若是去翻閱它的javadoc，就會發現這個類是ch.qos.logback.core.UnsynchronizedAppenderBase的子類。看到這裏，我想你內心已經有了必定猜想了。

Note that each appender has its own encoder. Encoders are usually not designed to be shared by multiple appenders. The same is true for layouts. As such, logback configuration files do not provide any syntactical means for sharing encoders or layouts.

這段文字在講了一些關於logger引用appender的知識後纔出現，這排布方式我也是服了。主要內容就是Encoder和Layout在設計時都沒有把它們在多個Appender中複用的想法。

logger引用appender——appender-ref

Logging to multiple appenders is as easy as defining the various appenders and referencing them in a logger, as the next configuration file illustrates:

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

The appenders are attached to the root logger by referencing them by name within an appender-ref element.

logger在appender上的累進

By default, appenders are cumulative: a logger will log to the appenders attached to itself (if any) as well as all the appenders attached to its ancestors. Thus, attaching the same appender to multiple loggers will cause logging output to be duplicated.

logger會調用全部它能調用的appender，包括其本身引用的，其在開啓addivity下全部上級logger的，都會被調用。
在此基礎上，若一個appender被多個logger引用，可能致使重複日誌記錄的問題。

善用logger的additivity實現全軟件控制檯輸出信息，特定類型的信息輸出到文件。

For instance, you can configure logging such that log messages appear on the console (for all loggers in the system) while messages only from some specific set of loggers flow into a specific 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>

In this example, the console appender will log all the messages (for all loggers in the system) whereas only logging requests originating from the chapters.configuration logger and its children will go into the myApp.log file.