Layouts

Appender 使用布局将 LogEvent 格式化为可以满足消耗日志事件的需求的形式。在 Log4j 1.x 和 Logback Layout 中，应该将事件转换为字符串。在 Log4j 2 中，布局返回一个字节数组。这样可以使布局的结果在更多类型的 Appender 中有用。但是，这意味着您需要使用Charset配置大多数布局，以确保字节数组包含正确的值。

使用字符集的布局的根类是 org.apache.logging.log4j.core.layout.AbstractStringLayout，其中默认值为 UTF-8.扩展 AbstractStringLayout 的每个布局都可以提供其自己的默认值。请参阅下面的每个布局。

Log4j 2.4.1 为 ISO-8859-1 和 US-ASCII 字符集添加了自定义字符编码器，以将 Java 8 内置的一些性能改进引入 Log4j，以便在 Java 7 上使用。对于仅记录日志的应用程序 ISO-8859-1 字符，指定此字符集将大大提高性能。

CSV Layouts

此布局创建逗号分隔值(CSV)条记录，并需要Apache Commons CSV 1.4.

可以通过两种方式使用 CSV 布局：首先，使用 CsvParameterLayout 记录事件参数以创建自定义数据库，通常将其创建到为此目的而专门配置的 Logger 和文件附加器中。其次，使用 CsvLogEventLayout 记录事件以创建数据库，这是使用完整的 DBMS 或使用支持 CSV 格式的 JDBC 驱动程序的替代方法。

CsvParameterLayout 将事件的参数转换为 CSV 记录，而忽略该消息。要记录 CSV 记录，可以使用常用的 Logger 方法 info()，debug()等：

logger.info("Ignored", value1, value2, value3);

这将创建 CSV 记录：

value1, value2, value3

或者，您可以使用仅包含参数的 ObjectArrayMessage：

logger.info(new ObjectArrayMessage(value1, value2, value3));

使用以下参数配置布局 CsvParameterLayout 和 CsvLogEventLayout：

• CsvParameterLayout 和 CsvLogEventLayout *

记录为 CSV 事件如下所示：

logger.debug("one={}, two={}, three={}", 1, 2, 3);

产生包含以下字段的 CSV 记录：

• Time Nanos

• Time Millis

• Level

• Thread ID

• Thread Name

• Thread Priority

• Formatted Message

• Logger FQCN

• Logger Name

• Marker

• Thrown Proxy

• Source

• Context Map

• Context Stack

0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[]

使用 CSV 布局需要额外的runtime dependencies。

GELF Layout

以 Graylog 扩展日志格式(GELF)1.1 布置事件。

如果日志事件数据大于 1024 字节(compressingThreshold)，则此布局将 JSON 压缩为 GZIP 或 ZLIB(compressionType)。此布局不实现分块。

进行以下配置，以使用 UDP 发送到 Graylog 2.x 服务器：

<Appenders>
    <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
        <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
    </Socket>
  </Appenders>

进行以下配置，以使用 TCP 发送到 Graylog 2.x 服务器：

<Appenders>
    <Socket name="Graylog" protocol="tcp" host="graylog.domain.com" port="12201">
        <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/>
    </Socket>
  </Appenders>

GelfLayout Parameters

要在输出中包括任何自定义字段，请使用以下语法：

<GelfLayout includeThreadContext="true" threadContextIncludes="loginId,requestId">
    %d %5p [%t] %c{1} %X{loginId, requestId} - %m%n
    <KeyValuePair key="additionalField1" value="constant value"/>
    <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
  </GelfLayout>

自定义字段包含在声明 Sequences 中。这些值支持lookups。

See also:

• The GELF specification

HTML Layout

HtmlLayout 生成一个 HTML 页面，并将每个 LogEvent 添加到表中的一行。

HtmlLayout Parameters

JSON Layout

将一系列 JSON 事件附加为序列化为字节的字符串。

完整的格式 JSON 和片段 JSON

如果您配置 complete =“ true”，则附加程序将输出格式正确的 JSON 文档。默认情况下，使用 complete =“ false”，您应该将输出作为外部文件包含在单独的文件中，以形成格式正确的 JSON 文档。

