Filters

筛选器允许对日志事件进行评估，以确定是否或如何发布它们。一个过滤器将使用其一种过滤方法被调用并返回一个结果，该结果是一个枚举，具有以下三个值之一：ACCEPT，DENY 或 NEUTRAL。

可以在以下四个位置之一中配置过滤器：

• 上下文范围的筛选器直接在配置中配置。这些过滤器拒绝的事件将不会传递给 Logger 以进行进一步处理。事件被上下文范围的过滤器接受后，将不再由其他任何上下文范围的过滤器进行评估，也不会使用 Logger 的级别来过滤事件。但是，该事件将由 Logger 和 Appender 筛选器评估。

• Logger 过滤器在指定的 Logger 上配置。这些是在上下文范围过滤器和 Logger 的日志级别之后评估的。无论可加性设置如何，这些过滤器拒绝的事件都将被丢弃，并且该事件将不会传递给父 Logger。

• Appender 筛选器用于确定特定的 Appender 是否应处理事件的格式和发布。

• Appender 参考过滤器用于确定 Logger 是否应将事件路由到 Appender。

BurstFilter

BurstFilter 提供了一种机制，通过在达到最大限制后通过静默丢弃事件来控制处理 LogEvent 的速率。

突发过滤器参数

Parameter Name	Type	Description
level	String	要过滤的消息级别。如果超出了 maxBurst，则等于或低于此级别的所有内容都会被滤除。默认值为 WARN，这意味着将记录任何高于警告的消息，无论突发大小如何。
rate	float	每秒允许的平均事件数。
maxBurst	integer	在过滤事件以超过平均速率之前可以发生的最大事件数。默认值为速率的 10 倍。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

包含 BurstFilter 的配置可能如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

CompositeFilter

CompositeFilter 提供了一种指定多个过滤器的方法。它作为过滤器元素添加到配置中，并包含其他要评估的过滤器。 filter 元素不接受任何参数。

包含 CompositeFilter 的配置如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Filters>
    <MarkerFilter marker="EVENT" onMatch="ACCEPT" onMismatch="NEUTRAL"/>
    <DynamicThresholdFilter key="loginId" defaultThreshold="ERROR"
                            onMatch="ACCEPT" onMismatch="NEUTRAL">
      <KeyValuePair key="User1" value="DEBUG"/>
    </DynamicThresholdFilter>
  </Filters>
  <Appenders>
    <File name="Audit" fileName="logs/audit.log">
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
    </File>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Logger name="EventLogger" level="info">
      <AppenderRef ref="Audit"/>
    </Logger>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

DynamicThresholdFilter

DynamicThresholdFilter 允许基于特定属性按日志级别进行过滤。例如，如果在 ThreadContext Map 中捕获了用户的 loginId，则可以仅对该用户启用调试日志记录。如果日志事件不包含指定的 ThreadContext 项，则将返回 NEUTRAL。

动态阈值过滤器参数

Parameter Name	Type	Description
key	String	ThreadContext Map 中要比较的项目的名称。
defaultThreshold	String	要过滤的消息级别。仅当日志事件包含指定的 ThreadContext Map 项目且其值与键/值对中的任何键都不匹配时，才应用默认阈值。
keyValuePair	KeyValuePair[]	一个或多个 KeyValuePair 元素，它们定义键的匹配值以及在键匹配时要评估的 Level。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

这是包含 DynamicThresholdFilter 的示例配置：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <DynamicThresholdFilter key="loginId" defaultThreshold="ERROR"
                          onMatch="ACCEPT" onMismatch="NEUTRAL">
    <KeyValuePair key="User1" value="DEBUG"/>
  </DynamicThresholdFilter>
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

MapFilter

MapFilter 允许过滤 MapMessage 中的数据元素。

Map 过滤器参数

Parameter Name	Type	Description
keyValuePair	KeyValuePair[]	一个或多个 KeyValuePair 元素，它们定义 Map 中的键和要匹配的值。如果多次指定相同的键，则该键的检查将自动为“或”，因为 Map 只能包含一个值。
operator	String	如果运算符是“或”，则任何键/值对的匹配都将被视为匹配，否则所有键/值对必须匹配。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

在此配置中，MapFilter 可用于记录特定事件：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
    <KeyValuePair key="eventId" value="Login"/>
    <KeyValuePair key="eventId" value="Logout"/>
  </MapFilter>
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

