Skip to content

Commit a40a468

Browse files
ppkarwaszppkarwasz
committed
Revamp the Filters page
In this PR we: - add a section about the filtering process, that explains in detail all the places, where a filter can be configured. - add the description of 3 filters, - improve the documentation of the remaining filters, by replacing the complete XML configuration examples with shorter examples in 4 formats that concentrate on the filter itself. Closes #2529, [LOG4J2-3485](https://issues.apache.org/jira/browse/LOG4J2-3485) and [LOG4J2-3682](https://issues.apache.org/jira/browse/LOG4J2-3682).
1 parent 6d1a52d commit a40a468

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+2166
-894
lines changed

‎src/site/antora/modules/ROOT/examples/manual/filters/ContextMapFilter.json

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"Configuration": {
3+
"monitorInterval": 10,
4+
"Appenders": {
5+
"Console": {
6+
"name": "CONSOLE",
7+
"JsonTemplateLayout": {}
8+
}
9+
},
10+
"Loggers": {
11+
"Root": {
12+
"level": "ALL",
13+
"AppenderRef": {
14+
"ref": "CONSOLE"
15+
}
16+
}
17+
},
18+
// tag::filter[]
19+
"ContextMapFilter": {
20+
"operator": "AND",
21+
"KeyValuePair": [
22+
{
23+
"key": "clientId",
24+
"value": "1234"
25+
},
26+
{
27+
"key": "userId",
28+
"value": "alice"
29+
},
30+
{
31+
"key": "userId",
32+
"value": "bob"
33+
}
34+
]
35+
}
36+
// end::filter[]
37+
}
38+
}

‎src/site/antora/modules/ROOT/examples/manual/filters/ContextMapFilter.properties

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
monitorInterval = 10
2+
3+
appender.0.type = Console
4+
appender.0.name = CONSOLE
5+
appender.0.layout.type = JsonTemplateLayout
6+
7+
rootLogger.level = ALL
8+
rootLogger.appenderRef.0.ref = CONSOLE
9+
10+
# tag::filter[]
11+
filter.0.type = ContextMapFilter
12+
filter.0.operator = AND
13+
14+
filter.0.kv0.type = KeyValuePair
15+
filter.0.kv0.key = clientId
16+
filter.0.kv0.value = 1234
17+
18+
filter.0.kv1.type = KeyValuePair
19+
filter.0.kv1.key = userId
20+
filter.0.kv1.value = alice
21+
22+
filter.0.kv2.type = KeyValuePair
23+
filter.0.kv2.key = userId
24+
filter.0.kv2.value = bob
25+
# end::filter[]

‎src/site/antora/modules/ROOT/examples/manual/filters/ContextMapFilter.xml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<Configuration xmlns="https://logging.apache.org/xml/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="
4+
https://logging.apache.org/xml/ns
5+
https://logging.apache.org/xml/ns/log4j-config-2.xsd"
6+
monitorInterval="10">
7+
<Appenders>
8+
<Console name="CONSOLE">
9+
<JsonTemplateLayout/>
10+
</Console>
11+
</Appenders>
12+
<Loggers>
13+
<Root level="ALL">
14+
<AppenderRef ref="CONSOLE"/>
15+
</Root>
16+
</Loggers>
17+
<!-- tag::filter[] -->
18+
<ContextMapFilter operator="AND">
19+
<!-- tag::kvp[] -->
20+
<KeyValuePair key="clientId" value="1234"/>
21+
<KeyValuePair key="userId" value="alice"/>
22+
<KeyValuePair key="userId" value="bob"/>
23+
<!-- end::kvp[] -->
24+
</ContextMapFilter>
25+
<!-- end::filter[] -->
26+
</Configuration>

‎src/site/antora/modules/ROOT/examples/manual/filters/ContextMapFilter.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Configuration:
2+
monitorInterval: 10
3+
Appenders:
4+
Console:
5+
name: "CONSOLE"
6+
JsonTemplateLayout: { }
7+
Loggers:
8+
Root:
9+
level: "ALL"
10+
AppenderRef:
11+
ref: "CONSOLE"
12+
# tag::filter[]
13+
ContextMapFilter:
14+
operator: "AND"
15+
KeyValuePair:
16+
- key: "clientId"
17+
value: "1234"
18+
- key: "userId"
19+
value: "alice"
20+
- key: "userId"
21+
value: "bob"
22+
# end::filter[]

