Logback 手册 - 第六章：布局 - 1

来源：logback.qos.ch/manual/layo… 作者：Ceki Gülcü、Sébastien Pennec、Carl Harris 版权所有 © 2000-2022 QOS.ch Sarl

本文档采用 知识共享署名 - 非商业性使用 - 相同方式共享 2.5 许可协议

TCP implementations will follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others.

TCP 实现会遵循一个稳健性的一般原则：在你所做的事情上要保守，对于来自他人的接受则要宽容。

——JON POSTEL，RFC 793

什么是布局？

为了运行本章中的示例，您需要确保类路径中存在某些 jar 文件。请参考 设置页面 获取更多详细信息。

如果您曾经想知道，布局与佛罗里达州的大庄园无关。布局是 logback 组件，负责将传入事件转换为字符串。Layout 接口中的 format() 方法接受代表事件（任何类型）的对象并返回一个字符串。下面是 Layout 接口的概要。

public interface Layout<E> extends ContextAware, LifeCycle {

  String doLayout(E event);
  String getFileHeader();
  String getPresentationHeader();
  String getFileFooter();
  String getPresentationFooter();
  String getContentType();
}

该接口非常简单，但足以满足许多格式化需求。来自得克萨斯州的德克萨斯州开发人员，您可能从约瑟夫·海勒的《第二十二条军规》中认识他，可能会惊叹道：实现一个布局只需要五个方法！！？

Logback-classic

Logback-classic 只能处理类型为 ch.qos.logback.classic.spi.ILoggingEvent 的事件。这一事实将贯穿本节。

编写您自己的自定义布局

让我们为 logback-classic 模块实现一个简单而功能强大的布局，它打印自应用程序启动以来经过的时间、日志事件的级别、调用线程（用方括号括起来）、其记录器名称、一个破折号，然后是事件消息和一个换行符。

示例输出可能如下所示：

10489 DEBUG [main] com.marsupial.Pouch - Hello world.

以下是一个可能的实现，由得克萨斯州的开发人员编写：

示例：布局的示例实现 (logback-examples/src/main/java/chapters/layouts/MySampleLayout.java)

package chapters.layouts;

import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.LayoutBase;

public class MySampleLayout extends LayoutBase<ILoggingEvent> {

  public String doLayout(ILoggingEvent event) {
    StringBuffer sbuf = new StringBuffer(128);
    sbuf.append(event.getTimeStamp() - event.getLoggingContextVO.getBirthTime());
    sbuf.append(" ");
    sbuf.append(event.getLevel());
    sbuf.append(" [");
    sbuf.append(event.getThreadName());
    sbuf.append("] ");
    sbuf.append(event.getLoggerName();
    sbuf.append(" - ");
    sbuf.append(event.getFormattedMessage());
    sbuf.append(CoreConstants.LINE_SEP);
    return sbuf.toString();
  }
}

请注意，MySampleLayout 扩展了 LayoutBase。这个类管理所有布局实例共有的状态，比如布局是否已启动或已停止、头部、尾部和内容类型数据。它允许开发人员专注于他 / 她的 Layout 预期的格式。请注意，LayoutBase 类是泛型的。在其类声明中，MySampleLayout 扩展了 LayoutBase<ILoggingEvent>。

doLayout(ILoggingEvent event) 方法，即 MySampleLayout 中唯一的方法，首先实例化一个 StringBuffer。随后添加事件参数的各个字段。得克萨斯州的人小心地打印了消息的格式化形式。如果伴随着日志请求传递了一个或多个参数，这是很重要的。

在将这些各种字符添加到字符串缓冲区后，doLayout() 方法将缓冲区转换为一个 String 并返回结果值。

在上面的示例中，doLayout 方法忽略了事件中可能包含的任何异常。在一个真实的布局实现中，您很可能也想打印异常的内容。

配置您自定义的布局

自定义布局像配置其他组件一样进行配置。如前所述，FileAppender 及其子类需要一个编码器。为了满足这一要求，我们传递一个 LayoutWrappingEncoder 实例给 FileAppender，该实例包装了我们的 MySampleLayout。以下是配置文件：

示例：MySampleLayout 的配置 (logback-examples/src/main/resources/chapters/layouts/sampleLayoutConfig.xml)

传统格式

<configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
      <layout class="chapters.layouts.MySampleLayout" />
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

规范格式 (1.3)

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration>

<configuration>
  <import class="ch.qos.logback.core.ConsoleAppender"/>
  <import class="chapters.layouts.MySampleLayout"/>
  <import class="ch.qos.logback.core.encoder.LayoutWrappingEncoder"/>

