Revamp the Lookups page

ppkarwasz · ppkarwasz · commit 151f7a6a902e · 2024-07-11T13:14:12.000+02:00
We revamp the `Lookups` page by: * Adding information on different evaluation contexts supported by lookups. * Adding a cheatsheet on which lookup is available in which evaluation context. E.g., using `$${sys:something}` on a per-event level is a major performance waster. * Removing the description of the broken `jvmrunargs` lookup (see #2726). * Improving the description of the `main` lookup by providing a code example that does not fail if the user switches logging implementations. * Shortening and improving the description of other lookups.
diff --git a/log4j-core-test/src/test/java/org/apache/logging/log4j/core/lookup/MainInputArgumentsJmxLookupTest.java b/log4j-core-test/src/test/java/org/apache/logging/log4j/core/lookup/MainInputArgumentsJmxLookupTest.java
@@ -18,6 +18,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertNull;
 
+import java.util.Map;
 import org.junit.jupiter.api.Test;
 
 /**
@@ -36,15 +37,40 @@ public static void main(final String[] args) {
     @Test
     public void testMap() {
         final JmxRuntimeInputArgumentsLookup lookup = JmxRuntimeInputArgumentsLookup.JMX_SINGLETON;
-        assertNull(lookup.lookup(null));
-        assertNull(lookup.lookup("X"));
-        assertNull(lookup.lookup("foo.txt"));
+        String result2 = null;
+        if (null != null) {
+            final Map<String, String> map2 = lookup.getMap();
+            result2 = map2 == null ? null : map2.get(null);
+        }
+        assertNull(result2);
+        String result1 = null;
+        if ("X" != null) {
+            final Map<String, String> map1 = lookup.getMap();
+            result1 = map1 == null ? null : map1.get("X");
+        }
+        assertNull(result1);
+        String result = null;
+        if ("foo.txt" != null) {
+            final Map<String, String> map = lookup.getMap();
+            result = map == null ? null : map.get("foo.txt");
+        }
+        assertNull(result);
     }
 
     public void callFromMain() {
         final JmxRuntimeInputArgumentsLookup lookup = JmxRuntimeInputArgumentsLookup.JMX_SINGLETON;
-        assertNull(lookup.lookup(null));
-        assertNull(lookup.lookup("X"));
+        String result1 = null;
+        if (null != null) {
+            final Map<String, String> map1 = lookup.getMap();
+            result1 = map1 == null ? null : map1.get(null);
+        }
+        assertNull(result1);
+        String result = null;
+        if ("X" != null) {
+            final Map<String, String> map = lookup.getMap();
+            result = map == null ? null : map.get("X");
+        }
+        assertNull(result);
         // Eclipse adds -Dfile.encoding=Cp1252
         // assertEquals("--file", lookup.lookup("0"));
         // assertEquals("foo.txt", lookup.lookup("1"));
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/AbstractLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/AbstractLookup.java
@@ -16,6 +16,8 @@
  */
 package org.apache.logging.log4j.core.lookup;
 
+import org.apache.logging.log4j.core.LogEvent;
+
 /**
  * A default lookup for others to extend.
  *
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/EnvironmentLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/EnvironmentLookup.java
@@ -27,12 +27,12 @@ public class EnvironmentLookup extends AbstractLookup {
 
     /**
      * Looks up the value of the environment variable.
-     * @param event The current LogEvent (is ignored by this StrLookup).
+     *
      * @param key  the key to be looked up, may be null
      * @return The value of the environment variable.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         return System.getenv(key);
     }
 }
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JavaLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JavaLookup.java
@@ -90,14 +90,12 @@ public String getVirtualMachine() {
     /**
      * Looks up the value of the environment variable.
      *
-     * @param event
-     *        The current LogEvent (is ignored by this StrLookup).
      * @param key
      *        the key to be looked up, may be null
      * @return The value of the environment variable.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         switch (key) {
             case "version":
                 return "Java version " + getSystemProperty("java.version");
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JmxRuntimeInputArgumentsLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JmxRuntimeInputArgumentsLookup.java
@@ -48,12 +48,7 @@ public JmxRuntimeInputArgumentsLookup(final Map<String, String> map) {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
-        return lookup(key);
-    }
-
-    @Override
-    public String lookup(final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (key == null) {
             return null;
         }
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JndiLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JndiLookup.java
@@ -50,12 +50,11 @@ public JndiLookup() {
     /**
      * Looks up the value of the JNDI resource.
      *
-     * @param event The current LogEvent (is ignored by this StrLookup).
      * @param key the JNDI resource name to be looked up, may be null
      * @return The String value of the JNDI resource.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (key == null) {
             return null;
         }
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/Log4jLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/Log4jLookup.java
@@ -53,7 +53,7 @@ private static URI getParent(final URI uri) throws URISyntaxException {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (configuration != null) {
             final ConfigurationSource configSrc = configuration.getConfigurationSource();
             final File file = configSrc.getFile();
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/LowerLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/LowerLookup.java
@@ -25,26 +25,16 @@
  * Converts values to lower case. The passed in "key" should be the value of another lookup.
  */
 @Plugin(name = "lower", category = StrLookup.CATEGORY)
-public class LowerLookup implements StrLookup {
+public class LowerLookup extends AbstractLookup {
 
     /**
      * Converts the "key" to lower case.
+     *
      * @param key  the key to be looked up, may be null
      * @return The value associated with the key.
      */
     @Override
-    public String lookup(final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         return key != null ? toRootLowerCase(key) : null;
     }
-
-    /**
-     * Converts the "key" to lower case.
-     * @param event The current LogEvent.
-     * @param key  the key to be looked up, may be null
-     * @return The value associated with the key.
-     */
-    @Override
-    public String lookup(final LogEvent event, final String key) {
-        return lookup(key);
-    }
 }
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/MainMapLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/MainMapLookup.java
@@ -82,7 +82,7 @@ public static void setMainArguments(final String... args) {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         return MAIN_SINGLETON.getMap().get(key);
     }
 
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/ResourceBundleLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/ResourceBundleLookup.java
@@ -39,14 +39,12 @@ public class ResourceBundleLookup extends AbstractLookup {
      *
      * For example: "com.domain.messages:MyKey".
      *
-     * @param event
-     *            The current LogEvent.
      * @param key
      *            the key to be looked up, may be null
      * @return The value associated with the key.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (key == null) {
             return null;
         }
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java
@@ -24,7 +24,7 @@
  * Looks up keys from {@link org.apache.logging.log4j.message.StructuredDataMessage} log messages.
  */
 @Plugin(name = "sd", category = StrLookup.CATEGORY)
-public class StructuredDataLookup implements StrLookup {
+public class StructuredDataLookup extends AbstractLookup {
 
     /**
      * Key to obtain the id of a structured message.
@@ -36,16 +36,6 @@ public class StructuredDataLookup implements StrLookup {
      */
     public static final String TYPE_KEY = "type";
 
-    /**
-     * Returns {@code null}. This Lookup plugin does not make sense outside the context of a LogEvent.
-     * @param key  The key to be looked up, may be null.
-     * @return {@code null}
-     */
-    @Override
-    public String lookup(final String key) {
-        return null;
-    }
-
     /**
      * Looks up the value for the key using the data in the LogEvent.
      * @param event The current LogEvent.
diff --git a/log4j-docker/src/main/java/org/apache/logging/log4j/docker/DockerLookup.java b/log4j-docker/src/main/java/org/apache/logging/log4j/docker/DockerLookup.java
@@ -95,7 +95,7 @@ public DockerLookup() {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (container == null) {
             return null;
         }
diff --git a/log4j-jakarta-web/src/main/java/org/apache/logging/log4j/web/WebLookup.java b/log4j-jakarta-web/src/main/java/org/apache/logging/log4j/web/WebLookup.java
@@ -30,7 +30,7 @@ public class WebLookup extends AbstractLookup {
     private static final String INIT_PARAM_PREFIX = "initParam.";
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         final ServletContext ctx = WebLoggerContextUtils.getServletContext();
         if (ctx == null) {
             return null;
diff --git a/src/site/antora/modules/ROOT/examples/manual/lookups/MainArgsExample.java b/src/site/antora/modules/ROOT/examples/manual/lookups/MainArgsExample.java
@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+public final class MainArgsExample implements Runnable {
+
+    // tag::usage[]
+    private final Logger logger = LogManager.getLogger(); // <1>
+
+    public static void main(final String[] args) {
+        try { // <2>
+            Class.forName("org.apache.logging.log4j.core.lookup.MainMapLookup")
+                    .getDeclaredMethod("setMainArguments", String[].class)
+                    .invoke(null, (Object) args);
+        } catch (final ReflectiveOperationException e) {
+            // Log4j Core is not used.
+        }
+        new MainArgsExample().run();
+    }
+    // end::usage[]
+
+    @Override
+    public void run() {
+        logger.info("Hello `main` lookup!");
+    }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.json b/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.json
@@ -0,0 +1,31 @@
+{
+  "Configuration": {
+    "Properties": {
+      "Property": [ // <1>
+        {
+          "name": "--logfile",
+          "value": "logs/app.log"
+        },
+        {
+          "name": "--loglevel",
+          "value": "INFO"
+        }
+      ]
+    },
+    "Appenders": {
+      "File": {
+        "fileName": "${main:\\--logfile}", // <2>
+        "name": "FILE",
+        "JsonTemplateLayout": {}
+      }
+    },
+    "Loggers": {
+      "Root": {
+        "level": "${main:\\--loglevel", // <2>
+        "AppenderRef": {
+          "ref": "FILE"
+        }
+      }
+    }
+  }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.properties b/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.properties
@@ -0,0 +1,29 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+##
+# <1>
+property.--logfile = logs/app.log
+property.--loglevel = INFO
+
+appender.0.type = File
+# <2>
+appender.0.fileName = ${main:\\--logfile}
+appender.0.name = FILE
+
+# <2>
+rootLogger.level = ${main:\\--loglevel}
+rootLogger.appenderRef.0.ref = FILE
diff --git a/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.xml b/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements.  See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to you under the Apache License, Version 2.0
+  ~ (the "License"); you may not use this file except in compliance with
+  ~ the License.  You may obtain a copy of the License at
+  ~
+  ~      http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+<Configuration xmlns="https://logging.apache.org/xml/ns"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="
+                   https://logging.apache.org/xml/ns
+                   https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+  <Properties> <!--1-->
+    <Property name="--logfile" value="logs/app.log"/>
+    <Property name="--loglevel" value="INFO"/>
+  </Properties>
+  <Appenders>
+    <File fileName="${main:\--logfile}"
+          name="FILE"/> <!--2-->
+  </Appenders>
+  <Loggers>
+    <Root level="${main:\--loglevel}"> <!--2-->
+      <AppenderRef ref="FILE"/>
+    </Root>
+  </Loggers>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.yaml b/src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.yaml
diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
diff --git a/src/site/antora/modules/ROOT/pages/manual/lookups.adoc b/src/site/antora/modules/ROOT/pages/manual/lookups.adoc
diff --git a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc
diff --git a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-docker.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-docker.adoc
diff --git a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-spring-boot.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-spring-boot.adoc

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,8 @@`
`16`	`16`	`*/`
`17`	`17`	`package org.apache.logging.log4j.core.lookup;`
`18`	`18`
	`19`	`+import org.apache.logging.log4j.core.LogEvent;`
	`20`	`+`
`19`	`21`	`/**`
`20`	`22`	`* A default lookup for others to extend.`
`21`	`23`	`*`
Original file line number	Diff line number	Diff line change
`@@ -27,12 +27,12 @@ public class EnvironmentLookup extends AbstractLookup {`
`27`	`27`
`28`	`28`	`/**`
`29`	`29`	`* Looks up the value of the environment variable.`
`30`		`- * @param event The current LogEvent (is ignored by this StrLookup).`
	`30`	`+ *`
`31`	`31`	`* @param key the key to be looked up, may be null`
`32`	`32`	`* @return The value of the environment variable.`
`33`	`33`	`*/`
`34`	`34`	`@Override`
`35`		`- public String lookup(final LogEvent event, final String key) {`
	`35`	`+ public String lookup(final LogEvent ignored, final String key) {`
`36`	`36`	`return System.getenv(key);`
`37`	`37`	`}`
`38`	`38`	`}`
Original file line number	Diff line number	Diff line change
`@@ -48,12 +48,7 @@ public JmxRuntimeInputArgumentsLookup(final Map<String, String> map) {`
`48`	`48`	`}`
`49`	`49`
`50`	`50`	`@Override`
`51`		`- public String lookup(final LogEvent event, final String key) {`
`52`		`- return lookup(key);`
`53`		`- }`
`54`		`-`
`55`		`- @Override`
`56`		`- public String lookup(final String key) {`
	`51`	`+ public String lookup(final LogEvent ignored, final String key) {`
`57`	`52`	`if (key == null) {`
`58`	`53`	`return null;`
`59`	`54`	`}`
Original file line number	Diff line number	Diff line change
`@@ -50,12 +50,11 @@ public JndiLookup() {`
`50`	`50`	`/**`
`51`	`51`	`* Looks up the value of the JNDI resource.`
`52`	`52`	`*`
`53`		`- * @param event The current LogEvent (is ignored by this StrLookup).`
`54`	`53`	`* @param key the JNDI resource name to be looked up, may be null`
`55`	`54`	`* @return The String value of the JNDI resource.`
`56`	`55`	`*/`
`57`	`56`	`@Override`
`58`		`- public String lookup(final LogEvent event, final String key) {`
	`57`	`+ public String lookup(final LogEvent ignored, final String key) {`
`59`	`58`	`if (key == null) {`
`60`	`59`	`return null;`
`61`	`60`	`}`
Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@ private static URI getParent(final URI uri) throws URISyntaxException {`
`53`	`53`	`}`
`54`	`54`
`55`	`55`	`@Override`
`56`		`- public String lookup(final LogEvent event, final String key) {`
	`56`	`+ public String lookup(final LogEvent ignored, final String key) {`
`57`	`57`	`if (configuration != null) {`
`58`	`58`	`final ConfigurationSource configSrc = configuration.getConfigurationSource();`
`59`	`59`	`final File file = configSrc.getFile();`
Original file line number	Diff line number	Diff line change
`@@ -82,7 +82,7 @@ public static void setMainArguments(final String... args) {`
`82`	`82`	`}`
`83`	`83`
`84`	`84`	`@Override`
`85`		`- public String lookup(final LogEvent event, final String key) {`
	`85`	`+ public String lookup(final LogEvent ignored, final String key) {`
`86`	`86`	`return MAIN_SINGLETON.getMap().get(key);`
`87`	`87`	`}`
`88`	`88`
Original file line number	Diff line number	Diff line change
`@@ -39,14 +39,12 @@ public class ResourceBundleLookup extends AbstractLookup {`
`39`	`39`	`*`
`40`	`40`	`* For example: "com.domain.messages:MyKey".`
`41`	`41`	`*`
`42`		`- * @param event`
`43`		`- * The current LogEvent.`
`44`	`42`	`* @param key`
`45`	`43`	`* the key to be looked up, may be null`
`46`	`44`	`* @return The value associated with the key.`
`47`	`45`	`*/`
`48`	`46`	`@Override`
`49`		`- public String lookup(final LogEvent event, final String key) {`
	`47`	`+ public String lookup(final LogEvent ignored, final String key) {`
`50`	`48`	`if (key == null) {`
`51`	`49`	`return null;`
`52`	`50`	`}`