如果 complete =“ false”，则追加程序不会在文档的开头“]”和结尾处写入 JSON 开放数组字符“ [”，也不会在记录之间写入逗号“，”。

日志事件遵循以下模式：

{
  "instant" : {
    "epochSecond" : 1493121664,
    "nanoOfSecond" : 118000000
  },
  "thread" : "main",
  "level" : "INFO",
  "loggerName" : "HelloWorld",
  "marker" : {
    "name" : "child",
    "parents" : [ {
      "name" : "parent",
      "parents" : [ {
        "name" : "grandparent"
      } ]
    } ]
  },
  "message" : "Hello, world!",
  "thrown" : {
    "commonElementCount" : 0,
    "message" : "error message",
    "name" : "java.lang.RuntimeException",
    "extendedStackTrace" : [ {
      "class" : "logtest.Main",
      "method" : "main",
      "file" : "Main.java",
      "line" : 29,
      "exact" : true,
      "location" : "classes/",
      "version" : "?"
    } ]
  },
  "contextStack" : [ "one", "two" ],
  "endOfBatch" : false,
  "loggerFqcn" : "org.apache.logging.log4j.spi.AbstractLogger",
  "contextMap" : {
    "bar" : "BAR",
    "foo" : "FOO"
  },
  "threadId" : 1,
  "threadPriority" : 5,
  "source" : {
    "class" : "logtest.Main",
    "method" : "main",
    "file" : "Main.java",
    "line" : 29
  }
}

如果 complete =“ false”，则追加程序不会在文档的开头“]”和结尾处写入 JSON 开放数组字符“ [”，也不会在记录之间写入逗号“，”。

漂亮 vs.紧凑 JSON

compact 属性确定输出是否为“漂亮”。默认值为“ false”，这意味着追加程序使用行尾字符和缩进行来设置文本格式。如果 compact =“ true”，则不使用行尾或缩进，这将导致输出占用更少的空间。当然，消息内容可能包含转义的行尾。

JsonLayout Parameters

要在输出中包括任何自定义字段，请使用以下语法：

<JsonLayout>
    <KeyValuePair key="additionalField1" value="constant value"/>
    <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
  </JsonLayout>

自定义字段始终按声明的 Sequences 排在最后。这些值支持lookups。

使用 JsonLayout 需要额外的runtime dependencies。

Pattern Layout

可以使用模式字符串配置的灵活布局。此类的目的是格式化 LogEvent 并返回结果。结果的格式取决于转换模式。

转换模式与 C 中的 printf 函数的转换模式密切相关。转换模式由 Literals 文本和称为转换说明符的格式控制表达式组成。

请注意，转换模式中可以包括任何 Literals 文本，包括 Special Characters 。特殊字符包括 t ， n ， r ， f 。使用 **** 将单个反斜杠插入输出中。

每个转换说明符均以百分号(％)开头，后跟可选的格式修饰符和转换字符。转换字符指定数据类型，例如类别，优先级，日期，线程名称。格式修饰符控制字段宽度，填充，左对齐和右对齐。以下是一个简单的示例。

假设转换模式为 “％-5p [％t]：％m％n” ，并假定 Log4j 环境设置为使用 PatternLayout。然后声明

Logger logger = LogManager.getLogger("MyLogger");
logger.debug("Message 1");
logger.warn("Message 2");

将产生输出

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

请注意，文本和转换说明符之间没有明确的分隔符。模式分析器在读取转换字符时会知道何时到达转换说明符的末尾。在上面的示例中，转换说明符 ％-5p 表示应将记录事件的优先级设置为 5 个字符的宽度。

如果模式字符串不包含用于处理正在记录的 Throwable 的说明符，则模式的解析将如同已将“％xEx”说明符添加到字符串的末尾一样。要完全禁止 Throwable 格式化，只需在模式字符串中添加“％ex{0}”作为说明符。

PatternLayout Parameters

RegexReplacement Parameters

Patterns

Log4j 提供的转换是：

默认情况下，相关信息按原样输出。但是，借助格式修饰符可以更改最小字段宽度，最大字段宽度和对齐方式。

可选的格式修饰符位于百分号和转换字符之间。

第一个可选的格式修饰符是左对齐标志，它只是减号(-)字符。然后是可选的最小字段宽度修饰符。这是一个十进制常数，代表要输出的最少字符数。如果数据项需要较少的字符，则在左侧或右侧填充它，直到达到最小宽度。默认为在左侧填充(右对齐)，但您可以使用左侧对齐标志指定右填充。填充字符为空格。如果数据项大于最小字段宽度，则字段将扩展以容纳数据。该值永远不会被截断。要将零用作填充字符，请在最小字段宽度前面加上零。

可以使用最大字段宽度修饰符来更改此行为，该修饰符由句点和十进制常数指定。如果数据项比最大字段长，那么多余的字符将从数据项的开头而不是结尾处删除。例如，最大字段宽度为 8，数据项的长度为 10 个字符，然后删除该数据项的前两个字符。此行为与 C 中的 printf 函数不同，后者从头开始进行截断。

通过在句点之后添加减号，可以从结尾截断。在这种情况下，如果最大字段宽度为 8，数据项的长度为 10 个字符，则将删除数据项的最后两个字符。

以下是类别转换说明符的各种格式修改器示例。

Pattern Converters

Windows 上的 ANSI 样式

在许多平台上本机支持 ANSI 转义序列，但 Windows 默认情况下不支持。要启用 ANSI 支持，请将Jansi jar 添加到您的应用程序中，并将属性 log4j.skipJansi 设置为 false。这允许 Log4j 在写入控制台时使用 Jansi 添加 ANSI 转义码。

注意：在 Log4j 2.10 之前，默认情况下启用 Jansi。 Jansi 需要本机代码的事实意味着 Jansi 只能由单个类加载器加载。对于 Web 应用程序，这意味着 Jansi jar 必须位于 Web 容器的 Classpath 中。为了避免给 Web 应用程序造成问题，在没有从 Log4j 2.10 开始进行显式配置的情况下，Log4j 将不再自动尝试加载 Jansi。

Example Patterns

Filtered Throwables

本示例说明如何从堆栈跟踪中不重要的包中筛选出类。

<properties>
  <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
</properties>
...
<PatternLayout pattern="%m%xEx{filters(${filters})}%n"/>

打印到控制台的结果将类似于以下内容：

Exception java.lang.IllegalArgumentException: IllegalArgument
at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:72) [test-classes/:?]
... suppressed 26 lines
at $Proxy0.invoke(Unknown Source)} [?:?]
... suppressed 3 lines
Caused by: java.lang.NullPointerException: null pointer
at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:71) ~[test-classes/:?]
... 30 more