  <appender name="STDOUT" class="ConsoleAppender">
    <encoder class="LayoutWrappingEncoder">
      <layout class="MySampleLayout"/>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="STDOUT"/>
  </root>
</configuration>

样例应用程序 chapters.layouts.SampleLogging 使用作为第一个参数传递的配置脚本配置 logback，然后记录调试消息，接着是错误消息。

要运行此示例，请在 logback-examples 目录中执行以下命令。

java chapters.layouts.SampleLogging src/main/java/chapters/layouts/sampleLayoutConfig.xml

这将产生以下输出：

0 DEBUG [main] chapters.layouts.SampleLogging - 一切顺利
0 ERROR [main] chapters.layouts.SampleLogging - 或许不太顺利...

那很简单。持怀疑态度的伊利亚学派的皮罗，坚称除了不确定性外没有任何确定的东西，而这也没有被确定的可能，他可能会问：有关带有选项的布局怎么样？读者将在 MySampleLayout2.java 中找到我们自定义布局的略微修改版本。正如本手册中所述，向布局或任何其他 logback 组件添加属性只需要声明该属性的 setter 方法即可。

MySampleLayout2 类包含两个属性。第一个是可以添加到输出的前缀。第二个属性用于选择是否显示发送日志请求的线程的名称。

这是 MySampleLayout2 类的副本：

package chapters.layouts;

import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.LayoutBase;

public class MySampleLayout2 extends LayoutBase<ILoggingEvent> {

  String prefix = null;
  boolean printThreadName = true;

  public void setPrefix(String prefix) {
    this.prefix = prefix;
  }

  public void setPrintThreadName(boolean printThreadName) {
    this.printThreadName = printThreadName;
  }

  public String doLayout(ILoggingEvent event) {
    StringBuffer sbuf = new StringBuffer(128);
    if (prefix != null) {
      sbuf.append(prefix + ": ");
    }
    sbuf.append(event.getTimeStamp() - event.getLoggerContextVO().getBirthTime());
    sbuf.append(" ");
    sbuf.append(event.getLevel());
    if (printThreadName) {
      sbuf.append(" [");
      sbuf.append(event.getThreadName());
      sbuf.append("] ");
    } else {
      sbuf.append(" ");
    }
    sbuf.append(event.getLoggerName());
    sbuf.append(" - ");
    sbuf.append(event.getFormattedMessage());
    sbuf.append(LINE_SEP);
    return sbuf.toString();
  }
}

只需添加相应的 setter 方法即可启用属性的配置。注意，PrintThreadName 属性是一个 boolean 而不是 String。logback 组件的配置在 配置章节 中详细介绍。Joran 章节 提供了更多细节。这是为 MySampleLayout2 量身定制的配置文件。

传统格式

<configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
      <layout class="chapters.layouts.MySampleLayout2">
        <prefix>MyPrefix</prefix>
        <printThreadName>false</printThreadName>
      </layout>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

规范格式 (1.3)

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration>

<configuration>
  <import class="chapters.layouts.MySampleLayout2"/>
  <import class="ch.qos.logback.core.encoder.LayoutWrappingEncoder"/>
  <import class="ch.qos.logback.core.ConsoleAppender"/>

  <appender name="STDOUT" class="ConsoleAppender">
    <encoder class="LayoutWrappingEncoder">
      <layout class="MySampleLayout2">
        <prefix>MyPrefix</prefix>
        <printThreadName>false</printThreadName>
      </layout>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="STDOUT"/>
  </root>
</configuration>

PatternLayout

Logback 经典版附带了一个灵活的布局，称为 PatternLayout。与所有布局一样，PatternLayout 接收日志事件并返回一个 String。但是，通过调整 PatternLayout 的转换模式，可以自定义此 String。

PatternLayout 的转换模式与 C 编程语言中的 printf() 函数的转换模式密切相关。转换模式由文字文本和称为 转换说明符 的格式控制表达式组成。您可以在转换模式中插入任何文字文本。每个转换说明符以百分号 '%' 开头，后面是可选的 格式修饰符，转换词和大括号之间的可选参数。转换词控制要转换的数据字段，例如日志记录器名称、级别、日期或线程名称。格式修饰符控制字段宽度、填充以及左右对齐。

如前所述，FileAppender 和其子类期望一个编码器。因此，当与 FileAppender 或其子类一起使用时，必须将 PatternLayout 包装在编码器内。考虑到 FileAppender/PatternLayout 组合非常常见，logback 附带了一个名为 PatternLayoutEncoder 的编码器，专门用于包装 PatternLayout 实例，以便将其视为编码器。以下是一个示例，演示了如何以程序方式配置带有 PatternLayoutEncoder 的 ConsoleAppender：

示例：使用 PatternLayout 的示例用法 (logback-examples/src/main/java/chapters/layouts/PatternSample.java)

package chapters.layouts;

import org.slf4j.LoggerFactory;

import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.LoggerContext;
import ch.qos.logback.classic.encoder.PatternLayoutEncoder;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.ConsoleAppender;

public class PatternSample {

