log4j2使用手册（中文）第八章 Lookups

作者: 在下喵星人 | 来源:发表于2019-07-26 11:39 被阅读0次

Lookups提供了一种在Log4j配置文件任意位置添加值的方法。它们是实现StrLookup接口的特定类型的插件。有关如何在配置文件中使用Lookup的信息，请参Configuration页面的“属性替换”部分。

Context Map Lookup

ContextMapLookup允许应用程序将数据存储在Log4j ThreadContext Map中，然后检索Log4j配置中的值。在下面的示例中，应用程序将使用键“loginId”将当前用户的登录ID存储在ThreadContext Map中。在初始配置处理期间，第一个’$’将被删除。 PatternLayout支持使用Lookup进行插值，然后为每个事件解析变量。请注意，模式“％X {loginId}”将获得相同的结果。

<File name="Application" fileName="application.log">
  <PatternLayout>
    <pattern>%d %p %c{1.} [%t] $${ctx:loginId} %m%n</pattern>
  </PatternLayout>
</File>

DateLookup

DateLookup与其他查找有些不同，因为它不使用键来定位值。相反，该键可用于指定对SimpleDateFormat有效的日期格式字符串。当前日期或与当前日志事件关联的日期将按指定格式进行格式化。

<RollingFile name="Rolling-${map:type}" fileName="${filename}" filePattern="target/rolling1/test1-$${date:MM-dd-yyyy}.%i.log.gz">
  <PatternLayout>
    <pattern>%d %p %c{1.} [%t] %m%n</pattern>
  </PatternLayout>
  <SizeBasedTriggeringPolicy size="500" />
</RollingFile>

Docker Lookup

DockerLookup可用于从运行应用程序的Docker容器中查找属性。

Log4j Docker提供对以下容器属性的访问：

containerId	分配给容器的完整ID。
containreName	分配给容器的名称。
imageId	分配给镜像的id。
imageName	分配给镜像的名称。
shortContainerId	容器ID的前12个字符。
shortImageId	镜像ID的前12个字符。

<JsonLayout properties="true" compact="true" eventEol="true">
  <KeyValuePair key="containerId" value="${docker:containerId}"/>
  <KeyValuePair key="containerName" value="${docker:containerName}"/>
  <KeyValuePair key="imageName" value="${docker:imageName}"/>
</JsonLayout>

此Lookup受Log4j Docker支持中列出的要求的约束

EnvironmentLookup

EnvironmentLookup允许系统配置环境变量，无论是在/etc/profile之类的全局文件中，还是在应用程序的启动脚本中，然后从日志配置中检索这些变量。下面的示例在应用程序日志中包含当前登录用户的名称。

<File name="Application" fileName="application.log">
  <PatternLayout>
    <pattern>%d %p %c{1.} [%t] $${env:USER} %m%n</pattern>
  </PatternLayout>
</File>

此lookup还支持默认值。在下面的示例中，当USER环境变量未定义时，使用默认值jdoe：

<File name="Application" fileName="application.log">
  <PatternLayout>
    <pattern>%d %p %c{1.} [%t] $${env:USER:-jdoe} %m%n</pattern>
  </PatternLayout>
</File>

Java Lookup

JavaLookup允许使用java：前缀在方便的预格式化字符串中检索Java环境信息。

键	描述
version	简短的Java版本，如：Java version 1.7.0_67
runtime	Java运行时版本，如：Java(TM) SE Runtime Environment(build 1.7.0_67-b01) from Oracle Corporation
vm	Java VM版本，如：Java HotSpot(TM) 64-Bit Server VM (build 24.65-b04, mixed mode)
os	操作系统版本，如：Windows 7 6.1 Service Pack 1,architecture: amd64-64
locale	硬件信息，如：default locale: en_US, platform encoding: Cp1252
hw	硬件信息，如：processors: 4, architecture: amd64-64, instruction sets: amd64

例如:

<File name="Application" fileName="application.log">
  <PatternLayout header="${java:runtime} - ${java:vm} - ${java:os}">
    <Pattern>%d %m%n</Pattern>
  </PatternLayout>
</File>

JndiLookup

JndiLookup允许通过JNDI检索变量。默认情况下，密钥将以java:comp/env/为前缀，但如果密钥包含“:”，则不会添加前缀。

