This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 69dfbe4c7e23e46812fb23d32710315f579013fa Author: Piotr P. Karwasz <[email protected]> AuthorDate: Mon Jul 8 11:45:31 2024 +0200 Apply review suggestions (3) --- .../antora/modules/ROOT/pages/manual/filters.adoc | 78 ++++++++++++++++------ 1 file changed, 56 insertions(+), 22 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/filters.adoc b/src/site/antora/modules/ROOT/pages/manual/filters.adoc index fe91b0187e..7b62f89c24 100644 --- a/src/site/antora/modules/ROOT/pages/manual/filters.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/filters.adoc @@ -97,6 +97,11 @@ Otherwise, a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] is created and processing continues. ACCEPT:: A `LogEvent` is created and processing continues in the next stage. +[IMPORTANT] +==== +This is the only stage, which differentiates between an `ACCEPT` and `NEUTRAL` filter result. +==== + [TIP] ==== Filtering logging calls at this stage provides the best performance: @@ -187,7 +192,7 @@ of the appender reference. * the xref:manual/configuration.adoc#appenderrefs-elements-filters[appender reference filter] must return `ACCEPT` or `NEUTRAL`, [#appender-stage] -=== 4. `Appender` stage +=== 4. `Appender` stage (optional) [plantuml] .... @@ -209,10 +214,15 @@ end group @enduml .... -When log events reach an appender, +If the appender implements +link:../javadoc/log4j-core/org/apache/logging/log4j/core/filter/Filterable.html[`Filterable`] +an additional filtering stage is available. +When log events reach such an appender, the filter attached to an appender is evaluated and if the result is `DENY`, the log event is discarded. +All standard appenders implement `Filterable`. + [NOTE] ==== Some appenders like the @@ -230,7 +240,7 @@ Using the `level` property of appender references will give a better performance [WARNING] ==== -Configuring filters is a measure of last resort, +Configuring filters at this stage is a measure of last resort, since it adds a large overhead to disabled log events. You should rather configure the filtering in one of the previous stages. ==== @@ -272,7 +282,7 @@ include::example$manual/filters/filters.properties[lines=17..-1] ==== <1> Global filter -<2> Logger `level` attribute (it is skipped if the event matches the global filter) +<2> Logger `level` attribute. This setting is **ignored** unless the global filter returns `NEUTRAL`. <3> Filter of the `org.example` logger <4> Filter of the root logger (it is the parent of the `org.example` logger) <5> Appender reference `level` attribute @@ -377,7 +387,7 @@ Timestamp filters use the timestamp of log events to decide whether to accept th The `BurstFilter` limits the rate of log events. The rate limit is only applied to log events less severe than a configured log level. -Besides the common configuration attributes, +Besides the <<common-configuration-attributes,common configuration attributes>>, the `BurstFilter` supports the following parameters: .`BurstFilter` -- configuration attributes @@ -424,7 +434,7 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin The `TimeFilter` only matches log events emitted during a certain time of the day. -Besides the common configuration attributes, +Besides the <<common-configuration-attributes,common configuration attributes>>, the `TimeFilter` supports the following parameters: .`TimeFilter` -- configuration attributes @@ -500,7 +510,8 @@ The following filters allow you to filter log events based on their xref:manual/ The `LevelMatchFilter` matches log events that have exactly a certain log level. -Besides the common configuration attributes, the `LevelMatchFilter` supports the following parameter: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `LevelMatchFilter` supports the following parameter: .`LevelMatchFilter` -- configuration attributes [cols="1m,1,1,4"] @@ -516,9 +527,13 @@ Besides the common configuration attributes, the `LevelMatchFilter` supports the [TIP] ==== -If you wish to use a different log file for each log level, you can also use a +If you wish to use a different log file for each log level, you should also use a xref:manual/appenders.adoc#RoutingAppender[`Routing` appender] together with the xref:manual/lookups.adoc#EventLookup[`${event:Level}` lookup]. +Such a solution will ensure that: + +* you don't forget any log level (Log4j supports xref:manual/customloglevels.adoc[custom levels]). +* you don't need to configure an appender for each level separately. ==== xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-LevelMatchFilter[📖 Plugin reference for `LevelMatchFilter`] @@ -528,7 +543,8 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin The `LevelRangeFilter` matches log events with a log level within a configured range. -Besides the common configuration attributes, the `LevelRangeFilter` supports the following parameter: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `LevelRangeFilter` supports the following parameter: .`LevelRangeFilter` -- configuration attributes [cols="1m,1,1,4"] @@ -562,7 +578,8 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin The `ThresholdFilter` matches log events at least as severe as a configured level. -Besides the common configuration attributes, the `ThresholdFilter` supports the following parameter: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `ThresholdFilter` supports the following parameter: .`ThresholdFilter`—configuration attributes [cols="1m,1,1,4"] @@ -593,7 +610,8 @@ For each log event: xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-KeyValuePair[`KeyValuePair`] configuration elements to decide which level to apply. -Besides the common configuration attributes, the `DynamicThresholdFilter` supports the following parameters: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `DynamicThresholdFilter` supports the following parameters: .`DynamicThresholdFilter`—configuration attributes [cols="1m,1,1,4"] @@ -688,7 +706,8 @@ to filter log events. The `NoMarkerFilter` matches log events that do not have any markers. -This filter does not have any additional configuration attribute, except the common attributes. +This filter does not have any additional configuration attribute, +except the <<common-configuration-attributes,common configuration attributes>>. xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-NoMarkerFilter[📖 Plugin reference for `NoMarkerFilter`] @@ -697,7 +716,8 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin The `MarkerFilter` matches log events marked with a specific marker or **any** of its descendants. -Besides the common configuration attributes, the `MarkerFilter` supports the following parameter: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `MarkerFilter` supports the following parameter: .`MarkerFilter`—configuration attributes [cols="1m,1,1,4"] @@ -733,7 +753,8 @@ or link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html#getFormat()[`Message.getFormattedMessage()`]. It can be used with all kinds of `Message` implementations. -Besides the common configuration attributes, the `RegexFilter` supports the following parameters: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `RegexFilter` supports the following parameters: .`RegexFilter` -- configuration attributes [cols="1m,1,1,4"] @@ -759,9 +780,11 @@ is used. |=== -[NOTE] +[WARNING] ==== -This filter only matches if the **whole** log message matches the regular expression. +* This filter only matches if the **whole** log message matches the regular expression. + +* Setting `useRawMsg` to `false` decreases performance, since it forces the formatting of all log messages, including the disabled ones. ==== xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-RegexFilter[📖 Plugin reference for `RegexFilter`] @@ -771,7 +794,8 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin The `StringMatchFilter` matches a log event, if its message contains the given string. -Besides the common configuration attributes, the `StringMatchFilter` supports the following parameters: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `StringMatchFilter` supports the following parameters: .`StringMatchFilter`—configuration attributes [cols="1m,1,1,4"] @@ -787,6 +811,11 @@ Besides the common configuration attributes, the `StringMatchFilter` supports th |=== +[WARNING] +==== +This filter decreases performance, since it forces the formatting of all log messages, including the disabled ones. +==== + xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-StringMatchFilter[📖 Plugin reference for `StringMatchFilter`] [#map-filters] @@ -854,7 +883,8 @@ The `MapFilter` allows filtering based on the contents of all This filter encodes the <<configuration-map>> introduced above as a list of `KeyValuePair` elements. -Besides the common configuration attributes, the `MapFilter` supports the following parameters: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `MapFilter` supports the following parameters: .`MapFilter` -- configuration attributes [cols="1m,1,1,4"] @@ -974,7 +1004,8 @@ link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html#getForma |=== The `StructuredDataFilter` encodes the <<configuration-map>> introduced above as a list of -`KeyValuePair` and supports the following parameters, besides the common configuration attributes: +`KeyValuePair` and supports the following parameters, +besides the <<common-configuration-attributes,common configuration attributes>>: .`StructuredDataFilter`—configuration attributes [cols="1m,1,1,4"] @@ -1063,7 +1094,8 @@ of the log event instead of the log message. This filter also encodes the <<configuration-map>> introduced above as a list of `KeyValuePair` elements. -Besides the common configuration attributes, the `ContextMapFilter` supports the following parameters: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `ContextMapFilter` supports the following parameters: .`ContextMapFilter` -- configuration attributes [cols="1m,1,1,4"] @@ -1151,7 +1183,8 @@ to filter messages, but externalizes the <<configuration-map>>, so it can be kep This filter encodes the <<configuration-map>> as JSON. The configuration map must be stored in an **external** location and will be regularly polled for changes. -Besides the common configuration attributes, the `MutableContextMapFilter` supports the following parameters: +Besides the <<common-configuration-attributes,common configuration attributes>>, +the `MutableContextMapFilter` supports the following parameters: .`MutableContextMapFilter` -- configuration attributes [cols="1m,1,1,4"] @@ -1250,7 +1283,8 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin The `ScriptFilter` executes a script that must return `true` if the event matches and `false` otherwise. -Besides the common configuration attributes, it accepts a single nested element: +Besides the <<common-configuration-attributes,common configuration attributes>>, +it accepts a single nested element: .`ScriptFilter` -- nested elements [cols="3,1,4"]