  static public void main(String[] args) throws Exception {
    Logger rootLogger = (Logger)LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
    LoggerContext loggerContext = rootLogger.getLoggerContext();
    // we are not interested in auto-configuration
    loggerContext.reset();

    PatternLayoutEncoder encoder = new PatternLayoutEncoder();
    encoder.setContext(loggerContext);
    encoder.setPattern("%-5level [%thread]: %message%n");
    encoder.start();

    ConsoleAppender<ILoggingEvent> appender = new ConsoleAppender<ILoggingEvent>();
    appender.setContext(loggerContext);
    appender.setEncoder(encoder);
    appender.start();

    rootLogger.addAppender(appender);

    rootLogger.debug("Message 1");
    rootLogger.warn("Message 2");
  }
}

在上面的示例中，转换模式被设置为 "%-5level [%thread]: %message%n"。logback 中包含的转换词的概要将很快给出。运行 PatternSample 应用程序：

java java chapters.layouts.PatternSample

将在控制台上产生以下输出。

DEBUG [main]: Message 1 WARN [main]: Message 2

请注意，在转换模式 "%-5level [%thread]: %message%n" 中，文字文本和转换说明符之间没有显式的分隔符。在解析转换模式时，PatternLayout 能够区分文字文本（空格字符、括号、冒号字符）和转换说明符。在上面的示例中，转换说明符 %-5level 表示日志事件的级别应该左对齐到五个字符的宽度。格式说明符将在下面解释。

在 PatternLayout 中，括号可以用于分组转换模式。因此，'(' 和 ')' 具有特殊含义，如果要作为字面值使用，则需要转义。 括号的特殊性质在下面的 解释。

如前所述，某些转换说明符可能包含在大括号中传递的可选参数。一个带有选项的示例转换说明符可以是 %logger{10}。这里的 "logger" 是转换词，10 是选项。选项将在下面 进一步讨论。

下表描述了识别的转换词及其选项。当在同一个表格单元中列出多个转换词时，它们被视为别名。

0    [main] DEBUG - logging statement
Caller+0   at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22)
Caller+1   at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17)

16   [main] DEBUG - logging statement
Caller+0   at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22)
Caller+1   at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17)
Caller+2   at mainPackage.ConfigTester.main(ConfigTester.java:38)

0    [main] DEBUG - logging statement
Caller+0   at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17)

mainPackage.foo.​bar.TestException: Houston we have a problem
  at mainPackage.foo.​bar.TestThrower.​fire(TestThrower.​java:22)
  at mainPackage.foo.​bar.TestThrower.​readyToLaunch(TestThrower.​java:17)
  at mainPackage.ExceptionLauncher.​main(ExceptionLauncher.​java:38)

mainPackage.foo.​bar.TestException: Houston we have a problem
  at mainPackage.foo.​bar.TestThrower.​fire(TestThrower.​java:22)

mainPackage.foo.​bar.TestException: Houston we have a problem
  at mainPackage.foo.​bar.TestThrower.​fire(TestThrower.​java:22)
  at mainPackage.foo.​bar.TestThrower.​readyToLaunch(TestThrower.​java:17)
  at mainPackage.ExceptionLauncher.​main(ExceptionLauncher.​java:38)

mainPackage.foo.​bar.TestException: Houston we have a problem
    at mainPackage.foo.​bar.TestThrower.​fire(TestThrower.​java:22)
    at mainPackage.foo.​bar.TestThrower.​readyToLaunch(TestThrower.​java:17)

