布局

附加器使用布局将日志事件格式化为满足消费日志事件的任何内容的需求。在 Log4j 1.x 和 Logback 中,预计布局将事件转换为字符串。在 Log4j 2 中,布局返回字节数组。这使得布局的结果在更多类型的附加器中变得有用。但是,这意味着您需要使用 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 布局

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

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

CsvParameterLayout 将事件的参数转换为 CSV 记录,忽略消息。要记录 CSV 记录,您可以使用通常的记录器方法 info()debug()

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

这将创建以下 CSV 记录

value1, value2, value3

或者,您可以使用 ObjectArrayMessage,它只携带参数

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

布局 CsvParameterLayoutCsvLogEventLayout 使用以下参数配置

CsvParameterLayout 和 CsvLogEventLayout
参数名称 类型 描述
format 字符串 预定义格式之一:DefaultExcelMySQLRFC4180TDF。请参阅 CSVFormat.Predefined.
delimiter 字符 将格式的分隔符设置为指定的字符。
escape 字符 将转义字符设置为指定的字符。
quote 字符 将 quoteChar 设置为指定的字符。
quoteMode 字符串 将格式的输出引用策略设置为指定的值。其中之一:ALLMINIMALNON_NUMERICNONE
nullString 字符串 在写入记录时,将 null 写入为给定的 nullString。
recordSeparator 字符串 将格式的记录分隔符设置为指定的字符串。
charset 字符集 输出字符集。
header 设置在打开流时要包含的标题。 描述。
footer 设置在关闭流时要包含的页脚。 描述。

将日志记录为 CSV 事件如下所示

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

生成具有以下字段的 CSV 记录

  1. 时间纳秒
  2. 时间毫秒
  3. 级别
  4. 线程 ID
  5. 线程名称
  6. 线程优先级
  7. 格式化消息
  8. 记录器 FQCN
  9. 记录器名称
  10. 标记
  11. 抛出代理
  12. 上下文映射
  13. 上下文堆栈
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 布局需要额外的 运行时依赖项

GELF 布局

将事件布局为 Graylog 扩展日志格式 (GELF) 1.1。

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