ANSI Styled

日志级别将根据事件的日志级别突出显示。遵循该级别的所有内容将变为亮绿色。

<PatternLayout>
  <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
</PatternLayout>

Pattern Selectors

可以使用 PatternSelector 配置 PatternLayout，以允许其基于日志事件的属性或其他因素选择要使用的模式。通常，PatternSelector 将配置有 defaultPattern 属性(在其他条件不匹配时使用)和一组 PatternMatch 元素，这些元素标识可以选择的各种模式。

LevelPatternSelector

LevelPatternSelector 根据日志事件的日志级别选择模式。如果日志事件中的 Level 等于(忽略大小写)在 PatternMatch 键属性上指定的名称，则将使用在那个 PatternMatch 元素上指定的模式。

MarkerPatternSelector

MarkerPatternSelector 根据日志事件中包含的 Marker 选择模式。如果日志事件中的 Marker 等于或是 PatternMatch 键属性上指定的名称的祖先，则将使用该 PatternMatch 元素上指定的模式。

<PatternLayout>
  <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
    <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </MarkerPatternSelector>
</PatternLayout>

ScriptPatternSelector

ScriptPatternSelector 执行配置一章的Scripts部分中描述的脚本。该脚本将传递配置的“属性”部分中配置的所有属性，“替换”变量中 Confguration 使用的 StrSubstitutor 和“ logEvent”变量中的 log 事件，并应返回 PatternMatch 的值应该使用的密钥；如果应该使用默认模式，则返回 null。

<PatternLayout>
  <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
    <Script name="BeanShellSelector" language="bsh"><![CDATA[
      if (logEvent.getLoggerName().equals("NoLocation")) {
        return "NoLocation";
      } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
        return "Flow";
      } else {
        return null;
      }]]>
    </Script>
    <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
    <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </ScriptPatternSelector>
</PatternLayout>

RFC5424 Layout

顾名思义，Rfc5424Layout 按照增强的 Syslog 规范RFC 5424格式化 LogEvents。尽管该规范主要针对通过 Syslog 发送消息，但该格式对于其他目的还是很有用的，因为项目在消息中作为自描述键/值对传递。

Rfc5424Layout Parameters

Serialized Layout

SerializedLayout 仅使用 Java 序列化将 LogEvent 序列化为字节数组。 SerializedLayout 不接受任何参数。

从 2.9 版开始不推荐使用此布局。 Java 序列化具有固有的安全性弱点，不再建议使用此布局。包含相同信息的替代布局是JsonLayout，配置为 properties =“ true”。

Syslog Layout

SyslogLayout 将 LogEvent 格式化为 BSD Syslog 记录，该记录与 Log4j 1.2 使用的格式相同。

SyslogLayout Parameters

XML Layout

附加log4j.dtd中定义的一系列 Event 元素。

完整的格式正确的 XML 与片段 XML

如果您配置 complete =“ true”，则附加程序将输出格式正确的 XML 文档，其中默认名称空间为 Log4j 名称空间“ http://logging.apache.org/log4j/2.0/events”。默认情况下，使用 complete =“ false”，您应将输出作为外部实体包含在单独的文件中，以形成格式正确的 XML 文档，在这种情况下，附加程序使用默认值为“ log4j”的 namespacePrefix。