由于配置的唯一 Logger 是根，因此该示例配置将表现出与前面的示例相同的行为。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
        <KeyValuePair key="eventId" value="Login"/>
        <KeyValuePair key="eventId" value="Logout"/>
      </MapFilter>
      <AppenderRef ref="RollingFile">
      </AppenderRef>
    </Root>
  </Loggers>
</Configuration>

第三个示例配置将表现出与前面的示例相同的行为，因为配置的唯一 Logger 是根，而根仅配置有单个添加程序引用。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile">
        <MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
          <KeyValuePair key="eventId" value="Login"/>
          <KeyValuePair key="eventId" value="Logout"/>
        </MapFilter>
      </AppenderRef>
    </Root>
  </Loggers>
</Configuration>

MarkerFilter

MarkerFilter 将配置的 Marker 值与 LogEvent 中包含的 Marker 进行比较。当标记名称与日志事件的标记或其父项之一匹配时，将发生匹配。

标记过滤器参数

Parameter Name	Type	Description
marker	String	要比较的标记的名称。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

如果标记匹配，则仅允许附加程序写入事件的示例配置：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="DENY"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

NoMarkerFilter

NoMarkerFilter 检查 LogEvent 中是否不包含任何标记。当“日志事件”中没有标记时，将发生匹配。

没有标记过滤器参数

Parameter Name	Type	Description
onMatch	string	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	string	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

如果没有标记，则仅允许附加程序写入事件的示例配置：

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <NoMarkerFilter onMatch="ACCEPT" onMismatch="DENY"/>
      <PatternLayout pattern="%d %p %c{1.} [%t] %m%n"/>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

RegexFilter

RegexFilter 允许将格式化或未格式化的消息与正则表达式进行比较。

正则表达式过滤器参数

Parameter Name	Type	Description
regex	String	正则表达式。
useRawMsg	boolean	如果为 true，则将使用未格式化的消息，否则将使用已格式化的消息。默认值为 false。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

如果事件包含单词“ test”，则仅允许事件由追加程序编写的示例配置：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <RegexFilter regex=".* test .*" onMatch="ACCEPT" onMismatch="DENY"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

Script

ScriptFilter 执行一个返回 true 或 false 的脚本。

脚本过滤器参数

Parameter Name	Type	Description
script	脚本，ScriptFile 或 ScriptRef	Script 元素，指定要执行的逻辑。
onMatch	String	脚本返回 true 时要采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器返回 false 时要采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

Script Parameters

Parameter Name	Type	Description
configuration	Configuration	拥有此 ScriptFilter 的配置。
level	Level	与事件关联的日志记录级别。仅在配置为全局过滤器时存在。
loggerName	String	Logger 的名称。仅在配置为全局过滤器时存在。
logEvent	LogEvent	正在处理的 LogEvent。配置为全局过滤器时不存在。
marker	Marker	标记在记录调用中传递(如果有)。仅在配置为全局过滤器时存在。
message	Message	与日志记录调用关联的消息。仅在配置为全局过滤器时存在。
parameters	Object[]	传递给日志记录调用的参数。仅在配置为全局过滤器时存在。某些消息包含参数作为消息的一部分。
throwable	Throwable	Throwable 传递给日志记录调用(如果有)。仅在配置为全局过滤器时存在。 Som 消息包括 Throwable 作为消息的一部分。
substitutor	StrSubstitutor	StrSubstitutor 用于替换查找变量。

下面的示例演示如何声明脚本字段，然后在特定组件中引用它们。有关如何使用 Script 元素将脚本代码直接嵌入配置中的示例，请参见ScriptCondition。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="ERROR">
  <Scripts>
    <ScriptFile name="filter.js" language="JavaScript" path="src/test/resources/scripts/filter.js" charset="UTF-8" />
    <ScriptFile name="filter.groovy" language="groovy" path="src/test/resources/scripts/filter.groovy" charset="UTF-8" />
  </Scripts>
  <Appenders>
    <List name="List">
      <PatternLayout pattern="[%-5level] %c{1.} %msg%n"/>
    </List>
  </Appenders>
  <Loggers>
    <Logger name="TestJavaScriptFilter" level="trace" additivity="false">
      <AppenderRef ref="List">
        <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
          <ScriptRef ref="filter.js" />
        </ScriptFilter>
      </AppenderRef>
    </Logger>
    <Logger name="TestGroovyFilter" level="trace" additivity="false">
      <AppenderRef ref="List">
        <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
          <ScriptRef ref="filter.groovy" />
        </ScriptFilter>
      </AppenderRef>
    </Logger>
    <Root level="trace">
      <AppenderRef ref="List" />
    </Root>
  </Loggers>