配置如下,以使用 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 参数
参数名称 类型 描述
host 字符串 host 属性的值(可选,默认为本地主机名)。
compressionType GZIPZLIBOFF 要使用的压缩(可选,默认为 GZIP
compressionThreshold int 如果数据大于此字节数,则压缩(可选,默认为 1024)
includeMapMessage 布尔值 是否将 MapMessage 中的字段包含为附加字段(可选,默认为 true)。
includeNullDelimiter 布尔值 是否在每个事件后包含 NULL 字节作为分隔符(可选,默认为 false)。对 Graylog GELF TCP 输入有用。不能与压缩一起使用。
includeStacktrace 布尔值 是否包含记录的 Throwables 的完整堆栈跟踪(可选,默认为 true)。如果设置为 false,则只包含 Throwable 的类名和消息。
includeThreadContext 布尔值 是否将线程上下文包含为附加字段(可选,默认为 true)。
mapMessageExcludes 字符串 MapMessage 中要排除的属性的逗号分隔列表,在格式化事件时。此属性仅在指定 includeMapMessage="true" 时适用。如果也指定了 mapMessageIncludes,则将忽略此属性。
mapMessageIncludes 字符串 MapMessage 中要包含的属性的逗号分隔列表,在格式化事件时。此属性仅在指定 includeMapMessage="true" 时适用。如果也指定了 mapMessageExcludes,则此属性将覆盖它们。此处指定的 MapMessage 字段,如果无值,将被省略。
mapPrefix 字符串 在渲染为字段时,要附加到 MapMessage 的所有元素的字符串。默认为空字符串。
messagePattern 字符串 用于格式化字符串的模式。不能同时指定 messagePattern 和 patternSelector。如果两者都存在,则将忽略消息模式,并将记录错误。如果未提供,则只使用从日志记录消息派生的文本。有关模式字符串的信息,请参阅 PatternLayout
omitEmptyFields 布尔值 如果为 true,则为 null 或为空字符串的字段将不会包含在 Gelf JSON 中的字段中。此设置不会影响这些字段是否出现在消息字段中。默认值为 false。
patternSelector PatternSelector 用于格式化字符串的 PatternSelector。不能同时指定 messagePattern 和 patternSelector。如果两者都存在,则将忽略消息模式,并将记录错误。如果未提供,则只使用从日志记录消息派生的文本。有关如何指定 PatternSelector 的信息,请参阅 PatternSelectors。有关模式字符串的信息,请参阅 PatternLayout
threadContextExcludes 字符串 在格式化事件时要排除的 ThreadContext 属性的逗号分隔列表。此属性仅在指定 includeThreadContext="true" 时适用。如果也指定了 threadContextIncludes,则将忽略此属性。
threadContextIncludes 字符串 在格式化事件时要包含的 ThreadContext 属性的逗号分隔列表。此属性仅在指定 includeThreadContext="true" 时适用。如果还指定了 threadContextExcludes,则此属性将覆盖它们。此处指定的 ThreadContext 字段如果没有值,将被省略。
ThreadContextPrefix 字符串 在 ThreadContextMap 的所有元素渲染为字段时要加在前面的字符串。默认为空字符串。

要将任何自定义字段包含在输出中,请使用以下语法

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

自定义字段按声明顺序包含。这些值支持 查找

另请参阅

HTML 布局

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

HtmlLayout 参数
参数名称 类型 描述
charset 字符串 将 HTML 字符串转换为字节数组时要使用的字符集。该值必须是有效的 Charset。如果未指定,此布局使用 UTF-8。
contentType 字符串 要分配给 Content-Type 标头的值。默认值为“text/html”。
locationInfo 布尔值

如果为 true,则文件名和行号将包含在 HTML 输出中。默认值为 false。

生成 位置信息 是一个昂贵的操作,可能会影响性能。谨慎使用。

title 字符串 将作为 HTML 标题显示的字符串。
fontName 字符串 要使用的 font-family。默认值为“arial,sans-serif”。
fontSize 字符串 要使用的 font-size。默认值为“small”。
datePattern 字符串 日志事件的日期格式。默认值为“JVM_ELAPSE_TIME”,它输出自 JVM 启动以来的毫秒数。有关其他有效值,请参阅 PatternLayout 的 日期模式
timezone 字符串 日志事件的时区 ID。如果未指定,此布局使用 java.util.TimeZone.getDefault 作为默认时区。与 PatternLayout 的 日期模式 一样,您可以使用 java.util.TimeZone.getTimeZone 中的时区 ID。

配置如下以在 HtmlLayout 中使用 dataPattern 和 timezone

<Appenders>
  <Console name="console">
    <HtmlLayout datePattern="ISO8601" timezone="GMT+0"/>
  </Console>
</Appenders>

JSON 布局

注意:JsonTemplate 被认为已弃用。JsonTemplateLayout 提供了更多功能,应改用它。

将一系列 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 开数组字符“[”,在结尾写入“]”,也不会在记录之间写入逗号“,”。

漂亮 JSON 与紧凑 JSON

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

JsonLayout 参数
参数名称 类型 描述
charset 字符串 转换为字节数组时要使用的字符集。该值必须是有效的 Charset。如果未指定,将使用 UTF-8。
compact 布尔值 如果为 true,则追加器不使用行尾和缩进。默认为 false。
eventEol 布尔值 如果为 true,则追加器在每个记录之后追加一个行尾。默认为 false。与 eventEol=true 和 compact=true 一起使用,以获得每行一个记录。
endOfLine 字符串 如果设置,则覆盖默认的行尾字符串。例如,将其设置为“\n”并与 eventEol=true 和 compact=true 一起使用,以使每行一个记录,用“\n”而不是“\r\n”分隔。默认为 null(即未设置)。
complete 布尔值 如果为 true,则追加器将包含 JSON 标头和页脚,以及记录之间的逗号。默认为 false。
properties 布尔值 如果为 true,则追加器将线程上下文映射包含在生成的 JSON 中。默认为 false。
propertiesAsList 布尔值 如果为 true,则线程上下文映射将包含为映射条目对象的列表,其中每个条目都有一个“key”属性(其值为键)和一个“value”属性(其值为值)。默认为 false,在这种情况下,线程上下文映射将包含为简单的键值对映射。
locationInfo 布尔值

如果为 true,则追加器将位置信息包含在生成的 JSON 中。默认为 false。

生成 位置信息 是一个昂贵的操作,可能会影响性能。谨慎使用。

includeStacktrace 布尔值 如果为 true,则包含任何已记录的 Throwable 的完整堆栈跟踪(可选,默认为 true)。
includeTimeMillis 布尔值 如果为 true,则 timeMillis 属性将包含在 Json 负载中,而不是瞬时。timeMillis 将包含自 1970 年 1 月 1 日午夜以来的毫秒数(UTC)。
stacktraceAsString 布尔值 是否将堆栈跟踪格式化为字符串,而不是嵌套对象(可选,默认为 false)。
includeNullDelimiter 布尔值 是否在每个事件之后包含 NULL 字节作为分隔符(可选,默认为 false)。
objectMessageAsJsonObject 布尔值 如果为 true,则 ObjectMessage 将作为 JSON 对象序列化到输出日志的“message”字段。默认为 false。

要将任何自定义字段包含在输出中,请使用以下语法

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

自定义字段始终位于最后,按声明顺序排列。这些值支持 查找

使用 JsonLayout 需要额外的 运行时依赖项

JSON 模板布局

JsonTemplateLayout 是一种可定制、高效且无垃圾的 JSON 发射布局。它根据提供的 JSON 模板中描述的结构对 LogEvent 进行编码。例如,给定以下 JSON 模板,它对 官方 Logstash JSONEventLayoutV1 进行建模

{
  "mdc": {
    "$resolver": "mdc"
  },
  "exception": {
    "exception_class": {
      "$resolver": "exception",
      "field": "className"
    },
    "exception_message": {
      "$resolver": "exception",
      "field": "message"
    },
    "stacktrace": {
      "$resolver": "exception",
      "field": "stackTrace",
      "stackTrace": {
        "stringified": true
      }
    }
  },
  "line_number": {
    "$resolver": "source",
    "field": "lineNumber"
  },
  "class": {
    "$resolver": "source",
    "field": "className"
  },
  "@version": 1,
  "source_host": "${hostName}",
  "message": {
    "$resolver": "message",
    "stringified": true
  },
  "thread_name": {
    "$resolver": "thread",
    "field": "name"
  },
  "@timestamp": {
    "$resolver": "timestamp"
  },
  "level": {
    "$resolver": "level",
    "field": "name"
  },
  "file": {
    "$resolver": "source",
    "field": "fileName"
  },
  "method": {
    "$resolver": "source",
    "field": "methodName"
  },
  "logger_name": {
    "$resolver": "logger",
    "field": "name"
  }
}

与以下 Log4j 配置结合使用

<JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>

JSON 模板布局将渲染 JSON 文档,如下所示

{
  "exception": {
    "exception_class": "java.lang.RuntimeException",
    "exception_message": "test",
    "stacktrace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
  },
  "line_number": 12,
  "class": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
  "@version": 1,
  "source_host": "varlik",
  "message": "Hello, error!",
  "thread_name": "main",
  "@timestamp": "2017-05-25T19:56:23.370+02:00",
  "level": "ERROR",
  "file": "JsonTemplateLayoutDemo.java",
  "method": "main",
  "logger_name": "org.apache.logging.log4j.JsonTemplateLayoutDemo"
}

有关完整文档,请参阅 JSON 模板布局 页面。

模式布局

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

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

请注意,任何文字文本(包括特殊字符)都可以包含在转换模式中。特殊字符包括\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表示日志事件的优先级应左对齐到五个字符的宽度。

如果模式字符串不包含用于处理已记录的 Throwable 的说明符,则模式的解析将表现得好像"%xEx" 说明符已添加到字符串的末尾。要完全禁止 Throwable 的格式化,只需在模式字符串中添加"%ex{0}" 作为说明符即可。

PatternLayout 参数
参数名称 类型 描述
charset 字符串 将 syslog 字符串转换为字节数组时要使用的字符集。该字符串必须是有效的 Charset。如果未指定,此布局使用平台默认字符集。
pattern 字符串 一个或多个来自下表中的转换模式的组合模式字符串。不能与 PatternSelector 一起指定。
patternSelector PatternSelector 一个组件,它分析 LogEvent 中的信息并确定应使用哪个模式来格式化事件。pattern 和 patternSelector 参数是互斥的。
replace RegexReplacement 允许替换结果字符串的某些部分。如果配置,replace 元素必须指定要匹配的正则表达式和替换。这执行与 RegexReplacement 转换器类似的功能,但应用于整个消息,而转换器仅应用于其模式生成的字符串。
alwaysWriteExceptions 布尔值 如果为 true(默认情况下),即使模式不包含异常转换,也会始终写入异常。这意味着,如果您在模式中不包含输出异常的方法,则默认异常格式化程序将添加到模式的末尾。将其设置为 false 将禁用此行为,并允许您从模式输出中排除异常。
header 字符串 要在每个日志文件顶部包含的可选标头字符串。
footer 字符串 要在每个日志文件底部包含的可选页脚字符串。
disableAnsi 布尔值 如果为 true,则不输出 ANSI 转义码。参数默认值为平台相关。如果在 Windows 上运行,则默认为 true,除非系统属性 log4j.skipJansi 设置为 false。在其他平台上,它默认为 false
noConsoleNoAnsi 布尔值 如果为 true(默认值为 false)并且 System.console() 为 null,则不输出 ANSI 转义码。
RegexReplacement 参数
参数名称 类型 描述
regex 字符串 要在结果字符串中匹配的符合 Java 规范的正则表达式。请参阅 Pattern
replacement 字符串 用于替换任何匹配的子字符串的字符串。

模式

Log4j 提供的转换是

转换模式 描述
c{precision}
logger{precision}

输出发布日志事件的记录器的名称。logger 转换说明符后面可以可选地加上精度说明符,它由一个十进制整数或以十进制整数开头的模式组成。

当精度说明符是一个整数值时,它会减小记录器名称的大小。如果数字为正,则布局会打印相应数量的最右侧记录器名称组件。如果为负,则布局会删除相应数量的最左侧记录器名称组件。如果精度包含句点,则句点之前的数字标识要从模式中剩余部分中的标记之前的项目中打印的长度。如果句点后的数字后面跟着一个星号,则表示将以完整形式打印多少个最右侧标记。请参阅下表以了解缩写示例。

如果精度包含任何非整数字符,则布局将根据模式缩写名称。如果精度整数小于 1,则布局仍会完整打印最右边的标记。默认情况下,布局会完整打印记录器名称。

转换模式 记录器名称 结果
%c{1} org.apache.commons.Foo Foo
%c{2} org.apache.commons.Foo commons.Foo
%c{10} org.apache.commons.Foo org.apache.commons.Foo
%c{-1} org.apache.commons.Foo apache.commons.Foo
%c{-2} org.apache.commons.Foo commons.Foo
%c{-10} org.apache.commons.Foo org.apache.commons.Foo
%c{1.} org.apache.commons.Foo o.a.c.Foo
%c{1.1.~.~} org.apache.commons.test.Foo o.a.~.~.Foo
%c{.} org.apache.commons.test.Foo ....Foo
%c{1.1.1.*} org.apache.commons.test.Foo o.a.c.test.Foo
%c{1.2.*} org.apache.commons.test.Foo o.a.c.test.Foo
%c{1.3.*} org.apache.commons.test.Foo o.a.commons.test.Foo
%c{1.8.*} org.apache.commons.test.Foo org.apache.commons.test.Foo
C{precision}
class{precision}

输出发出日志请求的调用者的完全限定类名。此转换说明符可以选择后跟精度说明符,该说明符遵循与记录器名称转换器相同的规则。

生成调用者的类名(位置信息)是一个昂贵的操作,可能会影响性能。谨慎使用。

d{pattern}
date{pattern}

输出日志事件的日期。日期转换说明符后面可以跟一对花括号,其中包含一个日期和时间模式字符串,符合 SimpleDateFormat

预定义的命名格式为

模式 示例
%d{DEFAULT} 2012-11-02 14:34:02,123
%d{DEFAULT_MICROS} 2012-11-02 14:34:02,123456
%d{DEFAULT_NANOS} 2012-11-02 14:34:02,123456789
%d{ISO8601} 2012-11-02T14:34:02,781
%d{ISO8601_BASIC} 20121102T143402,781
%d{ISO8601_OFFSET_DATE_TIME_HH} 2012-11-02'T'14:34:02,781-07
%d{ISO8601_OFFSET_DATE_TIME_HHMM} 2012-11-02'T'14:34:02,781-0700
%d{ISO8601_OFFSET_DATE_TIME_HHCMM} 2012-11-02'T'14:34:02,781-07:00
%d{ABSOLUTE} 14:34:02,781
%d{ABSOLUTE_MICROS} 14:34:02,123456
%d{ABSOLUTE_NANOS} 14:34:02,123456789
%d{DATE} 02 Nov 2012 14:34:02,781
%d{COMPACT} 20121102143402781
%d{UNIX} 1351866842
%d{UNIX_MILLIS} 1351866842781

您还可以使用一对花括号,其中包含一个符合 java.util.TimeZone.getTimeZone 的时区 ID。如果没有给出日期格式说明符,则使用 DEFAULT 格式。

您可以定义自定义日期格式

模式 示例
%d{HH:mm:ss,SSS} 14:34:02,123
%d{HH:mm:ss,nnnn} 到 %d{HH:mm:ss,nnnnnnnnn} 14:34:02,1234 到 14:34:02,123456789
%d{dd MMM yyyy HH:mm:ss,SSS} 02 Nov 2012 14:34:02,123
%d{dd MMM yyyy HH:mm:ss,nnnn} 到 %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn} 02 Nov 2012 14:34:02,1234 到 02 Nov 2012 14:34:02,123456789
%d{HH:mm:ss}{GMT+0} 18:34:02