java.lang.NullPointerException
    at com.xyz.Wombat(Wombat.java:57) ~[wombat-1.3.jar:1.3]
    at  com.xyz.Wombat(Wombat.java:76) ~[wombat-1.3.jar:1.3]
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.5.0_06]
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[na:1.5.0_06]
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[na:1.5.0_06]
    at java.lang.reflect.Method.invoke(Method.java:585) ~[na:1.5.0_06]
    at org.junit.internal.runners.TestMethod.invoke(TestMethod.java:59) [junit-4.4.jar:na]
    at org.junit.internal.runners.MethodRoadie.runTestMethod(MethodRoadie.java:98) [junit-4.4.jar:na]
    ...etc 

java.lang.NullPointerException
    at com.xyz.Wombat(Wombat.java:57) ~<span class="hljs-string">[wombat-1.3.jar:1.3]
    at com.xyz.Wombat(Wombat.java:76) ~<span class="hljs-string">[wombat-1.3.jar:1.3]
  Wrapped by: org.springframework.BeanCreationException: Error creating bean with name 'wombat':
    at org.springframework.AbstractBeanFactory.getBean(AbstractBeanFactory.java:248) <span class="hljs-string">[spring-2.0.jar:2.0]
    at org.springframework.AbstractBeanFactory.getBean(AbstractBeanFactory.java:170) <span class="hljs-string">[spring-2.0.jar:2.0]
    at org.apache.catalina.StandardContext.listenerStart(StandardContext.java:3934) <span class="hljs-string">[tomcat-6.0.26.jar:6.0.26]

% 字符具有特殊含义

在转换模式的上下文中，百分号具有特殊含义，如果要将其作为文字包含在内，需要使用反斜杠进行转义，例如 "%d %p \% %m%n"。

转换词后立即跟随的文字的限制

在大多数情况下，文字自然包含空格或其他分隔符，以免与转换词混淆。例如，模式 "%level[%thread]-%message%n" 包含字符串文字 "[" 和 "]-"。然而，如果在转换词后紧跟一个可以作为 Java 标识符一部分的字符，logback 的模式解析器会被误认为该文字是转换词的一部分。例如，模式 "%date%nHello" 将被解释为两个转换词 %date 和 %nHello，因为 %nHello 不是已知的转换词，所以 logback 会输出 %PARSER_ERROR[nHello] 用于 %nHello。如果希望字符串文字 "Hello" 立即将 %n 和 Hello 分开，可以将空参数列表传递给 %n。例如，"%date%n{}Hello" 将被解释为 %date 后跟 %n 后跟文字 "Hello"。

格式修饰符

默认情况下，相关信息会按原样输出。然而，通过格式修饰符的帮助，可以更改每个数据字段的最小和最大宽度以及对齐方式。

可选的格式修饰符放置在百分号和转换字符或词之间。

第一个可选的格式修饰符是 左对齐标志，即减号（-）字符。然后是可选的 最小字段宽度 修饰符。这是一个十进制常量，表示要输出的最少字符数。如果数据项包含的字符少于这个宽度，它将在左侧或右侧填充，直到达到最小宽度。默认情况是在左侧填充（右对齐），但可以使用左对齐标志指定右填充。填充字符是空格。如果数据项大于最小字段宽度，则该字段会扩展以容纳数据。该值永远不会被截断。

可以使用 最大字段宽度 修饰符来更改此行为，该修饰符由一个小数点和一个十进制常量组成。如果数据项长于最大字段宽度，则会从数据项的 开头 删除多余的字符。例如，如果最大字段宽度是 8，数据项长度为 10 个字符，则会删除数据项的前两个字符。这种行为与 C 语言中的 printf 函数不同，C 语言中的截断是从末尾进行的。

通过在小数点后面直接添加一个减号字符，可以实现从末尾进行截断。在这种情况下，如果最大字段宽度为 8，数据项长度为 10 个字符，则会删除数据项的最后两个字符。

下面是 logger 转换说明符的各种格式修饰符示例。

下表列出了格式修饰符截断的示例。请注意，方括号，即一对 "[]" 字符，不是输出的一部分。它们用于界定输出的宽度。

仅输出一个字母表示级别

在级别的位置上，不要打印 TRACE、DEBUG、WARN、INFO 或 ERROR，而是只打印 T、D、W、I 和 E。你可以编写一个用于此目的的自定义转换器，或者简单地利用格式修饰符（刚刚讨论过的）将级别值缩短为一个字符。合适的转换说明符将是 "%.-1level"。

版权声明：本文为博主「佳佳」的原创文章，遵循 CC 4.0 BY-NC-SA 版权协议，转载请附上原文出处链接及本声明。
原文链接：www.liujiajia.me/2023/12/7/l…