<File name="Application" fileName="application.log">
  <PatternLayout>
    <pattern>%d %p %c{1.} [%t] $${jndi:logging/context-name} %m%n</pattern>
  </PatternLayout>
</File>

Java的JNDI模块在Android上不可用。

JVM输入参数 Lookup（JMX）

映射JVM输入参数 - 但不是主参数 - 使用JMX获取JVM参数。使用前缀jvmrunargs来访问JVM参数。有关java.lang.management.RuntimeMXBean.getInputArguments（）的信息，请参阅Javadocs。 Java的JMX模块在Android或Google App Engine上不可用。

Log4j配置Location Lookup

Log4j配置属性。表达式 ${log4j：configLocation}和$ {log4j：configParentLocation}分别提供log4j配置文件及其父文件夹的绝对路径。以下示例使用此Lookup将日志文件放在相对于log4j配置文件的目录中。

<File name="Application" fileName="${log4j:configParentLocation}/logs/application.log">
  <PatternLayout>
    <pattern>%d %p %c{1.} [%t] %m%n</pattern>
  </PatternLayout>
</File>

Main Arguments Lookup (Application)

此Lookup要求您手动将应用程序的主要参数提供给Log4j：

import org.apache.logging.log4j.core.lookup.MainMapLookup;
 
public static void main(String args[]) {
  MainMapLookup.setMainArguments(args);
  ...
}

如果已设置主参数，则此lookup允许应用程序从日志记录配置中检索这些主参数值。 main：前缀后面的键可以是参数列表中从0开始索引，也可以是字符串，其中$ {main：myString}替换为主参数列表中myString后面的值。
例如，假设static void main String []参数是：

--file foo.txt --verbose -x bar

然后可以进行以下替换：

表达式	结果
${main:0}	–file
${main:1}	foo.txt
${main:2}	–verbose
${main:3}	-x
${main:4}	bar
${main:–file}	foo.txt
${main:-x}	bar
${main:bar}	null

用法示例：

<File name="Application" fileName="application.log">
  <PatternLayout header="File: ${main:--file}">
    <Pattern>%d %m%n</Pattern>
  </PatternLayout>
</File>

Map Lookup

MapLookup有多种用途。

为配置文件中Properties声明的属性提供基础。
从LogEvents中的MapMessages中检索值。
检索使用MapLookup.setMainArguments（String []）设置的值。

第一项仅表示MapLookup用于替换配置文件中定义的属性。指定这些变量时没有前缀 - 例如$ {name}等。第二种用法允许替换当前MapMessage中的值（如果其中一个是当前日志事件的一部分）。在下面的示例中，RoutingAppender将为MapMessage中名为“type”的键的每个惟一值使用不同的RollingFileAppender。注意，当以这种方式使用时，“type”的值应该在properties声明中声明，以便在消息不是MapMessage或MapMessage不包含键的情况下提供默认值。有关如何设置默认值的信息，请参阅 Configuration 页面的属性替换部分。

<Routing name="Routing">
  <Routes pattern="$${map:type}">
    <Route>
      <RollingFile name="Rolling-${map:type}" fileName="${filename}"
                   filePattern="target/rolling1/test1-${map:type}.%i.log.gz">
        <PatternLayout>
          <pattern>%d %p %c{1.} [%t] %m%n</pattern>
        </PatternLayout>
        <SizeBasedTriggeringPolicy size="500" />
      </RollingFile>
    </Route>
  </Routes>
</Routing>

Marker Lookup

markerlookup允许您在有趣的配置中使用标记，如路由追加器。请考虑以下YAML配置和基于标记记录到不同文件的代码：

Configuration:
  status: debug
 
  Appenders:
    Console:
    RandomAccessFile:
      - name: SQL_APPENDER
        fileName: logs/sql.log
        PatternLayout:
          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
      - name: PAYLOAD_APPENDER
        fileName: logs/payload.log
        PatternLayout:
          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
      - name: PERFORMANCE_APPENDER
        fileName: logs/performance.log
        PatternLayout:
          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
 
    Routing:
      name: ROUTING_APPENDER
      Routes:
        pattern: "$${marker:}"
        Route:
        - key: PERFORMANCE
          ref: PERFORMANCE_APPENDER
        - key: PAYLOAD
          ref: PAYLOAD_APPENDER
        - key: SQL
          ref: SQL_APPENDER
 
  Loggers:
    Root:
      level: trace
      AppenderRef:
        - ref: ROUTING_APPENDER