%d{UNIX} 输出以秒为单位的 UNIX 时间。%d{UNIX_MILLIS} 输出以毫秒为单位的 UNIX 时间。UNIX 时间是当前时间与 1970 年 1 月 1 日午夜 UTC 之间的差值,以秒为单位(对于 UNIX)和以毫秒为单位(对于 UNIX_MILLIS)。虽然时间单位是毫秒,但粒度取决于操作系统(Windows)。这是一种有效地输出事件时间的方法,因为只进行从 long 到 String 的转换,没有涉及日期格式化。

Log4j 2.11 在 Java 9 上运行时,为比毫秒更精确的时间戳添加了有限的支持。请注意,并非所有 DateTimeFormatter 格式都受支持。只有表格中提到的格式的时间戳可以使用“纳秒”模式字母 n 而不是“秒的小数部分”模式字母 S

用户可以通过将系统属性 log4j2.Clock 设置为 SystemMillisClock,在 Java 9 上运行时恢复到毫秒精度时钟。

enc{pattern}{[HTML|XML|JSON|CRLF]}
encode{pattern}{[HTML|XML|JSON|CRLF]}

对特定标记语言的输出进行编码和转义特殊字符。默认情况下,如果只指定一个选项,则对 HTML 进行编码。第二个选项用于指定应使用哪种编码格式。此转换器对于对用户提供的数据进行编码特别有用,以便输出数据不会被错误地或不安全地写入。