‎src/site/antora/modules/ROOT/examples/manual/filters/DynamicThresholdFilter.json

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{
2+
"Configuration": {
3+
"monitorInterval": 10,
4+
"Appenders": {
5+
"Console": {
6+
"name": "CONSOLE",
7+
"JsonTemplateLayout": {}
8+
}
9+
},
10+
"Loggers": {
11+
"Root": {
12+
"level": "ALL",
13+
"AppenderRef": {
14+
"ref": "CONSOLE"
15+
}
16+
}
17+
},
18+
// tag::filter[]
19+
"DynamicThresholdFilter": {
20+
"key": "loginId", // <3>
21+
"defaultThreshold": "ERROR",
22+
"KeyValuePair": [
23+
{ // <1>
24+
"key": "alice",
25+
"value": "DEBUG"
26+
},
27+
{ // <2>
28+
"key": "bob",
29+
"value": "INFO"
30+
}
31+
]
32+
}
33+
// end::filter[]
34+
}
35+
}

‎src/site/antora/modules/ROOT/examples/manual/filters/DynamicThresholdFilter.properties

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
monitorInterval = 10
2+
3+
appender.0.type = Console
4+
appender.0.name = CONSOLE
5+
appender.0.layout.type = JsonTemplateLayout
6+
7+
rootLogger.level = ALL
8+
rootLogger.appenderRef.0.ref = CONSOLE
9+
10+
# tag::filter[]
11+
filter.0.type = DynamicThresholdFilter
12+
filter.0.key = loginId
13+
# <3>
14+
filter.0.defaultThreshold = ERROR
15+
# <1>
16+
filter.0.kv0.type = KeyValuePair
17+
filter.0.kv0.key = alice
18+
filter.0.kv0.value = DEBUG
19+
# <2>
20+
filter.0.kv1.type = KeyValuePair
21+
filter.0.kv1.key = bob
22+
filter.0.kv1.value = INFO
23+
# end::filter[]

‎src/site/antora/modules/ROOT/examples/manual/filters/DynamicThresholdFilter.xml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<Configuration xmlns="https://logging.apache.org/xml/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="
4+
https://logging.apache.org/xml/ns
5+
https://logging.apache.org/xml/ns/log4j-config-2.xsd"
6+
monitorInterval="10">
7+
<Appenders>
8+
<Console name="CONSOLE">
9+
<JsonTemplateLayout/>
10+
</Console>
11+
</Appenders>
12+
<Loggers>
13+
<Root level="ALL">
14+
<AppenderRef ref="CONSOLE"/>
15+
</Root>
16+
</Loggers>
17+
<!-- tag::filter[] -->
18+
<DynamicThresholdFilter key="loginId"
19+
defaultThreshold="ERROR"> <!--3-->
20+
<KeyValuePair key="alice" value="DEBUG"/> <!--1-->
21+
<KeyValuePair key="bob" value="INFO"/> <!--2-->
22+
</DynamicThresholdFilter>
23+
<!-- end::filter[] -->
24+
</Configuration>

‎src/site/antora/modules/ROOT/examples/manual/filters/DynamicThresholdFilter.yaml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Configuration:
2+
monitorInterval: 10
3+
Appenders:
4+
Console:
5+
name: "CONSOLE"
6+
JsonTemplateLayout: { }
7+
Loggers:
8+
Root:
9+
level: "ALL"
10+
AppenderRef:
11+
ref: "CONSOLE"
12+
# tag::filter[]
13+
DynamicThresholdFilter:
14+
key: "loginId"
15+
defaultThreshold: "ERROR" # <3>
16+
KeyValuePair:
17+
- key: "alice" # <1>
18+
value: "DEBUG"
19+
- key: "bob" # <2>
20+
value: "INFO"
21+
# end::filter[]

‎src/site/antora/modules/ROOT/examples/manual/filters/MapFilter.json

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"Configuration": {
3+
"monitorInterval": 10,
4+
"Appenders": {
5+
"Console": {
6+
"name": "CONSOLE",
7+
"JsonTemplateLayout": {}
8+
}
9+
},
10+
"Loggers": {
11+
"Root": {
12+
"level": "ALL",
13+
"AppenderRef": {
14+
"ref": "CONSOLE"
15+
}
16+
}
17+
},
18+
// tag::filter[]
19+
"MapFilter": {
20+
"operator": "AND",
21+
"KeyValuePair": [
22+
{
23+
"key": "eventType",
24+
"value": "authentication"
25+
},
26+
{
27+
"key": "eventId",
28+
"value": "login"
29+
},
30+
{
31+
"key": "eventId",
32+
"value": "logout"
33+
}
34+
]
35+
}
36+
// end::filter[]
37+
}
38+
}