public static final Marker SQL = MarkerFactory.getMarker("SQL");
public static final Marker PAYLOAD = MarkerFactory.getMarker("PAYLOAD");
public static final Marker PERFORMANCE = MarkerFactory.getMarker("PERFORMANCE");
 
final Logger logger = LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
 
logger.info(SQL, "Message in Sql.log");
logger.info(PAYLOAD, "Message in Payload.log");
logger.info(PERFORMANCE, "Message in Performance.log");

请注意，配置的关键部分是pattern:：“$$ {marker：}”。这将生成三个日志文件，每个文件都包含特定标记的日志事件。 Log4j将使用SQL标记将日志事件路由到sql.log，将带有PAYLOAD标记的日志事件路由到payload.log，依此类推。

您可以使用符号“$ {marker：name}”和“$$ {marker：name}”来检查是否存在标记，其中name是标记名称。如果标记存在，则表达式返回名称，否则返回null。

Structured Data Lookup

StructuredDataLookup与MapLookup非常相似，它将从StructuredDataMessages中检索值。除了Map值之外，它还将返回id的名称部分和类型字段。下面的示例和MapMessage的示例之间的主要区别在于，“type”是StructuredDataMessage的一个属性，而“type”必须是MapMessage中Map的一个键。

<Routing name="Routing">
  <Routes pattern="$${sd:type}">
    <Route>
      <RollingFile name="Rolling-${sd:type}" fileName="${filename}"
                   filePattern="target/rolling1/test1-${sd:type}.%i.log.gz">
        <PatternLayout>
          <pattern>%d %p %c{1.} [%t] %m%n</pattern>
        </PatternLayout>
        <SizeBasedTriggeringPolicy size="500" />
      </RollingFile>
    </Route>
  </Routes>
</Routing>

System Properties Lookup

由于通过使用系统属性在应用程序内部和外部定义值是很常见的，因此很自然地应该可以通过Lookup来访问它们。由于系统属性通常在应用程序之外定义，因此通常会看到以下内容：

<Appenders>
  <File name="ApplicationLog" fileName="${sys:logPath}/app.log"/>
</Appenders>

此查找还支持默认值。在下面的示例中，当未定义logPath系统属性时，将使用缺省值/var/logs：

<Appenders>
  <File name="ApplicationLog" fileName="${sys:logPath:-/var/logs}/app.log"/>
</Appenders>

Web Lookup

WebLookup允许应用程序检索与ServletContext关联的变量。除了能够在ServletContext中检索各种字段之外，WebLookup还支持查找存储为属性的值或配置为初始化参数。下表列出了可以检索的各种键：

键	描述
attr.name	返回具有指定名称的ServletContext属性
contextPath	Web应用程序的上下文路径
effectiveMajorVersion	获取此ServletContext所代表的应用程序所基于的Servlet规范的主要版本
effectiveMinorVersion	获取此ServletContext所代表的应用程序所基于的Servlet规范的次要版本。
initParam.name	返回具有指定名称的ServletContext初始化参数
majorVersion	返回此servlet容器支持的Servlet API的主要版本。
minorVersion	返回此servlet容器支持的Servlet API的次要版本。
rootDir	返回使用值“/”调用getRealPath的结果。
serverInfo	返回运行servlet的servlet容器的名称和版本。
servletContextName	返回部署描述符的display-name元素中定义的Web应用程序的名称

指定的任何其他键名都将首先检查ServletContext属性是否存在该名称，然后检查该名称的初始化参数是否存在。如果找到键，则返回相应的值。

<Appenders>
  <File name="ApplicationLog" fileName="${web:rootDir}/app.log"/>
</Appenders>

log4j2使用手册（中文）第一章介绍
log4j2使用手册（中文）第二章架构
log4j2使用手册（中文）第三章 Log4j 1.x 迁移至Log4j 2
log4j2使用手册（中文）第四章 API
log4j2使用手册（中文）第五章 Configuration
log4j2使用手册（中文）第六章使用
log4j2使用手册（中文）第七章 Web Applications and JSPs
log4j2使用手册（中文）第八章 Lookups