典型的用法是对消息 %enc{%m} 进行编码,但用户输入也可以来自其他位置,例如 MDC %enc{%mdc{key}}

使用 HTML 编码格式,将替换以下字符

字符 替换
'\r', '\n' 分别转换为转义字符串“\\r”和“\\n”
&, <, >, ", ', / 替换为相应的 HTML 实体

使用 XML 编码格式,这遵循 XML 规范 中指定的转义规则

字符 替换
&, <, >, ", ' 替换为相应的 XML 实体

使用 JSON 编码格式,这遵循 RFC 4627 第 2.5 节 中指定的转义规则

字符 替换
U+0000 - U+001F \u0000 - \u001F
任何其他控制字符 编码为其 \uABCD 等效转义代码点
" \"
\ \\

例如,模式 {"message": "%enc{%m}{JSON}"} 可用于输出包含日志消息作为字符串值的有效 JSON 文档。

使用 CRLF 编码格式,将替换以下字符

字符 替换
'\r', '\n' 分别转换为转义字符串“\\r”和“\\n”
equals{pattern}{test}{substitution}
equalsIgnoreCase{pattern}{test}{substitution}

在评估模式后产生的字符串中,将字符串“test”的出现次数替换为其替换“substitution”。例如,"%equals{[%marker]}{[]}{}" 将用空字符串替换没有标记的事件产生的“[]”字符串。

模式可以任意复杂,特别是可以包含多个转换关键字。

ex|exception|throwable
{
  [ "none"
   | "full"
   | depth
   | "short"
   | "short.className"
   | "short.fileName"
   | "short.lineNumber"
   | "short.methodName"
   | "short.message"
   | "short.localizedMessage"]
}
  {filters(package,package,...)}
  {suffix(pattern)}
  {separator(separator)}

输出绑定到日志事件的 Throwable 跟踪,默认情况下,这将输出完整的跟踪,就像通常使用对 Throwable.printStackTrace() 的调用一样。

您可以在 throwable 转换词后面加上一个选项,形式为 %throwable{option}

%throwable{short} 输出 Throwable 的第一行。

%throwable{short.className} 输出发生异常的类的名称。

%throwable{short.methodName} 输出发生异常的方法名称。

%throwable{short.fileName} 输出发生异常的类的名称。

%throwable{short.lineNumber} 输出发生异常的行号。

%throwable{short.message} 输出消息。

%throwable{short.localizedMessage} 输出本地化消息。

%throwable{n} 输出堆栈跟踪的前 n 行。

指定 %throwable{none}%throwable{0} 将抑制异常的输出。

使用 {filters(packages)},其中 packages 是包名称列表,以抑制与堆栈跟踪中的匹配堆栈帧。

使用 {suffix(pattern)} 在每个堆栈帧的末尾添加 pattern 的输出。

使用 {separator(...)} 作为行尾字符串。例如:separator(|)。默认值为 line.separator 系统属性,该属性取决于操作系统。

F
file

输出发出日志请求的文件名。

生成文件信息(位置信息)是一个昂贵的操作,可能会影响性能。谨慎使用。

highlight{pattern}{style}

根据当前事件的日志级别,在封闭模式的结果中添加 ANSI 颜色。(参见 Jansi 配置。)

每个级别的默认颜色为

级别 ANSI 颜色
FATAL 亮红色
ERROR 亮红色
WARN 黄色
INFO 绿色
DEBUG 青色
TRACE 黑色(看起来是深灰色)

颜色名称是在 AnsiEscape 类中定义的 ANSI 名称。

颜色和属性名称是标准的,但确切的色调、色相或值。

颜色表
强度代码 0 1 2 3 4 5 6 7
普通 黑色 红色 绿色 黄色 蓝色 洋红色 青色 白色
黑色 红色 绿色 黄色 蓝色 洋红色 青色 白色

您可以使用默认颜色

%highlight{%d [%t] %-5level: %msg%n%throwable}

您可以在可选的 {style} 选项中覆盖默认颜色。例如

%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=bright_blue, INFO=black, DEBUG=bright_green, TRACE=blue}

同时可以使用真彩色(24 位)。例如

%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=bg_#5792e6 fg_#eef26b bold, INFO=black, DEBUG=#3fe0a8, TRACE=blue}

您可以只突出显示日志事件的一部分

