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>