Set the default minLevel/maxLevel of LevelRangeFilter to OFF/ALL (#1503)

Author: vy

log4j-core-test/src/test/java/org/apache/logging/log4j/core/filter/LevelRangeFilterTest.java

@@ -17,41 +17,77 @@
 package org.apache.logging.log4j.core.filter;
 
 import org.apache.logging.log4j.Level;
-import org.apache.logging.log4j.core.Filter;
+import org.apache.logging.log4j.core.Filter.Result;
 import org.apache.logging.log4j.core.LogEvent;
 import org.apache.logging.log4j.core.impl.Log4jLogEvent;
 import org.apache.logging.log4j.message.SimpleMessage;
+import org.assertj.core.api.SoftAssertions;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.apache.logging.log4j.core.filter.LevelRangeFilter.createFilter;
+import static org.assertj.core.api.Assertions.assertThat;
 
-public class LevelRangeFilterTest {
+class LevelRangeFilterTest {
 
     @Test
-    public void testLevels() {
-        final LevelRangeFilter filter = LevelRangeFilter.createFilter(Level.ERROR, Level.INFO, null, null);
-        filter.start();
-        assertTrue(filter.isStarted());
-        assertSame(Filter.Result.DENY, filter.filter(null, Level.DEBUG, null, (Object) null, (Throwable) null));
-        assertSame(Filter.Result.NEUTRAL, filter.filter(null, Level.ERROR, null, (Object) null, (Throwable) null));
-        LogEvent event = Log4jLogEvent.newBuilder() //
-                .setLevel(Level.DEBUG) //
-                .setMessage(new SimpleMessage("Test")) //
-                .build();
-        assertSame(Filter.Result.DENY, filter.filter(event));
-        event = Log4jLogEvent.newBuilder() //
-                .setLevel(Level.ERROR) //
-                .setMessage(new SimpleMessage("Test")) //
-                .build();
-        assertSame(Filter.Result.NEUTRAL, filter.filter(event));
+    void verify_constants() {
+        assertThat(LevelRangeFilter.DEFAULT_MIN_LEVEL).isEqualTo(Level.OFF);
+        assertThat(LevelRangeFilter.DEFAULT_MAX_LEVEL).isEqualTo(Level.ALL);
+        assertThat(LevelRangeFilter.DEFAULT_ON_MATCH).isEqualTo(Result.NEUTRAL);
+        assertThat(LevelRangeFilter.DEFAULT_ON_MISMATCH).isEqualTo(Result.DENY);
+    }
+
+    @Test
+    void verify_defaults() {
+        final LevelRangeFilter filter = createFilter(null, null, null, null);
+        assertThat(filter.getMinLevel()).isEqualTo(Level.OFF);
+        assertThat(filter.getMaxLevel()).isEqualTo(Level.ALL);
+        assertThat(filter.getOnMatch()).isEqualTo(Result.NEUTRAL);
+        assertThat(filter.getOnMismatch()).isEqualTo(Result.DENY);
+    }
+
+    @ParameterizedTest
+    @MethodSource("org.apache.logging.log4j.Level#values")
+    void default_should_match_all_levels(final Level level) {
+        final LevelRangeFilter filter = createFilter(null, null, null, null);
+        assertThat(filter.filter(createEvent(level))).isEqualTo(LevelRangeFilter.DEFAULT_ON_MATCH);
     }
 
     @Test
-    public void testMinimumOnlyLevel() {
-        final LevelRangeFilter filter = LevelRangeFilter.createFilter(Level.ERROR, null, null, null);
-        filter.start();
-        assertTrue(filter.isStarted());
-        assertSame(Filter.Result.NEUTRAL, filter.filter(null, Level.ERROR, null, (Object) null, (Throwable) null));
+    void overriding_defaults_should_be_effective() {
+
+        // Choose a configuration
+        final Level minLevel = Level.ERROR;
+        final Level maxLevel = Level.WARN;
+        final Result onMatch = Result.ACCEPT;
+        final Result onMismatch = Result.NEUTRAL;
+
+        // Verify we deviate from the defaults
+        assertThat(minLevel).isNotEqualTo(LevelRangeFilter.DEFAULT_MIN_LEVEL);
+        assertThat(maxLevel).isNotEqualTo(LevelRangeFilter.DEFAULT_MAX_LEVEL);
+        assertThat(onMatch).isNotEqualTo(LevelRangeFilter.DEFAULT_ON_MATCH);
+        assertThat(onMismatch).isNotEqualTo(LevelRangeFilter.DEFAULT_ON_MISMATCH);
+
+        // Verify the filtering
+        final LevelRangeFilter filter = createFilter(minLevel, maxLevel, onMatch, onMismatch);
+        final SoftAssertions assertions = new SoftAssertions();
+        for (final Level level : Level.values()) {
+            final Result expectedResult = level.isInRange(minLevel, maxLevel) ? onMatch : onMismatch;
+            assertions.assertThat(filter.filter(createEvent(level))).isEqualTo(expectedResult);
+        }
+        assertions.assertAll();
+
+    }
+
+    private static LogEvent createEvent(final Level level) {
+        final SimpleMessage message = new SimpleMessage("test message at level " + level);
+        return Log4jLogEvent
+                .newBuilder()
+                .setLevel(level)
+                .setMessage(message)
+                .build();
     }
 
 }

log4j-core/src/main/java/org/apache/logging/log4j/core/filter/LevelRangeFilter.java

@@ -29,13 +29,12 @@
 import org.apache.logging.log4j.util.PerformanceSensitive;
 
 /**
- * This filter returns the {@code onMatch} result if the level in the {@code LogEvent} is in the range of the configured
- * min and max levels, otherwise it returns {@code onMismatch} value . For example, if the filter is configured with
- * {@link Level#ERROR} and {@link Level#INFO} and the LogEvent contains {@link Level#WARN} then the onMatch value will
- * be returned since {@link Level#WARN WARN} events are in between {@link Level#ERROR ERROR} and {@link Level#INFO
- * INFO}.
+ * This filter returns the {@link #onMatch} result if the level of the {@link LogEvent} is in the range of the configured {@link #minLevel} and {@link #maxLevel} values, otherwise it returns the {@link #onMismatch} result.
+ * The default values for {@link #minLevel} and {@link #maxLevel} are set to {@link Level#OFF} and {@link Level#ALL}, respectively.
+ * The default values for {@link #onMatch} and {@link #onMismatch} are set to {@link Result#NEUTRAL} and {@link Result#DENY}, respectively.
  * <p>
- * The default Levels are both {@link Level#ERROR ERROR}.
+ * The levels get compared by their associated integral values; {@link Level#OFF} has an integral value of 0, {@link Level#FATAL} 100, {@link Level#ERROR} 200, and so on.
+ * For example, if the filter is configured with {@link #maxLevel} set to {@link Level#INFO}, the filter will return {@link #onMismatch} result for {@link LogEvent}s of level with higher integral values; {@link Level#DEBUG}, {@link Level#TRACE}, etc.
  * </p>
  */
 @Configurable(elementType = Filter.ELEMENT_TYPE, printObject = true)
@@ -44,33 +43,49 @@
 public final class LevelRangeFilter extends AbstractFilter {
 
     /**
-     * Creates a ThresholdFilter.
+     * The default minimum level threshold.
+     */
+    public static final Level DEFAULT_MIN_LEVEL = Level.OFF;
+
+    /**
+     * THe default maximum level threshold.
+     */
+    public static final Level DEFAULT_MAX_LEVEL = Level.ALL;
+
+    /**
+     * The default result on a match.
+     */
+    public static final Result DEFAULT_ON_MATCH = Result.NEUTRAL;
+
+    /**
+     * The default result on a mismatch.
+     */
+    public static final Result DEFAULT_ON_MISMATCH = Result.DENY;
+
+    /**
+     * Creates an instance with the provided properties.
      *
-     * @param minLevel
-     *            The minimum log Level.
-     * @param maxLevel
-     *            The maximum log Level.
-     * @param match
-     *            The action to take on a match.
-     * @param mismatch
-     *            The action to take on a mismatch.
-     * @return The created ThresholdFilter.
+     * @param minLevel the minimum level threshold
+     * @param maxLevel the maximum level threshold
+     * @param onMatch the result to return on a match
+     * @param onMismatch the result to return on a mismatch
+     * @return a new instance
      */
-    // TODO Consider refactoring to use AbstractFilter.AbstractFilterBuilder
     @PluginFactory
     public static LevelRangeFilter createFilter(
             // @formatter:off
             @PluginAttribute final Level minLevel,
             @PluginAttribute final Level maxLevel,
-            @PluginAttribute final Result match,
-            @PluginAttribute final Result mismatch) {
+            @PluginAttribute final Result onMatch,
+            @PluginAttribute final Result onMismatch) {
             // @formatter:on
-        final Level actualMinLevel = minLevel == null ? Level.ERROR : minLevel;
-        final Level actualMaxLevel = maxLevel == null ? Level.ERROR : maxLevel;
-        final Result onMatch = match == null ? Result.NEUTRAL : match;
-        final Result onMismatch = mismatch == null ? Result.DENY : mismatch;
-        return new LevelRangeFilter(actualMinLevel, actualMaxLevel, onMatch, onMismatch);
+        final Level effectiveMinLevel = minLevel == null ? DEFAULT_MIN_LEVEL : minLevel;
+        final Level effectiveMaxLevel = maxLevel == null ? DEFAULT_MAX_LEVEL : maxLevel;
+        final Result effectiveOnMatch = onMatch == null ? DEFAULT_ON_MATCH : onMatch;
+        final Result effectiveOnMismatch = onMismatch == null ? DEFAULT_ON_MISMATCH : onMismatch;
+        return new LevelRangeFilter(effectiveMinLevel, effectiveMaxLevel, effectiveOnMatch, effectiveOnMismatch);
     }
+
     private final Level maxLevel;
 
     private final Level minLevel;
@@ -82,7 +97,7 @@ private LevelRangeFilter(final Level minLevel, final Level maxLevel, final Resul
     }
 
     private Result filter(final Level level) {
-        return level.isInRange(this.minLevel, this.maxLevel) ? onMatch : onMismatch;
+        return level.isInRange(minLevel, maxLevel) ? onMatch : onMismatch;
     }
 
     @Override
@@ -177,13 +192,23 @@ public Result filter(final Logger logger, final Level level, final Marker marker
         return filter(level);
     }
 
+    /**
+     * @return the minimum level threshold
+     */
     public Level getMinLevel() {
         return minLevel;
     }
 
+    /**
+     * @return the maximum level threshold
+     */
+    public Level getMaxLevel() {
+        return maxLevel;
+    }
+
     @Override
     public String toString() {
-        return minLevel.toString();
+        return String.format("[%s,%s]", minLevel, maxLevel);
     }
 
 }

src/site/asciidoc/manual/filters.adoc

@@ -16,6 +16,7 @@
 ////
 = Filters
 Ralph Goers <[email protected]>
+Volkan Yazıcı <[email protected]>
 
 ++++
 <link rel="stylesheet" type="text/css" href="../css/tables.css">
@@ -224,6 +225,55 @@ Here is a sample configuration containing the DynamicThresholdFilter:
 </Configuration>
 ----
 
+[#LevelRangeFilter]
+== LevelRangeFilter
+
+`LevelRangeFilter` allows filtering against a level range, where levels get compared by their associated integral values; `OFF` has an integral value of 0, `FATAL` 100, `ERROR` 200, and so on.
+
+.`LevelRangeFilter` parameters
+[cols="1m,1m,4"]
+|===
+|Parameter Name |Type |Description
+
+|minLevel
+|Level
+|the minimum level threshold (defaults to `OFF`, which has an integral value of 0)
+
+|maxLevel
+|Level
+|the maximum level threshold (defaults to `ALL`, which has an integral value of `Integer.MAX_VALUE`)
+
+|onMatch
+|Filter.Result
+|the result to return on a match, where allowed values are `ACCEPT`, `DENY`, or `NEUTRAL` (default)
+
+|onMismatch
+|Filter.Result
+|the result to return on a mismatch, where allowed values are `ACCEPT`, `DENY` (default), or `NEUTRAL`
+|===
+
+In the following example configuration, a `LevelRangeFilter` is configured with `maxLevel` set to `INFO`.
+The filter will return `onMismatch` result (i.e., `DENY`, the default) for log events of level with higher integral values than `INFO`; i.e., `DEBUG`, `TRACE`, etc.
+
+.Example configuration using `LevelRangeFilter`
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="WARN" name="MyApp">
+  <Appenders>
+    <Console name="STDOUT">
+      <LevelRangeFilter maxLevel="INFO"/>
+      <PatternLayout pattern="%d %p %c{1.} [%t] %m%n"/>
+    </Console>
+  </Appenders>
+  <Loggers>
+    <Root level="ERROR">
+      <AppenderRef ref="STDOUT"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
 [#MapFilter]
 == MapFilter