%d [%t] %highlight{%-5level: %msg%n%throwable}

您可以设置消息的一部分样式,并突出显示日志事件的其余部分

%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}

您还可以使用 STYLE 键使用预定义的颜色组

%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
STYLE 值可以是以下之一
样式 描述
默认 参见上文
Logback
级别 ANSI 颜色
FATAL 闪烁的亮红色
ERROR 亮红色
WARN 红色
INFO 蓝色
DEBUG 普通
TRACE 普通
K{key}
map{key}
MAP{key}

输出 MapMessage 中的条目(如果事件中存在)。K 转换字符后面可以跟放置在花括号中的地图的键,例如 %K{clientNumber},其中 clientNumber 是键。将输出与键相对应的 Map 中的值。如果没有指定其他子选项,则将使用格式 {{key1,val1},{key2,val2}} 输出 Map 键值对集的全部内容。

l
location

输出生成日志事件的调用者的位置信息。

位置信息取决于 JVM 实现,但通常包括调用方法的完全限定名称,以及调用者的源文件名和行号(在括号中)。

生成 位置信息 是一个昂贵的操作,可能会影响性能。谨慎使用。

L
line

输出发出日志请求的行号。

生成行号信息(位置信息)是一个昂贵的操作,可能会影响性能。谨慎使用。

m{ansi}
msg{ansi}
message{ansi}

输出与日志事件关联的应用程序提供的消息。

从 Log4j 2.16.0 开始,出于安全原因,已删除对日志消息中查找的支持。{lookups}{nolookups} 选项现在在 %m、%msg 和 %message 模式上被忽略。如果指定了其中任何一个,则会记录一条消息。

添加 {ansi} 以使用 ANSI 转义代码呈现消息(需要 JAnsi,参见 配置。)

嵌入式 ANSI 代码的默认语法为

@|code(,code)* text|@

例如,要以绿色呈现消息 "Hello",请使用

@|green Hello|@

要以粗体和红色呈现消息 "Hello",请使用

@|bold,red Warning!|@

您还可以在配置中使用语法定义自定义样式名称

%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n

例如

%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n

调用站点可能如下所示

logger.info("@|KeyStyle {}|@ = @|ValueStyle {}|@", entry.getKey(), entry.getValue());
M
method

输出发出日志请求的方法名称。

生成调用者的方法名称(位置信息)是一个昂贵的操作,可能会影响性能。谨慎使用。

marker 标记的完整名称,包括父标记(如果存在)。
markerSimpleName 标记的简单名称(不包括父标记),如果存在。
maxLen
maxLength

输出评估模式的结果并截断结果。如果长度大于 20,则输出将包含尾随省略号。如果提供的长度无效,则使用默认值 100。

示例语法:%maxLen{%p: %c{1} - %m%notEmpty{ =>%ex{short}}}{160} 将限制为 160 个字符,并带有尾随省略号。另一个示例:%maxLen{%m}{20} 将限制为 20 个字符,没有尾随省略号。

n

输出平台相关的行分隔符字符或字符。

此转换字符提供与使用非可移植换行符字符串(如“\n”或“\r\n”)几乎相同的性能。因此,它是指定换行符的首选方法。

N
nano

输出在创建日志事件时System.nanoTime()的结果。

pid{[defaultValue]}
processId{[defaultValue]}

如果底层平台支持,则输出进程 ID。如果平台不支持进程 ID,则可以指定一个可选的默认值以显示。

variablesNotEmpty{pattern}
varsNotEmpty{pattern}
notEmpty{pattern}

当且仅当模式中的所有变量都不为空时,输出评估模式的结果。

例如

%notEmpty{[%marker]}
p|level{level=label, level=label, ...} p|level{length=n} p|level{lowerCase=true|false}

输出日志事件的级别。您以“level=value, level=value”的形式提供级别名称映射,其中 level 是级别的名称,value 是应显示的值,而不是级别的名称。

例如

%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}

或者,对于紧凑型

%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}

更简洁地说,为了获得与上述相同的结果,您可以定义级别标签的长度

%level{length=1}
如果长度大于级别名称长度,则布局使用正常的级别名称。

您可以组合两种类型的选项

%level{ERROR=Error, length=2}
这将为您提供Error级别名称和所有其他长度为 2 的级别名称。

最后,您可以输出小写级别名称(默认值为大写)

%level{lowerCase=true}
r
relative
输出从 JVM 启动到创建日志事件为止经过的毫秒数。
R{string}{length}
repeat{string}{length}
生成一个包含指定字符串的请求数量的实例的字符串。例如,“%repeat{*}{2}”将生成字符串“**”。
replace{pattern}{regex}{substitution}

在评估模式后生成的字符串中,将正则表达式“regex”的出现替换为其替换“substitution”。例如,“%replace{%msg}{\s}{}”将删除事件消息中包含的所有空格。

模式可以任意复杂,特别是可以包含多个转换关键字。例如,“%replace{%logger %msg}{\.}{/}”将用正斜杠替换日志记录器或事件消息中的所有点。

rEx|rException|rThrowable
  {
    ["none" | "short" | "full" | depth]
    [,filters(package,package,...)]
    [,separator(separator)]
  }
  {ansi(
    Key=Value,Value,...
    Key=Value,Value,...
    ...)
  }
  {suffix(pattern)}

与 %throwable 转换词相同,但堆栈跟踪从抛出的第一个异常开始打印,然后是每个后续的包装异常。

throwable 转换词后面可以跟一个选项,形式为%rEx{short},它只输出 Throwable 的第一行,或者%rEx{n},其中将打印堆栈跟踪的前 n 行。

指定%rEx{none}%rEx{0}将抑制打印异常。

使用filters(packages),其中packages是包名称列表,以抑制堆栈跟踪中匹配的堆栈帧。

使用separator字符串来分隔堆栈跟踪的行。例如:separator(|)。默认值为line.separator系统属性,它依赖于操作系统。

