ppkarwasz commented on code in PR #2717: URL: https://github.com/apache/logging-log4j2/pull/2717#discussion_r1668270521
########## src/site/antora/modules/ROOT/pages/manual/filters.adoc: ########## @@ -17,1038 +17,1407 @@ [id=filters] = Filters +:stem: -Log4j supports filtering of log events at each level of the logging pipeline using two features: +Filters are Log4j plugins that evaluate the parameters of a logging call or a log event and return one of three results: -* the `level` attributes that can be set on loggers and appender references, -* filter components that can be attached to loggers, appenders, appender references or the global configuration object. +ACCEPT:: The log event is accepted by the filter and goes to the next stage of the logging pipeline. -Filters evaluate the parameters of a logging call (context-wide filter) or a log event and return one of three results: +DENY:: The log event is unconditionally dropped. -ACCEPT:: The log event is accepted by the filter and goes to the next stage of the logging pipeline, +NEUTRAL:: Log4j behaves as if the filter was not present. -DENY:: The log event is unconditionally dropped, +Filters can be used at each level of the +xref:manual/architecture.adoc#architecture-diagram[logging pipeline]: -NEUTRAL:: Log4j behaves as if the filter was not present. +* the global configuration element can contain a xref:manual/configuration.adoc#global-filters[global filter]. +* each xref:manual/configuration.adoc#configuring-loggers[logger] configuration element can contain a xref:manual/configuration.adoc#logger-elements-filters[logger filter]. +* each xref:manual/configuration.adoc#configuring-appenderrefs[appender reference] configuration element can contain an xref:manual/configuration.adoc#appenderrefs-elements-filters[appender reference filter]. +* each xref:manual/appenders.adoc[appender] configuration element can contain an xref:manual/appenders.adoc[appender filter]. + +Additionally, the following configuration attributes take part in the filtering process: + +* the xref:manual/configuration.adoc#logger-attributes-level[`level` attribute] of logger configuration elements. +* the xref:manual/configuration.adoc#appenderref-attributes-level[`level` attribute] of appender reference configuration elements. + +[#filtering-process] +== Filtering process + +Due to the interaction of many elements, +the filtering process in Log4j is quite complex and can be divided in four stages: + +. <<logger-stage,`Logger` stage>> +. <<logger-config-stage,`LoggerConfig` stage>> +. <<appender-control-stage,`AppenderControl` stage>> +. <<appender-stage,`Appender` stage>> + +[IMPORTANT] +==== +For performance reasons, log events should be filtered at the earliest possible stage. +This reduces the cost of disabled log events: +e.g., log event creation, population of context data, formatting, transfer through an asynchronous barrier. +==== + +[#logger-stage] +=== 1. `Logger` stage + +[plantuml] +.... +@startuml +start +group Logger + +:A Logger method; + +switch (Apply global filter) +case (DENY) + #pink:Discard; + detach +case (ACCEPT) +case (NEUTRAL) + if (Is less severe than logger level?) then (yes) + #pink:Discard; + detach + else (no) + ' The label improves spacing + label a1 + endif +endswitch +end group +:Create LogEvent; +stop +.... + +The parameters of the logging call are passed to the global filter. +If the global filter returns: + +DENY:: The log message is immediately discarded. +NEUTRAL:: If the level of the log message is less severe than the configured logger threshold, the message is discarded. +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. + +[TIP] +==== +Filtering logging calls at this stage provides the best performance: + +* this stage precedes the creation of log events, therefore operations like the +xref:manual/thread-context.adoc[injection of context data], +xref:manual/layouts.adoc#LocationInformation[computation of location information] +will not be performed for disabled log statements. +* this stage precedes the asynchronous calls performed by either +xref:manual/async.adoc[asynchronous loggers] +or +xref:manual/appenders.adoc#AsyncAppender[asynchronous appenders]. +==== + +[#logger-config-stage] +=== 2. `LoggerConfig` stage + +[plantuml] +.... +@startuml +start +group LoggerConfig +repeat + +:LoggerConfig.log(); + +if (Apply logger filter) then (DENY) + #pink:Discard; + detach +else (not DENY) + ' The label improves spacing + label a1 +endif +repeat while (Go to parent logger?) is (yes) +-> no; +end group +stop +@enduml +.... + +In this stage, log events are evaluated by all the +xref:manual/configuration.adoc#logger-elements-filters[logger filters] +that stand on the path from the logger to an appender. +Due to the +xref:manual/configuration.adoc#logger-attributes-additivity[additivity of logger configurations], +this means that a log event must also pass the filters of all the parent loggers, +until it reaches the logger that references the chosen appender. + +[#appender-control-stage] +=== 3. `AppenderControl` stage + +[plantuml] +.... +@startuml +!pragma useVerticalIf on +start +group AppenderControl + +:AppenderControl.callAppender(); + +if (Is less severe then appender reference level?) then (yes) + #pink:Discard; + detach +else (no) + ' The label improves spacing + label a2 +endif +if (Apply appender reference filter) then (DENY) + #pink:Discard; + detach +else (not DENY) + ' The label improves spacing + label a1 +endif +end group +stop +@enduml +.... + +To pass this stage, log events must satisfy both conditions: + +* the log event must be at least as severe as the +xref:manual/configuration.adoc#appenderref-attributes-level[`level` attribute] +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 + +[plantuml] +.... +@startuml +start +group Appender + +:Appender.append(); Review Comment: Fixed in 2cde19bec61964536b33d11635712c9ae8d21fd8 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