</Configuration>

StructuredDataFilter

StructuredDataFilter 是一个 MapFilter，它也允许对事件 ID，类型和消息进行过滤。

结构化数据过滤器参数

Parameter Name	Type	Description
keyValuePair	KeyValuePair[]	一个或多个 KeyValuePair 元素，它们定义 Map 中的键和要匹配的值。 “ id”，“ id.name”，“ type”和“ message”应分别用于在 StructuredDataId，StructuredDataId 的名称部分，类型和格式化消息上进行匹配。如果多次指定相同的键，则该键的检查将自动为“或”，因为 Map 只能包含一个值。
operator	String	如果运算符是“或”，则任何键/值对的匹配都将被视为匹配，否则所有键/值对必须匹配。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

像在此配置中一样，StructuredDataFilter 可用于记录特定事件：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <StructuredDataFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
    <KeyValuePair key="id" value="Login"/>
    <KeyValuePair key="id" value="Logout"/>
  </StructuredDataFilter>
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

ThreadContextMapFilter(或 ContextMapFilter)

ThreadContextMapFilter 或 ContextMapFilter 允许针对当前上下文中的数据元素进行过滤。默认情况下，这是 ThreadContextMap。

上下文 Map 过滤器参数

Parameter Name	Type	Description
keyValuePair	KeyValuePair[]	一个或多个 KeyValuePair 元素，它们定义 Map 中的键和要匹配的值。如果多次指定相同的键，则该键的检查将自动为“或”，因为 Map 只能包含一个值。
operator	String	如果运算符是“或”，则任何键/值对的匹配都将被视为匹配，否则所有键/值对必须匹配。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

包含 ContextMapFilter 的配置可能如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <ContextMapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
    <KeyValuePair key="User1" value="DEBUG"/>
    <KeyValuePair key="User2" value="WARN"/>
  </ContextMapFilter>
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

ContextMapFilter 也可以应用于 Logger 进行过滤：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <BurstFilter level="INFO" rate="16" maxBurst="100"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
      <ContextMapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
        <KeyValuePair key="foo" value="bar"/>
        <KeyValuePair key="User2" value="WARN"/>
      </ContextMapFilter>
    </Root>
  </Loggers>
</Configuration>

ThresholdFilter

如果 LogEvent 中的级别与配置的级别相同或更特定，则此过滤器返回 onMatch 结果，否则返回 onMismatch 值。例如，如果 ThresholdFilter 配置为 Level ERROR，并且 LogEvent 包含 Level DEBUG，则将返回 onMismatch 值，因为 ERROR 事件比 DEBUG 更具体。

阈值滤波器参数

Parameter Name	Type	Description
level	String	要匹配的有效级别名称。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

如果级别匹配，仅允许附加程序写入事件的示例配置：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <ThresholdFilter level="TRACE" onMatch="ACCEPT" onMismatch="DENY"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>

TimeFilter

时间过滤器可用于将过滤器限制为一天中的特定时间。

时间过滤器参数

Parameter Name	Type	Description
start	String	HH：mm：ss 格式的时间。
end	String	HH：mm：ss 格式的时间。如果指定的结束时间小于开始时间，则不会写入任何日志条目。
timezone	String	与事件时间戳进行比较时使用的时区。
onMatch	String	过滤器匹配时采取的措施。可以是接受，拒绝或中性。默认值为“中性”。
onMismatch	String	过滤器不匹配时采取的措施。可以是接受，拒绝或中性。默认值为 DENY。

一个示例配置，该配置仅允许追加程序每天使用默认时区在上午 5:00 到 5:30 之间编写事件：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Appenders>
    <RollingFile name="RollingFile" fileName="logs/app.log"
                 filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
      <TimeFilter start="05:00:00" end="05:30:00" onMatch="ACCEPT" onMismatch="DENY"/>
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>