使用rEx{suffix(pattern)pattern的输出添加到输出中,仅当有 throwable 要打印时。

sn
sequenceNumber
包含一个序列号,该序列号将在每个事件中递增。计数器是一个静态变量,因此它只在共享相同转换器类对象的应用程序中是唯一的。
style{pattern}{ANSI style}

使用 ANSI 转义序列来设置封闭模式的结果的样式。样式可以由来自下表的空格分隔的样式名称列表组成。(参见 Jansi 配置。)

样式名称 描述
普通 正常显示
粗体
暗淡 暗淡或微弱的字符
下划线 带下划线的字符
闪烁 闪烁的字符
反转 反转视频
隐藏
黑色或 FG_Black 将前景色设置为黑色
红色或 FG_Red 将前景色设置为红色
绿色或 FG_Green 将前景色设置为绿色
黄色或 FG_Yellow 将前景色设置为黄色
蓝色或 FG_Blue 将前景色设置为蓝色
洋红色或 FG_Magenta 将前景色设置为洋红色
青色或 FG_Cyan 将前景色设置为青色
白色或 FG_White 将前景色设置为白色
默认或 FG_Default 将前景色设置为默认值(白色)
BG_Black 将背景色设置为黑色
BG_Red 将背景色设置为红色
BG_Green 将背景色设置为绿色
BG_Yellow 将背景色设置为黄色
BG_Blue 将背景色设置为蓝色
BG_Magenta 将背景色设置为洋红色
BG_Cyan 将背景色设置为青色
BG_White 将背景色设置为白色

例如

%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}

您也可以组合样式

%d %highlight{%p} %style{%logger}{bright cyan} %C{1.} %msg%n

您也可以将%与颜色一起使用,例如%black%blue%cyan等。例如

%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
T
tid
threadId
输出生成日志事件的线程的 ID。
t
tn
thread
threadName
输出生成日志事件的线程的名称。
tp
threadPriority
输出生成日志事件的线程的优先级。
fqcn 输出日志记录器的完全限定类名。
endOfBatch 输出日志事件的 EndOfBatch 状态,为“true”或“false”。
x
NDC
输出与生成日志事件的线程关联的线程上下文堆栈(也称为嵌套诊断上下文或 NDC)。
X{key[,key2...]}
mdc{key[,key2...]}
MDC{key[,key2...]}

输出与生成日志事件的线程关联的线程上下文映射(也称为映射诊断上下文或 MDC)。X转换字符后面可以跟一个或多个映射的键,放在大括号中,如%X{clientNumber},其中clientNumber是键。将输出与键对应的 MDC 中的值。

如果提供了一组键,例如%X{name, number},则将使用格式 {name=val1, number=val2} 输出 ThreadContext 中存在的每个键。键值对将按它们在列表中出现的顺序打印。

如果没有指定子选项,则将使用格式 {key1=val1, key2=val2} 输出 MDC 键值对集的全部内容。键值对将按排序顺序打印。

有关更多详细信息,请参见ThreadContext类。

u{"RANDOM" | "TIME"}
uuid
包含随机或基于时间的 UUID。基于时间的 UUID 是一个类型 1 UUID,它每毫秒可以生成多达 10,000 个唯一 ID,将使用每个主机的 MAC 地址,并且为了尝试确保同一主机上的多个 JVM 和/或类加载器之间的唯一性,每个 UUID 生成器类的实例将关联一个 0 到 16,384 之间的随机数,并包含在生成的每个基于时间的 UUID 中。由于基于时间的 UUID 包含 MAC 地址和时间戳,因此应谨慎使用,因为它们会导致安全漏洞。
xEx|xException|xThrowable
  {
    ["none" | "short" | "full" | depth]
    [,filters(package,package,...)]
    [,separator(separator)]
  }
  {ansi(
    Key=Value,Value,...
    Key=Value,Value,...
    ...)
  }
  {suffix(pattern)}

与 %throwable 转换词相同,但还包括类打包信息。

在异常的每个堆栈元素的末尾,将添加一个字符串,其中包含包含该类的 jar 文件的名称或该类所在的目录,以及在该 jar 的清单中找到的“Implementation-Version”。如果信息不确定,则类打包数据将以波浪号开头,即“~”字符。

throwable 转换词后面可以跟一个选项,形式为%xEx{short},它只输出 Throwable 的第一行,或者%xEx{n},其中将打印堆栈跟踪的前 n 行。指定%xEx{none}%xEx{0}将抑制打印异常。

使用filters(packages),其中packages是包名称列表,以抑制堆栈跟踪中匹配的堆栈帧。

使用separator字符串来分隔堆栈跟踪的行。例如:separator(|)。默认值为line.separator系统属性,它依赖于操作系统。

ansi选项使用 JAnsi 库使用 ANSI 转义代码呈现堆栈跟踪。(参见 配置。)使用{ansi}使用默认颜色映射。您可以使用key=value对指定自己的映射。键是

  • 前缀
  • 名称
  • NameMessageSeparator
  • 消息
  • CauseLabel
  • 文本
  • 更多
  • 被抑制
  • StackTraceElement.ClassName
  • StackTraceElement.ClassMethodSeparator
  • StackTraceElement.MethodName
  • StackTraceElement.NativeMethod
  • StackTraceElement.FileName
  • StackTraceElement.LineNumber
  • StackTraceElement.Container
  • StackTraceElement.ContainerSeparator
  • StackTraceElement.UnknownSource
  • ExtraClassInfo.Inexact
  • ExtraClassInfo.Container
  • ExtraClassInfo.ContainerSeparator
  • ExtraClassInfo.Location
  • ExtraClassInfo.Version

值是来自 JAnsi 的 Code 类的名称,例如bluebg_red等(Log4j 忽略大小写。)

特殊的键StyleMapName可以设置为以下预定义映射之一:SpockKirk