‎src/site/antora/modules/ROOT/examples/manual/filters/MapFilter.properties

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
monitorInterval = 10
2+
3+
appender.0.type = Console
4+
appender.0.name = CONSOLE
5+
appender.0.layout.type = JsonTemplateLayout
6+
7+
rootLogger.level = ALL
8+
rootLogger.appenderRef.0.ref = CONSOLE
9+
10+
# tag::filter[]
11+
filter.0.type = MapFilter
12+
filter.0.operator = AND
13+
14+
filter.0.kv0.type = KeyValuePair
15+
filter.0.kv0.key = eventType
16+
filter.0.kv0.value = authentication
17+
18+
filter.0.kv1.type = KeyValuePair
19+
filter.0.kv1.key = eventId
20+
filter.0.kv1.value = login
21+
22+
filter.0.kv2.type = KeyValuePair
23+
filter.0.kv2.key = eventId
24+
filter.0.kv2.value = logout
25+
# end::filter[]

‎src/site/antora/modules/ROOT/examples/manual/filters/MapFilter.xml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<Configuration xmlns="https://logging.apache.org/xml/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="
4+
https://logging.apache.org/xml/ns
5+
https://logging.apache.org/xml/ns/log4j-config-2.xsd"
6+
monitorInterval="10">
7+
<Appenders>
8+
<Console name="CONSOLE">
9+
<JsonTemplateLayout/>
10+
</Console>
11+
</Appenders>
12+
<Loggers>
13+
<Root level="ALL">
14+
<AppenderRef ref="CONSOLE"/>
15+
</Root>
16+
</Loggers>
17+
<!-- tag::filter[] -->
18+
<MapFilter operator="AND">
19+
<KeyValuePair key="eventType" value="authentication"/>
20+
<KeyValuePair key="eventId" value="login"/>
21+
<KeyValuePair key="eventId" value="logout"/>
22+
</MapFilter>
23+
<!-- end::filter[] -->
24+
</Configuration>

‎src/site/antora/modules/ROOT/examples/manual/filters/MapFilter.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Configuration:
2+
monitorInterval: 10
3+
Appenders:
4+
Console:
5+
name: "CONSOLE"
6+
JsonTemplateLayout: { }
7+
Loggers:
8+
Root:
9+
level: "ALL"
10+
AppenderRef:
11+
ref: "CONSOLE"
12+
# tag::filter[]
13+
MapFilter:
14+
operator: "AND"
15+
KeyValuePair:
16+
- key: "eventType"
17+
value: "authentication"
18+
- key: "eventId"
19+
value: "login"
20+
- key: "eventId"
21+
value: "logout"
22+
# end::filter[]

‎src/site/antora/modules/ROOT/examples/manual/filters/MutableContextMapFilter.json

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"Configuration": {
3+
"Appenders": {
4+
"Console": {
5+
"name": "CONSOLE",
6+
"JsonTemplateLayout": {}
7+
}
8+
},
9+
"Loggers": {
10+
"Root": {
11+
"level": "ALL",
12+
"AppenderRef": {
13+
"ref": "CONSOLE"
14+
}
15+
}
16+
},
17+
// tag::filter[]
18+
"MutableContextMapFilter": {
19+
"configLocation": "https://server.example/configs.json",
20+
"pollInterval": 10
21+
}
22+
// end::filter[]
23+
}
24+
}

‎src/site/antora/modules/ROOT/examples/manual/filters/MutableContextMapFilter.properties

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
appender.0.type = Console
2+
appender.0.name = CONSOLE
3+
appender.0.layout.type = JsonTemplateLayout
4+
5+
rootLogger.level = ALL
6+
rootLogger.appenderRef.0.ref = CONSOLE
7+
8+
# tag::filter[]
9+
filter.0.type = MutableContextMapFilter
10+
filter.0.configLocation = https://server.example/configs.json
11+
filter.0.pollInterval = 10
12+
# end::filter[]

0 commit comments

Comments
 (0)