Package ch.qos.logback.classic.turbo

## Class DynamicThresholdFilter

- java.lang.Object
- - ch.qos.logback.core.spi.ContextAwareBase
  - - ch.qos.logback.classic.turbo.TurboFilter
    - - ch.qos.logback.classic.turbo.DynamicThresholdFilter

All Implemented Interfaces:
  `ContextAware`, `LifeCycle`

    public class DynamicThresholdFilter
    extends TurboFilter

This filter allows for efficient course grained filtering based on criteria such as product name or company name that would be associated with requests as they are processed.

This filter will allow you to associate threshold levels to a key put in the MDC. This key can be any value specified by the user. Furthermore, you can pass MDC value and level threshold associations, which are then looked up to find the level threshold to apply to the current logging request. If no level threshold could be found, then a 'default' value specified by the user is applied. We call this value 'levelAssociatedWithMDCValue'.

If 'levelAssociatedWithMDCValue' is higher or equal to the level of the current logger request, the `decide()` method returns the value of `onHigherOrEqual`, if it is lower then the value of `onLower` is returned. Both 'onHigherOrEqual' and 'onLower' can be set by the user. By default, 'onHigherOrEqual' is set to NEUTRAL and 'onLower' is set to DENY. Thus, if the current logger request's level is lower than 'levelAssociatedWithMDCValue', then the request is denied, and if it is higher or equal, then this filter decides NEUTRAL letting subsequent filters to make the decision on the fate of the logging request.

The example below illustrates how logging could be enabled for only individual users. In this example all events for logger names matching "com.mycompany" will be logged if they are for 'user1' and at a level higher than equals to DEBUG, and for 'user2' if they are at a level higher than or equal to TRACE, and for other users only if they are at level ERROR or higher. Events issued by loggers other than "com.mycompany" will only be logged if they are at level ERROR or higher since that is all the root logger allows.

     <configuration>
       <appender name="STDOUT"
                 class="ch.qos.logback.core.ConsoleAppender">
         <layout class="ch.qos.logback.classic.PatternLayout">
           <Pattern>TEST %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern>
         </layout>
       </appender>

       <turboFilter class="ch.qos.logback.classic.turbo.DynamicThresholdFilter">
         <Key>userId</Key>
         <DefaultThreshold>ERROR</DefaultThreshold>
         <MDCValueLevelPair>
           <value>user1</value>
           <level>DEBUG</level>
         </MDCValueLevelPair>
         <MDCValueLevelPair>
           <value>user2</value>
           <level>TRACE</level>
         </MDCValueLevelPair>
       </turboFilter>

       <logger name="com.mycompany" level="TRACE"/>

       <root level="ERROR" >
         <appender-ref ref="STDOUT" />
       </root>
     </configuration>

In the next configuration events from user1 and user2 will be logged regardless of the logger levels. Events for other users and records without a userid in the MDC will be logged if they are ERROR level messages. With this configuration, the root level is never checked since DynamicThresholdFilter will either accept or deny all records.

     <configuration>
       <appender name="STDOUT"
                 class="ch.qos.logback.core.ConsoleAppender">
         <layout class="ch.qos.logback.classic.PatternLayout">
            <Pattern>TEST %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern>
         </layout>
       </appender>

       <turboFilter class="ch.qos.logback.classic.turbo.DynamicThresholdFilter">
         <Key>userId</Key>
         <DefaultThreshold>ERROR</DefaultThreshold>
         <OnHigherOrEqual>ACCEPT</OnHigherOrEqual>
         <OnLower>DENY</OnLower>
         <MDCValueLevelPair>
           <value>user1</value>
           <level>TRACE</level>
         </MDCValueLevelPair>
         <MDCValueLevelPair>
           <value>user2</value>
           <level>TRACE</level>
         </MDCValueLevelPair>
       </turboFilter>

       <root level="DEBUG" >
         <appender-ref ref="STDOUT" />
       </root>
     </configuration>

Author:
  Ralph Goers, Ceki Gülcü

### Field Summary

### Fields inherited from class ch.qos.logback.core.spi.ContextAwareBase

`context`

### Constructor Summary

Constructors
`DynamicThresholdFilter()`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addMDCValueLevelPair​(MDCValueLevelPair mdcValueLevelPair)` Add a new MDCValuePair
`FilterReply` `decide​(org.slf4j.Marker marker, Logger logger, Level level, java.lang.String s, java.lang.Object[] objects, java.lang.Throwable throwable)` This method first finds the MDC value for 'key'.
`Level` `getDefaultThreshold()` Get the default threshold value when the MDC key is not set.
`java.lang.String` `getKey()` Get the MDC key whose value will be used as a level threshold
`FilterReply` `getOnHigherOrEqual()` Get the FilterReply when the effective level is higher or equal to the level of current logging request
`FilterReply` `getOnLower()` Get the FilterReply when the effective level is lower than the level of current logging request
`void` `setDefaultThreshold​(Level defaultThreshold)`
`void` `setKey​(java.lang.String key)`
`void` `setOnHigherOrEqual​(FilterReply onHigherOrEqual)`
`void` `setOnLower​(FilterReply onLower)`
`void` `start()`

### Methods inherited from class ch.qos.logback.classic.turbo.TurboFilter

`getName, isStarted, setName, stop`

### Methods inherited from class ch.qos.logback.core.spi.ContextAwareBase

`addError, addError, addInfo, addInfo, addStatus, addWarn, addWarn, getContext, getDeclaredOrigin, getStatusManager, setContext`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### DynamicThresholdFilter

    public DynamicThresholdFilter()

### Method Detail

#### getKey

    public java.lang.String getKey()

Get the MDC key whose value will be used as a level threshold

Returns:
  the name of the MDC key.

#### setKey

    public void setKey​(java.lang.String key)

See Also:
  `setKey(java.lang.String)`

#### getDefaultThreshold

    public Level getDefaultThreshold()

Get the default threshold value when the MDC key is not set.

Returns:
  the default threshold value in the absence of a set MDC key

#### setDefaultThreshold

    public void setDefaultThreshold​(Level defaultThreshold)

#### getOnHigherOrEqual

    public FilterReply getOnHigherOrEqual()

Get the FilterReply when the effective level is higher or equal to the level of current logging request

Returns:
  FilterReply

#### setOnHigherOrEqual

    public void setOnHigherOrEqual​(FilterReply onHigherOrEqual)

#### getOnLower

    public FilterReply getOnLower()

Get the FilterReply when the effective level is lower than the level of current logging request

Returns:
  FilterReply

#### setOnLower

    public void setOnLower​(FilterReply onLower)

#### addMDCValueLevelPair

    public void addMDCValueLevelPair​(MDCValueLevelPair mdcValueLevelPair)

Add a new MDCValuePair

#### start

    public void start()

Specified by:
  `start` in interface `LifeCycle`
Overrides:
  `start` in class `TurboFilter`

#### decide

    public FilterReply decide​(org.slf4j.Marker marker,
                              Logger logger,
                              Level level,
                              java.lang.String s,
                              java.lang.Object[] objects,
                              java.lang.Throwable throwable)

This method first finds the MDC value for 'key'. It then finds the level threshold associated with this MDC value from the list of MDCValueLevelPair passed to this filter. This value is stored in a variable called 'levelAssociatedWithMDCValue'. If it null, then it is set to the

Specified by:
  `decide` in class `TurboFilter`
Parameters:
  `marker` -
  `logger` -
  `level` -
  `s` -
  `objects` -
  `throwable` -
Returns:
  FilterReply - this filter's decision