过滤器 Filters

过滤器允许对日志事件进行评估，以确定是否或如何发布它们。

Filter将在其过滤器方法之一上被调用，并将返回一个Result，这是一个Enum，具有3个值之一- ACCEPT, DENY或NEUTRAL。

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

1) 上下文范围的过滤器直接在配置中配置。被这些筛选器拒绝的事件将不会传递给日志记录器进行进一步处理。

一旦事件被上下文范围的过滤器接受，它将不会被任何其他上下文范围的过滤器评估，也不会使用记录器的级别来过滤事件。然而，该事件将由记录器和Appender过滤器评估。

2) 记录器过滤器是在指定的记录器上配置的。这些在上下文范围过滤器和日志记录器的日志级别之后进行评估。

被这些过滤器拒绝的事件将被丢弃，并且无论添加性设置如何，事件都不会传递给父Logger。

3) Appender过滤器用于确定是否应该由特定的Appender处理事件的格式化和发布。

4) Appender引用过滤器用于确定Logger是否应该将事件路由到Appender。

BurstFilter

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

参数

Parameter Name Type Description
level String 要过滤的消息级别。如果超过maxBurst，则等于或低于此级别的任何内容都将被过滤掉。默认值是WARN，这意味着任何高于WARN的消息都将被记录下来，而不管突发的大小。
rate float 允许的每秒平均事件数。
maxBurst integer 在过滤超过平均速率的事件之前可以发生的最大事件数。默认值是该比率的10倍。
onMatch String 当过滤器匹配时要采取的操作。可以是ACCEPT, DENY或NEUTRAL。缺省值为NEUTRAL。
onMismatch String 当过滤器不匹配时采取的操作。可以是ACCEPT, DENY或NEUTRAL。缺省值为DENY。

例子

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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提供了一种指定多个过滤器的方法。它作为过滤器元素添加到配置中，并包含要评估的其他过滤器。

过滤器元素不接受任何参数。

包含CompositeFilter的配置可能如下所示:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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允许基于特定属性按日志级别进行过滤。

例如，如果用户的loginId在ThreadContext Map中被捕获，那么就有可能仅为该用户启用调试日志记录。如果日志事件不包含指定的ThreadContext项，则返回NEUTRAL。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" >
  <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中的数据元素进行过滤。

例子

在这个配置中，MapFilter可以用来记录特定的事件:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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>

MarkerFilter

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

例子

一个示例配置，只允许在Marker匹配的情况下由appender写入事件:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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>

MutableThreadContextMapFilter(或MutableContextMapFilter)

MutableThreadContextMapFilter或MutableContextMapFilter允许对当前上下文中的数据元素进行过滤。

默认情况下，这是ThreadContext Map。要比较的值是在外部定义的，可以定期轮询以查看更改。

例子

一个包含MutableContextMapFilter的配置可能看起来像这样:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <MutableContextMapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or"
    configLocation="http://localhost:8080/threadContextFilter.json" pollInterval="300">
  </MutableContextMapFilter>
  <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>

NoMarkerFilter

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

例子

一个示例配置，只允许在没有标记的情况下由appender写入事件:

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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允许将格式化或未格式化的消息与正则表达式进行比较。

例子

一个示例配置，只允许appender编写包含单词”test”的事件:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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>

脚本

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

例子

下面的示例展示了如何声明脚本字段，然后在特定组件中引用它们。有关如何使用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、类型和消息进行过滤。

例子

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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允许对当前上下文中的数据元素进行过滤。默认情况下，这是ThreadContext Map。

例子

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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>

ThresholdFilter

如果LogEvent中的级别与配置的级别相同或更具体，则此过滤器返回onMatch结果，否则返回onMismatch值。

例如，如果ThresholdFilter配置了ERROR级别，并且LogEvent包含DEBUG级别，那么onMismatch值将被返回，因为ERROR事件比DEBUG事件更具体。

例子

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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

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

例子

一个示例配置，只允许appender在每天早上5:00到5:30使用默认时区写入事件:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
  <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>

参考资料

https://logging.apache.org/log4j/2.x/manual/filters.html