[参考](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实例，以便可以将其视为编码器。