Log4j2 Dynamic ThresholdFilter Example

Learn to filter the logging messages or events using the Log4j2 DynamicThresholdFilter. We will learn to configure DynamicThresholdFilter, understand how it matches the keys and uses the default threshold for log messages.

1. DynamicThresholdFilter

The DynamicThresholdFilter allows filtering log messages by log level based on specific attributes present in the org.apache.logging.log4j.ThreadContext Map.

We can configure the DynamicThresholdFilter in log4j2.xml under the element as follows:

<Configuration status="WARN" monitorInterval="30">

  <DynamicThresholdFilter key="USER_ROLE" defaultThreshold="ERROR" onMatch="ACCEPT" onMismatch="DENY">
    <KeyValuePair key="ADMIN" value="INFO"/>
    <KeyValuePair key="GUEST" value="DEBUG"/>
  </DynamicThresholdFilter>

  <Loggers>
    <Root level="INFO">
      <AppenderRef ref="console"/>
    </Root>
  </Loggers>

</Configuration>

To put a value in ThreadContext, use its put() method.

ThreadContext.put("USER_ROLE", "ADMIN");

2. How Thresholds are Resolved?

Suppose we have configured the USER_ROLE key in DynamicThresholdFilter as specified in the previous section. When a log message is executed in runtime, three kinds of scenarios can happen.

2.1. Key is Not Present in ThreadContext

If there is no key present in the context matching USER_ROLE then the threshold is decided by the ROOT logger’s level. The filter is effectively disabled in this case. In the following example, we are using <Root level="INFO">.

logger.info("User accessed the page without USER_ROLE = NONE");
logger.debug("User accessed the page without USER_ROLE = NONE");
logger.error("User accessed the page without USER_ROLE = NONE");

The program output.

[INFO ] 2022-09-27T17:39:48.620 DynamicThresholdFilterExample - User accessed the page without USER_ROLE = NONE
[ERROR] 2022-09-27T17:39:48.620 DynamicThresholdFilterExample - User accessed the page without USER_ROLE = NONE

2.2. Key is Present with a Matching Value

If the USER_ROLE key is present in the ThreadContext; and one of its values is listed on the KeyValuePair array then the threshold is decided by its value attribute.

In the following example, we have set the threshold INFO for ADMIN users, and DEBUG for GUEST users.

ThreadContext.put("USER_ROLE", "ADMIN");

logger.info("User accessed the page with USER_ROLE = ADMIN");
logger.debug("User accessed the page with USER_ROLE = ADMIN");
logger.error("User accessed the page without USER_ROLE = ADMIN");

ThreadContext.put("USER_ROLE", "GUEST");

logger.info("User accessed the page with USER_ROLE = GUEST");
logger.debug("User accessed the page with USER_ROLE = GUEST");
logger.error("User accessed the page without USER_ROLE = GUEST");

The program output.

[INFO ] 2022-09-27T17:46:04.034 DynamicThresholdFilterExample - User accessed the page with USER_ROLE = ADMIN
[ERROR] 2022-09-27T17:46:04.034 DynamicThresholdFilterExample - User accessed the page with USER_ROLE = ADMIN

[INFO ] 2022-09-27T17:46:04.034 DynamicThresholdFilterExample - User accessed the page with USER_ROLE = GUEST
[DEBUG] 2022-09-27T17:46:04.034 DynamicThresholdFilterExample - User accessed the page with USER_ROLE = GUEST
[ERROR] 2022-09-27T17:46:04.034 DynamicThresholdFilterExample - User accessed the page with USER_ROLE = GUEST

2.3. Key is Present without Any Match

If the USER_ROLE key is present in the ThreadContext; and there is no matching value in the KeyValuePair array then the threshold is decided by defaultThreshold value. In the following example, we are using defaultThreshold="ERROR".

ThreadContext.put("USER_ROLE", "UNKNOWN");

logger.info("User accessed the page with USER_ROLE = UNKNOWN");
logger.debug("User accessed the page with USER_ROLE = UNKNOWN");
logger.error("User accessed the page with USER_ROLE = UNKNOWN");

The program output.

[ERROR] 2022-09-27T17:46:40.139 DynamicThresholdFilterExample - User accessed the page with USER_ROLE = UNKNOWN

3. Conclusion

In this short log4j2 tutorial, we learned to configure and use the DynamicThresholdFilter. We learned how to match thresholds and write the filtered messages in log files using various combinations.

Happy Learning !!

Sourcecode on Github