与 %throwable 一样,%xEx{suffix(pattern) 转换将在只有 throwable 要打印时将pattern的输出添加到输出中。

% 序列 %% 输出一个百分号。

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

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

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

可以使用最大字段宽度修饰符更改此行为,该修饰符由一个句点后跟一个十进制常数表示。如果数据项的长度超过最大字段,则从数据项的开头删除多余的字符,而不是从末尾删除。例如,如果最大字段宽度为 8,而数据项的长度为 10 个字符,则数据项的前两个字符将被删除。此行为与 C 语言中的 printf 函数不同,后者从末尾进行截断。

可以通过在句点后立即附加一个减号字符来实现从末尾截断。在这种情况下,如果最大字段宽度为 8,而数据项的长度为 10 个字符,则数据项的最后两个字符将被删除。

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

模式转换器
格式修饰符 左对齐 最小宽度 最大宽度 注释
%20c false 20 如果类别名称少于 20 个字符,则用空格左填充。
%-20c true 20 如果类别名称少于 20 个字符,则用空格右填充。
%.30c NA 30 如果类别名称超过 30 个字符,则从开头截断。
%20.30c false 20 30 如果类别名称短于 20 个字符,则用空格左填充。但是,如果类别名称超过 30 个字符,则从开头截断。
%-20.30c true 20 30 如果类别名称短于 20 个字符,则用空格右填充。但是,如果类别名称超过 30 个字符,则从开头截断。
%-20.-30c true 20 30 如果类别名称短于 20 个字符,则用空格右填充。但是,如果类别名称超过 30 个字符,则从末尾截断。

Windows 上的 ANSI 样式

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

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

示例模式

过滤的 Throwable

此示例演示如何从堆栈跟踪中过滤掉来自不重要包的类。

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

日志级别将根据事件的日志级别突出显示。所有在级别后面的内容将以亮绿色显示。

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

模式选择器

PatternLayout 可以使用 PatternSelector 配置,以允许它根据日志事件的属性或其他因素选择要使用的模式。PatternSelector 通常会使用 defaultPattern 属性配置,该属性在其他条件不匹配时使用,以及一组 PatternMatch 元素,这些元素标识可以选择的各种模式。

LevelPatternSelector

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

MarkerPatternSelector

MarkerPatternSelector 根据日志事件中包含的 Marker 选择模式。如果日志事件中的 Marker 等于或祖先为 PatternMatch key 属性中指定的名称,则将使用该 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 执行脚本,如配置章节的 脚本 部分所述。该脚本将传递配置的属性部分中配置的所有属性、Configuration 使用的 StrSubstitutor 在 "substitutor" 变量中,以及 "logEvent" 变量中的日志事件,并期望返回应使用的 PatternMatch key 的值,或者如果应使用默认模式,则返回 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 布局

顾名思义,Rfc5424Layout 根据 RFC 5424(增强的 Syslog 规范)格式化 LogEvent。虽然该规范主要针对通过 Syslog 发送消息,但这种格式对于其他目的非常有用,因为项目作为自描述的键值对传递到消息中。

Rfc5424Layout 参数
参数名称 类型 描述
appName 字符串 用作 RFC 5424 syslog 记录中 APP-NAME 的值。
charset 字符串 将 syslog 字符串转换为字节数组时要使用的字符集。该字符串必须是有效的 Charset。如果未指定,将使用默认系统字符集。
enterpriseNumber 整数 IANA 企业编号,如 RFC 5424 中所述
exceptionPattern 字符串 来自 PatternLayout 的转换说明符之一,定义要使用哪个 ThrowablePatternConverter 来格式化异常。可以包含对这些说明符有效的任何选项。默认情况下,不将事件中的 Throwable(如果有)包含在输出中。
facility 字符串 该设施用于尝试对消息进行分类。facility 选项必须设置为 "KERN"、"USER"、"MAIL"、"DAEMON"、"AUTH"、"SYSLOG"、"LPR"、"NEWS"、"UUCP"、"CRON"、"AUTHPRIV"、"FTP"、"NTP"、"AUDIT"、"ALERT"、"CLOCK"、"LOCAL0"、"LOCAL1"、"LOCAL2"、"LOCAL3"、"LOCAL4"、"LOCAL5"、"LOCAL6" 或 "LOCAL7" 之一。这些值可以指定为大写或小写字符。
format 字符串 如果设置为 "RFC5424",则数据将根据 RFC 5424 进行格式化。否则,它将被格式化为 BSD Syslog 记录。请注意,虽然 BSD Syslog 记录必须为 1024 字节或更短,但 SyslogLayout 不会截断它们。RFC5424Layout 也不会截断记录,因为接收器必须接受最多 2048 字节的记录,并且可能接受更长的记录。
id 字符串 根据 RFC 5424 格式化时要使用的默认结构化数据 ID。如果 LogEvent 包含 StructuredDataMessage,则将使用消息中的 ID 而不是此值。
includeMDC 布尔值 指示是否将来自 ThreadContextMap 的数据包含在 RFC 5424 Syslog 记录中。默认为 true。
loggerFields 键值对列表 允许将任意 PatternLayout 模式包含为指定的 ThreadContext 字段;没有默认值。要使用,请包含一个 <LoggerFields> 嵌套元素,其中包含一个或多个 <KeyValuePair> 元素。每个 <KeyValuePair> 必须具有一个 key 属性,该属性指定用于标识 MDC 结构化数据元素中字段的键名,以及一个 value 属性,该属性指定用作值的 PatternLayout 模式。
mdcExcludes 字符串 应从 LogEvent 中排除的 mdc 键的逗号分隔列表。这与 mdcIncludes 属性互斥。此属性仅适用于 RFC 5424 syslog 记录。
mdcIncludes 字符串 应包含在 FlumeEvent 中的 mdc 键的逗号分隔列表。列表中找不到的 MDC 中的任何键都将被排除。此选项与 mdcExcludes 属性互斥。此属性仅适用于 RFC 5424 syslog 记录。
mdcRequired 字符串 MDC 中必须存在的 mdc 键的逗号分隔列表。如果键不存在,则会抛出 LoggingException。此属性仅适用于 RFC 5424 syslog 记录。
mdcPrefix 字符串 应附加到每个 MDC 键的字符串,以将其与事件属性区分开来。默认字符串为 "mdc:"。此属性仅适用于 RFC 5424 syslog 记录。
mdcId 字符串 必需的 MDC ID。此属性仅适用于 RFC 5424 syslog 记录。
messageId 字符串 RFC 5424 syslog 记录的 MSGID 字段中要使用的默认值。
newLine 布尔值 如果为 true,则会在 syslog 记录的末尾附加一个换行符。默认为 false。
newLineEscape 字符串 应用于替换消息文本中换行符的字符串。

序列化布局

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

此布局已从 2.9 版开始弃用。Java 序列化存在固有的安全漏洞,不再建议使用此布局。包含相同信息的替代布局是 JsonLayout,配置为 properties="true"

Syslog 布局

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

SyslogLayout 参数
参数名称 类型 描述
charset 字符串 将 syslog 字符串转换为字节数组时要使用的字符集。该字符串必须是有效的 Charset。如果未指定,此布局使用 UTF-8。
facility 字符串 该设施用于尝试对消息进行分类。facility 选项必须设置为 "KERN"、"USER"、"MAIL"、"DAEMON"、"AUTH"、"SYSLOG"、"LPR"、"NEWS"、"UUCP"、"CRON"、"AUTHPRIV"、"FTP"、"NTP"、"AUDIT"、"ALERT"、"CLOCK"、"LOCAL0"、"LOCAL1"、"LOCAL2"、"LOCAL3"、"LOCAL4"、"LOCAL5"、"LOCAL6" 或 "LOCAL7" 之一。这些值可以指定为大写或小写字符。
newLine 布尔值 如果为 true,则会在 syslog 记录的末尾附加一个换行符。默认为 false。
newLineEscape 字符串 应用于替换消息文本中换行符的字符串。

XML 布局

追加一系列 Event 元素,如 log4j.dtd 中所定义。

完整的格式良好的 XML 与片段 XML

如果配置complete="true",则附加程序将输出一个格式良好的 XML 文档,其中默认命名空间是 Log4j 命名空间"https://logging.apache.org/log4j/2.0/events"。默认情况下,使用complete="false",您应该将输出作为外部实体包含在单独的文件中以形成格式良好的 XML 文档,在这种情况下,附加程序使用namespacePrefix,默认值为"log4j"

格式良好的 XML 文档遵循以下模式

<Event xmlns="htthttps://ging.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 处理指令和根元素。

标记

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

漂亮与紧凑的 XML

默认情况下,XML 布局不是紧凑的(也称为“漂亮”),compact="false",这意味着附加程序使用行尾字符并缩进行以格式化 XML。如果compact="true",则不使用行尾或缩进。当然,消息内容可能包含行尾。

XmlLayout 参数
参数名称 类型 描述
charset 字符串 转换为字节数组时要使用的字符集。该值必须是有效的 Charset。如果未指定,将使用 UTF-8。
compact 布尔值 如果为 true,则追加器不使用行尾和缩进。默认为 false。
complete 布尔值 如果为真,则附加程序将包含 XML 标头和页脚。默认值为假。
properties 布尔值 如果为真,则附加程序将包含生成的 XML 中的线程上下文映射。默认值为假。
locationInfo 布尔值

如果为真,则附加程序将包含生成的 XML 中的位置信息。默认值为假。

生成 位置信息 是一个昂贵的操作,可能会影响性能。谨慎使用。

includeStacktrace 布尔值 如果为 true,则包含任何已记录的 Throwable 的完整堆栈跟踪(可选,默认为 true)。
stacktraceAsString 布尔值 是否将堆栈跟踪格式化为字符串,而不是嵌套对象(可选,默认为 false)。
includeNullDelimiter 布尔值 是否在每个事件之后包含 NULL 字节作为分隔符(可选,默认为 false)。

要将任何自定义字段包含在输出中,请使用以下语法

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

自定义字段始终位于最后,按声明顺序排列。这些值支持 查找

使用 XmlLayout 需要额外的运行时依赖项

YAML 布局

追加一系列 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 参数
参数名称 类型 描述
charset 字符串 转换为字节数组时要使用的字符集。该值必须是有效的 Charset。如果未指定,将使用 UTF-8。
properties 布尔值 如果为真,则附加程序将包含生成的 YAML 中的线程上下文映射。默认值为假。
locationInfo 布尔值

如果为真,则附加程序将包含生成的 YAML 中的位置信息。默认值为假。

生成 位置信息 是一个昂贵的操作,可能会影响性能。谨慎使用。

includeStacktrace 布尔值 如果为 true,则包含任何已记录的 Throwable 的完整堆栈跟踪(可选,默认为 true)。
stacktraceAsString 布尔值 是否将堆栈跟踪格式化为字符串,而不是嵌套对象(可选,默认为 false)。
includeNullDelimiter 布尔值 是否在每个事件之后包含 NULL 字节作为分隔符(可选,默认为 false)。

要将任何自定义字段包含在输出中,请使用以下语法

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

自定义字段始终位于最后,按声明顺序排列。这些值支持 查找

使用 YamlLayout 需要额外的运行时依赖项

位置信息

如果其中一个布局配置了与位置相关的属性,例如 HTML locationInfo,或其中一个模式%C 或 %class%F 或 %file%l 或 %location%L 或 %line%M 或 %method,Log4j 将对堆栈进行快照,并遍历堆栈跟踪以查找位置信息。

这是一个昂贵的操作:对于同步记录器,速度慢 1.3-5 倍。同步记录器会在尽可能长时间地等待后才进行堆栈快照。如果不需要位置,则永远不会进行快照。

但是,异步记录器需要在将日志消息传递到另一个线程之前做出此决定;位置信息将在该点之后丢失。对于异步记录器,进行堆栈跟踪快照的性能影响甚至更高:带有位置的日志记录比没有位置的日志记录慢 30-100 倍。出于这个原因,异步记录器和异步附加程序默认情况下不包含位置信息。

您可以在记录器或异步附加程序配置中通过指定includeLocation="true"来覆盖默认行为。