格式正确的 XML 文档遵循以下模式：

<Event xmlns="http://logging.apache.org/log4j/2.0/events"
       level="INFO"
       loggerName="HelloWorld"
       endOfBatch="false"
       thread="main"
       loggerFqcn="org.apache.logging.log4j.spi.AbstractLogger"
       threadId="1"
       threadPriority="5">
  <Instant epochSecond="1493121664" nanoOfSecond="118000000"/>
  <Marker name="child">
    <Parents>
      <Marker name="parent">
        <Parents>
          <Marker name="grandparent"/>
        </Parents>
      </Marker>
    </Parents>
  </Marker>
  <Message>Hello, world!</Message>
  <ContextMap>
    <item key="bar" value="BAR"/>
    <item key="foo" value="FOO"/>
  </ContextMap>
  <ContextStack>
    <ContextStackItem>one</ContextStackItem>
    <ContextStackItem>two</ContextStackItem>
  </ContextStack>
  <Source
      class="logtest.Main"
      method="main"
      file="Main.java"
      line="29"/>
  <Thrown commonElementCount="0" message="error message" name="java.lang.RuntimeException">
    <ExtendedStackTrace>
      <ExtendedStackTraceItem
          class="logtest.Main"
          method="main"
          file="Main.java"
          line="29"
          exact="true"
          location="classes/"
          version="?"/>
    </ExtendedStackTrace>
  </Thrown>
</Event>

如果 complete =“ false”，则附加程序不会编写 XML 处理指令和根元素。

Marker

标记由 Event 元素内的 Marker 元素表示。仅当在日志消息中使用标记时，Marker 元素才会出现。标记父级的名称将在 Marker 元素的 parent 属性中提供。

漂亮与紧凑型 XML

默认情况下，XML 布局不是带有 compact =“ false”的紧凑格式(也就是不是“漂亮”)，这意味着追加程序使用行尾字符和缩进线来格式化 XML。如果 compact =“ true”，则不使用行尾或缩进。消息内容当然可以包含行尾。

XmlLayout Parameters

要在输出中包括任何自定义字段，请使用以下语法：

<XmlLayout>
    <KeyValuePair key="additionalField1" value="constant value"/>
    <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
  </XmlLayout>

自定义字段始终按声明的 Sequences 排在最后。这些值支持lookups。

使用 XmlLayout 需要额外的runtime dependencies。

YAML Layout

将一系列 YAML 事件附加为序列化为字节的字符串。

YAML 日志事件遵循以下模式：

---
instant:
 epochSecond: 1493121664
 nanoOfSecond: 118000000
thread: "main"
level: "INFO"
loggerName: "HelloWorld"
marker:
 name: "child"
 parents:
 - name: "parent"
   parents:
   - name: "grandparent"
message: "Hello, world!"
thrown:
 commonElementCount: 0
 message: "error message"
 name: "java.lang.RuntimeException"
 extendedStackTrace:
 - class: "logtest.Main"
   method: "main"
   file: "Main.java"
   line: 29
   exact: true
   location: "classes/"
   version: "?"
contextStack:
- "one"
- "two"
endOfBatch: false
loggerFqcn: "org.apache.logging.log4j.spi.AbstractLogger"
contextMap:
 bar: "BAR"
 foo: "FOO"
threadId: 1
threadPriority: 5
source:
 class: "logtest.Main"
 method: "main"
 file: "Main.java"
 line: 29

YamlLayout Parameters

要在输出中包括任何自定义字段，请使用以下语法：

<YamlLayout>
    <KeyValuePair key="additionalField1" value="constant value"/>
    <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
  </YamlLayout>

自定义字段始终按声明的 Sequences 排在最后。这些值支持lookups。

使用 YamlLayout 需要额外的runtime dependencies。

Location Information

如果其中一个布局配置了与位置相关的属性(例如 HTML locationInfo)，或者配置了模式％C 或％class，％F 或％file，％l 或％location，％L 或％line，％M 或％方法之一，则 Log4j 会获取堆栈的快照，并遍历堆栈跟踪以查找位置信息。

这是一项昂贵的操作：对于同步 Logger，速度要慢 1.3-5 倍。同步 Logger 在获取此堆栈快照之前会 await 尽可能长的时间。如果不需要位置，将永远不会拍摄快照。

但是，异步 Logger 需要在将日志消息传递到另一个线程之前做出决定。之后，位置信息将丢失。对于异步 Logger 而言，获取堆栈跟踪快照的performance impact甚至更高：有位置的记录比没有位置的记录慢 30-100 倍。因此，默认情况下，异步 Logger 和异步附加器不包含位置信息。

您可以通过指定 includeLocation =“ true”覆盖 Logger 或异步附加程序配置中的默认行为。