LOG4J2-1802: Convert lookups manual page to asciidoc

Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/1079bef3
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/1079bef3
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/1079bef3

Branch: refs/heads/master
Commit: 1079bef340dc821cd92e9af8e502adf136e06725
Parents: 0a60a4a
Author: Matt Sicker <boa...@gmail.com>
Authored: Sun Apr 8 19:48:51 2018 -0500
Committer: Matt Sicker <boa...@gmail.com>
Committed: Sun Apr 8 20:08:49 2018 -0500

----------------------------------------------------------------------
 src/site/asciidoc/manual/lookups.adoc | 498 ++++++++++++++++++++++++++++
 src/site/xdoc/manual/lookups.xml      | 511 -----------------------------
 2 files changed, 498 insertions(+), 511 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/1079bef3/src/site/asciidoc/manual/lookups.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/lookups.adoc 
b/src/site/asciidoc/manual/lookups.adoc
new file mode 100644
index 0000000..89317dd
--- /dev/null
+++ b/src/site/asciidoc/manual/lookups.adoc
@@ -0,0 +1,498 @@
+////
+    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
+
+        https://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.
+////
+= Lookups
+Ralph Goers <rgo...@apache.org>
+
+Lookups provide a way to add values to the Log4j configuration at
+arbitrary places. They are a particular type of Plugin that implements
+the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
+interface. Information on how to use Lookups in configuration files can
+be found in the link:configuration.html#PropertySubstitution[Property
+Substitution] section of the link:configuration.html[Configuration]
+page.
+
+[#ContextMapLookup]
+== Context Map Lookup
+
+The ContextMapLookup allows applications to store data in the Log4j
+ThreadContext Map and then retrieve the values in the Log4j
+configuration. In the example below, the application would store the
+current user's login id in the ThreadContext Map with the key "loginId".
+During initial configuration processing the first '$' will be removed.
+The PatternLayout supports interpolation with Lookups and will then
+resolve the variable for each event. Note that the pattern
+"%X\{loginId}" would achieve the same result.
+
+[source,xml]
+----
+<File name="Application" fileName="application.log">
+  <PatternLayout>
+    <pattern>%d %p %c{1.} [%t] $${ctx:loginId} %m%n</pattern>
+  </PatternLayout>
+</File>
+----
+
+[#DateLookup]
+== Date Lookup
+
+The DateLookup is somewhat unusual from the other lookups as it doesn't
+use the key to locate an item. Instead, the key can be used to specify a
+date format string that is valid for
+http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html[SimpleDateFormat].
+The current date, or the date associated with the current log event will
+be formatted as specified.
+
+[source,xml]
+----
+<RollingFile name="Rolling-${map:type}" fileName="${filename}" 
filePattern="target/rolling1/test1-$${date:MM-dd-yyyy}.%i.log.gz">
+  <PatternLayout>
+    <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+  </PatternLayout>
+  <SizeBasedTriggeringPolicy size="500" />
+</RollingFile>
+----
+
+[#EnvironmentLookup]
+== Environment Lookup
+
+The EnvironmentLookup allows systems to configure environment variables,
+either in global files such as /etc/profile or in the startup scripts
+for applications, and then retrieve those variables from within the
+logging configuration. The example below includes the name of the
+currently logged in user in the application log.
+
+[source,xml]
+----
+<File name="Application" fileName="application.log">
+  <PatternLayout>
+    <pattern>%d %p %c{1.} [%t] $${env:USER} %m%n</pattern>
+  </PatternLayout>
+</File>
+----
+
+This lookup also supports default value syntax. In the sample below,
+when the `USER` environment variable is undefined, the default value
+`jdoe` is used:
+
+[source,xml]
+----
+<File name="Application" fileName="application.log">
+  <PatternLayout>
+    <pattern>%d %p %c{1.} [%t] $${env:USER:-jdoe} %m%n</pattern>
+  </PatternLayout>
+</File>
+----
+
+[#JavaLookup]
+== Java Lookup
+
+The JavaLookup allows Java environment information to be retrieved in
+convenient preformatted strings using the `java:` prefix.
+
+[cols="1m,4a"]
+|===
+|Key |Description
+
+|version
+|The short Java version, like:
+
+`Java version 1.7.0_67`
+
+|runtime
+|The Java runtime version, like:
+
+`Java(TM) SE Runtime Environment (build 1.7.0_67-b01) from Oracle Corporation`
+
+|vm
+|The Java VM version, like:
+
+`Java HotSpot(TM) 64-Bit Server VM (build 24.65-b04, mixed mode)`
+
+|os
+|The OS version, like:
+
+`Windows 7 6.1 Service Pack 1, architecture: amd64-64`
+
+|locale
+|Hardware information, like:
+
+`default locale: en_US, platform encoding: Cp1252`
+
+|hw
+|Hardware information, like:
+
+`processors: 4, architecture: amd64-64, instruction sets: amd64`
+
+|===
+
+For example:
+
+[source,xml]
+----
+<File name="Application" fileName="application.log">
+  <PatternLayout header="${java:runtime} - ${java:vm} - ${java:os}">
+    <Pattern>%d %m%n</Pattern>
+  </PatternLayout>
+</File>
+----
+
+[#JndiLookup]
+== JNDI Lookup
+
+The JndiLookup allows variables to be retrieved via JNDI. By default the
+key will be prefixed with java:comp/env/, however if the key contains a
+":" no prefix will be added.
+
+[source,xml]
+----
+<File name="Application" fileName="application.log">
+  <PatternLayout>
+    <pattern>%d %p %c{1.} [%t] $${jndi:logging/context-name} %m%n</pattern>
+  </PatternLayout>
+</File>
+----
+
+*Java's JNDI module is not available on Android.*
+
+[#JmxRuntimeInputArgumentsLookup]
+== JVM Input Arguments Lookup (JMX)
+
+Maps JVM input arguments -- but not _main_ arguments -- using JMX to
+acquire the JVM arguments.
+
+Use the prefix `jvmrunargs` to access JVM arguments.
+
+See the Javadocs for
+https://docs.oracle.com/javase/8/docs/api/java/lang/management/RuntimeMXBean.html#getInputArguments--[java.lang.management.RuntimeMXBean.getInputArguments()].
+
+*Java's JMX module is not available on Android or on Google App Engine.*
+
+[#Log4jConfigLookup]
+== Log4j Configuration Location Lookup
+
+Log4j configuration properties. The expressions
+`${log4j:configLocation}` and `${log4j:configParentLocation}`
+respectively provide the absolute path to the log4j configuration file
+and its parent folder.
+
+The example below uses this lookup to place log files in a directory
+relative to the log4j configuration file.
+
+[source,xml]
+----
+<File name="Application" 
fileName="${log4j:configParentLocation}/logs/application.log">
+  <PatternLayout>
+    <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+  </PatternLayout>
+</File>
+----
+
+[#AppMainArgsLookup]
+== Main Arguments Lookup (Application)
+
+This lookup requires that you manually provide the main arguments of the
+application to Log4j:
+
+[source,java]
+----
+import org.apache.logging.log4j.core.lookup.MainMapLookup;
+
+public static void main(String args[]) {
+  MainMapLookup.setMainArguments(args);
+  ...
+}
+----
+
+If the main arguments have been set, this lookup allows applications to
+retrieve these main argument values from within the logging
+configuration. The key that follows the `main:` prefix can either be a
+0-based index into the argument list, or a string, where
+`${main:myString}` is substituted with the value that follows `myString`
+in the main argument list.
+
+For example, suppose the static void main String[] arguments are:
+
+....
+--file foo.txt --verbose -x bar
+....
+
+Then the following substitutions are possible:
+
+[cols="m,m"]
+|===
+|Expression |Result
+
+|${main:0}
+|--file
+
+|${main:1}
+|foo.txt
+
+|${main:2}
+|--verbose
+
+|${main:3}
+|-x
+
+|${main:4}
+|bar
+
+|${main:--file}
+|foo.txt
+
+|${main:-x}
+|bar
+
+|${main:bar}
+|null
+|===
+
+Example usage:
+
+[source,xml]
+----
+<File name="Application" fileName="application.log">
+  <PatternLayout header="File: ${main:--file}">
+    <Pattern>%d %m%n</Pattern>
+  </PatternLayout>
+</File>
+----
+
+[#MapLookup]
+== Map Lookup
+
+The MapLookup serves several purposes.
+
+1.  Provide the base for Properties declared in the configuration file.
+2.  Retrieve values from MapMessages in LogEvents.
+3.  Retrieve values set with
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/MapLookup.html#setMainArguments%28java.lang.String%5B%5D%29[MapLookup.setMainArguments(String[])]
+
+The first item simply means that the MapLookup is used to substitute
+properties that are defined in the configuration file. These variables
+are specified without a prefix - e.g. `${name}`. The second usage allows
+a value from the current
+link:../log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html[`MapMessage`],
+if one is part of the current log event, to be substituted. In the
+example below the RoutingAppender will use a different
+RollingFileAppender for each unique value of the key named "type" in the
+MapMessage. Note that when used this way a value for "type" should be
+declared in the properties declaration to provide a default value in
+case the message is not a MapMessage or the MapMessage does not contain
+the key. See the link:configuration.html#PropertySubstitution[Property
+Substitution] section of the link:configuration.html[Configuration]
+page for information on how to set the default values.
+
+[source,xml]
+----
+<Routing name="Routing">
+  <Routes pattern="$${map:type}">
+    <Route>
+      <RollingFile name="Rolling-${map:type}" fileName="${filename}"
+                   filePattern="target/rolling1/test1-${map:type}.%i.log.gz">
+        <PatternLayout>
+          <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+        </PatternLayout>
+        <SizeBasedTriggeringPolicy size="500" />
+      </RollingFile>
+    </Route>
+  </Routes>
+</Routing>
+----
+
+The marker lookup allows you to use markers in interesting
+configurations like a routing appender. Consider the following YAML
+configuration and code that logs to different files based on markers:
+
+[source,yaml]
+----
+Configuration:
+  status: debug
+
+  Appenders:
+    Console:
+    RandomAccessFile:
+      - name: SQL_APPENDER
+        fileName: logs/sql.log
+        PatternLayout:
+          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
+      - name: PAYLOAD_APPENDER
+        fileName: logs/payload.log
+        PatternLayout:
+          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
+      - name: PERFORMANCE_APPENDER
+        fileName: logs/performance.log
+        PatternLayout:
+          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
+
+    Routing:
+      name: ROUTING_APPENDER
+      Routes:
+        pattern: "$${marker:}"
+        Route:
+        - key: PERFORMANCE
+          ref: PERFORMANCE_APPENDER
+        - key: PAYLOAD
+          ref: PAYLOAD_APPENDER
+        - key: SQL
+          ref: SQL_APPENDER
+
+  Loggers:
+    Root:
+      level: trace
+      AppenderRef:
+        - ref: ROUTING_APPENDER
+----
+
+[source,java]
+----
+public static final Marker SQL = MarkerFactory.getMarker("SQL");
+public static final Marker PAYLOAD = MarkerFactory.getMarker("PAYLOAD");
+public static final Marker PERFORMANCE = 
MarkerFactory.getMarker("PERFORMANCE");
+
+final Logger logger = LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
+
+logger.info(SQL, "Message in Sql.log");
+logger.info(PAYLOAD, "Message in Payload.log");
+logger.info(PERFORMANCE, "Message in Performance.log");
+----
+
+Note the key part of the configuration is `pattern: "$${marker:}"`. This
+will produce three log files, each with a log event for a specific
+marker. Log4j will route the log event with the `SQL` marker to
+`sql.log`, the log event with the `PAYLOAD` marker to `payload.log`, and
+so on.
+
+You can use the notation `"${marker:name}"` and `"$${marker:name}"` to
+check for the existence of a marker where `name` is the marker name. If
+the marker exists, the expression returns the name, otherwise `null`.
+
+[#StructuredDataLookup]
+== Structured Data Lookup
+
+The StructuredDataLookup is very similar to the MapLookup in that it
+will retrieve values from StructuredDataMessages. In addition to the Map
+values it will also return the name portion of the id (not including the
+enterprise number) and the type field. The main difference between the
+example below and the example for MapMessage is that the "type" is an
+attribute of the
+link:../log4j-api/apidocs/org/apache/logging/log4j/message/StructuredDataMessage.html[StructuredDataMessage]
+while "type" would have to be an item in the Map in a MapMessage.
+
+[source,xml]
+----
+<Routing name="Routing">
+  <Routes pattern="$${sd:type}">
+    <Route>
+      <RollingFile name="Rolling-${sd:type}" fileName="${filename}"
+                   filePattern="target/rolling1/test1-${sd:type}.%i.log.gz">
+        <PatternLayout>
+          <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+        </PatternLayout>
+        <SizeBasedTriggeringPolicy size="500" />
+      </RollingFile>
+    </Route>
+  </Routes>
+</Routing>
+----
+
+[#SystemPropertiesLookup]
+== System Properties Lookup
+
+As it is quite common to define values inside and outside the
+application by using System Properties, it is only natural that they
+should be accessible via a Lookup. As system properties are often
+defined outside the application it would be quite common to see
+something like:
+
+[source,xml]
+----
+<Appenders>
+  <File name="ApplicationLog" fileName="${sys:logPath}/app.log"/>
+</Appenders>
+----
+
+This lookup also supports default value syntax. In the sample below,
+when the `logPath` system property is undefined, the default value
+`/var/logs` is used:
+
+[source,xml]
+----
+<Appenders>
+  <File name="ApplicationLog" fileName="${sys:logPath:-/var/logs}/app.log"/>
+</Appenders>
+----
+
+[#WebLookup]
+== Web Lookup
+
+The WebLookup allows applications to retrieve variables that are
+associated with the ServletContext. In addition to being able to
+retrieve various fields in the ServletContext, WebLookup supports
+looking up values stored as attributes or configured as initialization
+parameters. The following table lists various keys that can be
+retrieved:
+
+[cols="1m,4"]
+|===
+|Key |Description
+
+|attr._name_
+|Returns the ServletContext attribute with the specified name
+
+|contextPath
+|The context path of the web application
+
+|effectiveMajorVersion
+|Gets the major version of the Servlet specification that the application
+represented by this ServletContext is based on.
+
+|effectiveMinorVersion
+|Gets the minor version of the Servlet specification that the application
+represented by this ServletContext is based on.
+
+|initParam._name_
+|Returns the ServletContext initialization parameter with the specified name
+
+|majorVersion
+|Returns the major version of the Servlet API that this servlet container 
supports.
+
+|minorVersion
+|Returns the minor version of the Servlet API that this servlet container 
supports.
+
+|rootDir
+|Returns the result of calling getRealPath with a value of "/".
+
+|serverInfo
+|Returns the name and version of the servlet container on which the servlet is 
running.
+
+|servletContextName
+|Returns the name of the web application as defined in the display-name 
element of the deployment descriptor
+|===
+
+Any other key names specified will first be checked to see if a
+ServletContext attribute exists with that name and then will be checked
+to see if an initialization parameter of that name exists. If the key is
+located then the corresponding value will be returned.
+
+[source,xml]
+----
+<Appenders>
+  <File name="ApplicationLog" fileName="${web:rootDir}/app.log"/>
+</Appenders>
+----

http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/1079bef3/src/site/xdoc/manual/lookups.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/lookups.xml b/src/site/xdoc/manual/lookups.xml
deleted file mode 100644
index 255054a..0000000
--- a/src/site/xdoc/manual/lookups.xml
+++ /dev/null
@@ -1,511 +0,0 @@
-<?xml version="1.0"?>
-<!--
-    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.
--->
-
-<document xmlns="http://maven.apache.org/XDOC/2.0";
-          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 
http://maven.apache.org/xsd/xdoc-2.0.xsd";>
-    <properties>
-        <title>Log4j 2 Lookups</title>
-        <author email="rgo...@apache.org">Ralph Goers</author>
-    </properties>
-
-    <body>
-      <section name="Lookups">
-        <p>
-          Lookups provide a way to add values to the Log4j configuration at 
arbitrary places. They are
-          a particular type of Plugin that implements the
-          <a 
href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html">StrLookup</a>
 interface.
-          Information on how to use Lookups in configuration files can be 
found in the
-          <a href="./configuration.html#PropertySubstitution">Property 
Substitution</a> section of the
-          <a href="./configuration.html">Configuration</a> page.
-        </p>
-        <a name="ContextMapLookup"/>
-        <subsection name="Context Map Lookup">
-          <p>
-            The ContextMapLookup allows applications to store data in the 
Log4j ThreadContext Map and
-            then retrieve the values in the Log4j configuration. In the 
example below, the application
-            would store the current user's login id in the ThreadContext Map 
with the key "loginId". During
-            initial configuration processing the first '$' will be removed. 
The PatternLayout supports
-            interpolation with Lookups and will then resolve the variable for 
each event.  Note that
-            the pattern "%X{loginId}" would achieve the same result.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<File name="Application" fileName="application.log">
-  <PatternLayout>
-    <pattern>%d %p %c{1.} [%t] $${ctx:loginId} %m%n</pattern>
-  </PatternLayout>
-</File>]]></pre>
-        </subsection>
-        <a name="DateLookup"/>
-        <subsection name="Date Lookup">
-          <p>
-            The DateLookup is somewhat unusual from the other lookups as it 
doesn't use the key to locate an item.
-            Instead, the key can be used to specify a date format string that 
is valid for
-            <a 
href="http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html";>SimpleDateFormat</a>.
-            The current date, or the date associated with the current log 
event will be formatted as specified.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<RollingFile name="Rolling-${map:type}" fileName="${filename}" 
filePattern="target/rolling1/test1-$${date:MM-dd-yyyy}.%i.log.gz">
-  <PatternLayout>
-    <pattern>%d %p %c{1.} [%t] %m%n</pattern>
-  </PatternLayout>
-  <SizeBasedTriggeringPolicy size="500" />
-</RollingFile>]]></pre>
-        </subsection>
-        <a name="EnvironmentLookup"/>
-        <subsection name="Environment Lookup">
-          <p>
-            The EnvironmentLookup allows systems to configure environment 
variables, either in global files
-            such as /etc/profile or in the startup scripts for applications, 
and then retrieve those variables
-            from within the logging configuration. The example below includes 
the name of the currently logged
-            in user in the application log.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<File name="Application" fileName="application.log">
-  <PatternLayout>
-    <pattern>%d %p %c{1.} [%t] $${env:USER} %m%n</pattern>
-  </PatternLayout>
-</File>]]></pre>
-          <p>
-            This lookup also supports default value syntax. In the sample 
below, when the <code>USER</code> environment
-            variable is undefined, the default value <code>jdoe</code> is used:
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<File name="Application" fileName="application.log">
-  <PatternLayout>
-    <pattern>%d %p %c{1.} [%t] $${env:USER:-jdoe} %m%n</pattern>
-  </PatternLayout>
-</File>]]></pre>           
-        </subsection>
-        <a name="JavaLookup"/>
-        <subsection name="Java Lookup">
-          <p>
-            The JavaLookup allows Java environment information to be retrieved 
in convenient preformatted strings
-            using the <code>java:</code> prefix.
-          </p>
-          <table>
-            <tr>
-              <th>Key</th>
-              <th>Description</th>
-            </tr>
-            <tr>
-              <td>version</td>
-              <td>
-                <p>The short Java version, like:</p>
-                <p><code>Java version 1.7.0_67</code></p>
-              </td>
-            </tr>
-            <tr>
-              <td>runtime</td>
-              <td>
-                <p>The Java runtime version, like:</p>
-                <p><code>Java(TM) SE Runtime Environment (build 1.7.0_67-b01) 
from Oracle Corporation</code></p>
-              </td>
-            </tr>
-            <tr>
-              <td>vm</td>
-              <td>
-                <p>The Java VM version, like:</p>
-                <p><code>Java HotSpot(TM) 64-Bit Server VM (build 24.65-b04, 
mixed mode)</code></p>
-              </td>
-            </tr>
-            <tr>
-              <td>os</td>
-              <td>
-                <p>The OS version, like:</p>
-                <p><code>Windows 7 6.1 Service Pack 1, architecture: 
amd64-64</code></p>
-              </td>
-            </tr>
-            <tr>
-              <td>locale</td>
-              <td>
-                <p>Hardware information, like:</p>
-                <p><code>default locale: en_US, platform encoding: 
Cp1252</code></p>
-              </td>
-            </tr>
-            <tr>
-              <td>hw</td>
-              <td>
-                <p>Hardware information, like:</p>
-                <p><code>processors: 4, architecture: amd64-64, instruction 
sets: amd64</code></p>
-              </td>
-            </tr>
-          </table>
-          <p>
-            For example:
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<File name="Application" fileName="application.log">
-  <PatternLayout header="${java:runtime} - ${java:vm} - ${java:os}">
-    <Pattern>%d %m%n</Pattern>
-  </PatternLayout>
-</File>]]></pre>
-        </subsection>
-        <a name="JndiLookup"/>
-        <subsection name="Jndi Lookup">
-          <p>
-            The JndiLookup allows variables to be retrieved via JNDI. By 
default the key will be prefixed with
-            java:comp/env/, however if the key contains a ":" no prefix will 
be added.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<File name="Application" fileName="application.log">
-  <PatternLayout>
-    <pattern>%d %p %c{1.} [%t] $${jndi:logging/context-name} %m%n</pattern>
-  </PatternLayout>
-</File>]]></pre>
-        <p><strong>Java's JNDI module is not available on Android.</strong></p>
-        </subsection>
-        <a name="JmxRuntimeInputArgumentsLookup"/>
-        <subsection name="JVM Input Arguments Lookup (JMX)">
-          <p>
-            Maps JVM input arguments -- but not <em>main</em> arguments -- 
using JMX to acquire the JVM arguments.
-          </p>
-          <p>
-            Use the prefix <code>jvmrunargs</code> to access JVM arguments.
-          </p>
-          <p>
-            See the Javadocs for
-            <a 
href="http://docs.oracle.com/javase/8/docs/api/java/lang/management/RuntimeMXBean.html#getInputArguments--";>
-            java.lang.management.RuntimeMXBean.getInputArguments()
-            </a>.
-          </p>
-          <p><strong>Java's JMX module is not available on Android or on 
Google App Engine.</strong></p>
-        </subsection>
-        <a name="Log4jConfigLookup"/>
-        <subsection name="Log4j Configuration Location Lookup">
-          <p>
-            Log4j configuration properties. The expressions
-            <code>${log4j:configLocation}</code> and 
<code>${log4j:configParentLocation}</code>
-            respectively provide the absolute path to the log4j configuration 
file
-            and its parent folder.
-          </p><p>
-            The example below uses this lookup to place log files in a 
directory relative
-            to the log4j configuration file.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<File name="Application" 
fileName="${log4j:configParentLocation}/logs/application.log">
-  <PatternLayout>
-    <pattern>%d %p %c{1.} [%t] %m%n</pattern>
-  </PatternLayout>
-</File>]]></pre>
-        </subsection>
-        <a name="AppMainArgsLookup"/>
-        <subsection name="Main Arguments Lookup (Application)">
-          <p>
-             This lookup requires that you manually provide
-             the main arguments of the application to Log4j:
-          </p>
-<pre class="prettyprint linenums"><![CDATA[
-import org.apache.logging.log4j.core.lookup.MainMapLookup;
-
-public static void main(String args[]) {
-  MainMapLookup.setMainArguments(args);
-  ...
-}]]></pre>
-        <p>
-          If the main arguments have been set, this lookup allows applications 
to retrieve
-          these main argument values from within the logging configuration.
-          The key that follows the <code>main:</code> prefix can either be a 
0-based index into the argument list,
-          or a string, where <code>${main:myString}</code> is substituted with 
the value that follows
-          <code>myString</code> in the main argument list.
-        </p>
-        <p>
-          For example, suppose the static void main String[] arguments are:
-        </p>
-        <pre>--file foo.txt --verbose -x bar</pre>
-        <p>
-          Then the following substitutions are possible:
-        </p>
-        <table style="width: 40%">
-          <tr>
-            <th>Expression</th>
-            <th>Result</th>
-          </tr>
-          <tr>
-            <td>${main:0}</td>
-            <td>
-              <p><code>--file</code></p>
-            </td>
-          </tr>
-          <tr>
-            <td>${main:1}</td>
-            <td>
-              <p><code>foo.txt</code></p>
-            </td>
-          </tr>
-          <tr>
-            <td>${main:2}</td>
-            <td>
-              <p><code>--verbose</code></p>
-            </td>
-          </tr>
-          <tr>
-            <td>${main:3}</td>
-            <td>
-              <p><code>-x</code></p>
-            </td>
-          </tr>
-          <tr>
-            <td>${main:4}</td>
-            <td>
-              <p><code>bar</code></p>
-            </td>
-          </tr>
-          <tr>
-            <td>${main:--file}</td>
-            <td>
-              <p><code>foo.txt</code></p>
-            </td>
-          </tr>
-          <tr>
-            <td>${main:-x}</td>
-            <td>
-              <p><code>bar</code></p>
-            </td>
-          </tr>
-          <tr>
-            <td>${main:bar}</td>
-            <td>
-              <p><code>null</code></p>
-            </td>
-          </tr>
-        </table>
-          <p>
-            Example usage:
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<File name="Application" fileName="application.log">
-  <PatternLayout header="File: ${main:--file}">
-    <Pattern>%d %m%n</Pattern>
-  </PatternLayout>
-</File>]]></pre>
-        </subsection>
-        <a name="MapLookup"/>
-        <subsection name="Map Lookup">
-          <p>
-            The MapLookup serves several purposes.
-          </p>
-            <ol>
-              <li>Provide the base for Properties declared in the 
configuration file.</li>
-              <li>Retrieve values from MapMessages in LogEvents.</li>
-              <li>Retrieve values set with <a 
href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/MapLookup.html#setMainArguments%28java.lang.String[]%29">MapLookup.setMainArguments(String[])</a></li>
-            </ol>
-          <p>
-            The first item simply means that the MapLookup is used to 
substitute properties that are defined
-            in the configuration file. These variables are specified without a 
prefix - e.g. <code>${name}</code>.
-            The second usage allows a value from the current
-            <a 
href="../log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html">MapMessage</a>,
-            if one is part of the current log event, to be substituted. In the 
example below the RoutingAppender will
-            use a different RollingFileAppender for each unique value of the 
key named "type" in the MapMessage. Note
-            that when used this way a  value for "type" should be declared in 
the properties declaration to provide
-            a default value in case the message is not a MapMessage or the 
MapMessage does not contain the key. See the
-            <a href="./configuration.html#PropertySubstitution">Property 
Substitution</a> section of the
-            <a href="./configuration.html">Configuration</a> page for 
information on how to set the default values.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<Routing name="Routing">
-  <Routes pattern="$${map:type}">
-    <Route>
-      <RollingFile name="Rolling-${map:type}" fileName="${filename}"
-                   filePattern="target/rolling1/test1-${map:type}.%i.log.gz">
-        <PatternLayout>
-          <pattern>%d %p %c{1.} [%t] %m%n</pattern>
-        </PatternLayout>
-        <SizeBasedTriggeringPolicy size="500" />
-      </RollingFile>
-    </Route>
-  </Routes>
-</Routing>]]></pre>
-        </subsection>
-        <subsection name="Marker Lookup">
-          <p>
-            The marker lookup allows you to use markers in interesting 
configurations like a routing appender.
-            Consider the following YAML configuration and code that logs to 
different files based on markers:
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-Configuration:
-  status: debug
-
-  Appenders:
-    Console:
-    RandomAccessFile:
-      - name: SQL_APPENDER
-        fileName: logs/sql.log
-        PatternLayout:
-          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
-      - name: PAYLOAD_APPENDER
-        fileName: logs/payload.log
-        PatternLayout:
-          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
-      - name: PERFORMANCE_APPENDER
-        fileName: logs/performance.log
-        PatternLayout:
-          Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"
-
-    Routing:
-      name: ROUTING_APPENDER
-      Routes:
-        pattern: "$${marker:}"
-        Route:
-        - key: PERFORMANCE
-          ref: PERFORMANCE_APPENDER
-        - key: PAYLOAD
-          ref: PAYLOAD_APPENDER
-        - key: SQL
-          ref: SQL_APPENDER
-
-  Loggers:
-    Root:
-      level: trace
-      AppenderRef:
-        - ref: ROUTING_APPENDER]]></pre>
-          <pre class="prettyprint linenums"><![CDATA[
-public static final Marker SQL = MarkerFactory.getMarker("SQL");
-public static final Marker PAYLOAD = MarkerFactory.getMarker("PAYLOAD");
-public static final Marker PERFORMANCE = 
MarkerFactory.getMarker("PERFORMANCE");
-
-final Logger logger = LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
-
-logger.info(SQL, "Message in Sql.log");
-logger.info(PAYLOAD, "Message in Payload.log");
-logger.info(PERFORMANCE, "Message in Performance.log");]]></pre>
-          <p>
-            Note the key part of the configuration is <code>pattern: 
"$${marker:}"</code>. This will produce three log files,
-            each with a log event for a specific marker. Log4j will route the 
log event with the <code>SQL</code> marker to
-            <code>sql.log</code>, the log event with the <code>PAYLOAD</code> 
marker to <code>payload.log</code>, and so on.
-          </p>
-          <p>
-            You can use the notation <code>"${marker:name}"</code> and 
<code>"$${marker:name}"</code> to check for the
-            existence of a marker where <code>name</code> is the marker name. 
If the marker exists, the expression returns
-            the name, otherwise <code>null</code>.
-          </p>
-        </subsection>
-        <a name="StructuredDataLookup"/>
-        <subsection name="Structured Data Lookup">
-          <p>
-            The StructuredDataLookup is very similar to the MapLookup in that 
it will retrieve values from
-            StructuredDataMessages. In addition to the Map values it will also 
return the name portion of the
-            id (not including the enterprise number) and the type field. The 
main difference between the
-            example below and the example for MapMessage is that the "type" is 
an attribute of the
-            <a 
href="../log4j-api/apidocs/org/apache/logging/log4j/message/StructuredDataMessage.html">StructuredDataMessage</a>
-            while "type" would have to be an item in the Map in a MapMessage.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<Routing name="Routing">
-  <Routes pattern="$${sd:type}">
-    <Route>
-      <RollingFile name="Rolling-${sd:type}" fileName="${filename}"
-                   filePattern="target/rolling1/test1-${sd:type}.%i.log.gz">
-        <PatternLayout>
-          <pattern>%d %p %c{1.} [%t] %m%n</pattern>
-        </PatternLayout>
-        <SizeBasedTriggeringPolicy size="500" />
-      </RollingFile>
-    </Route>
-  </Routes>
-</Routing>]]></pre>
-        </subsection>
-        <a name="SystemPropertiesLookup"/>
-        <subsection name="System Properties Lookup">
-          <p>
-            As it is quite common to define values inside and outside the 
application by using System Properties,
-            it is only natural that they should be accessible via a Lookup. As 
system properties are often
-            defined outside the application it would be quite common to see 
something like:
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<Appenders>
-  <File name="ApplicationLog" fileName="${sys:logPath}/app.log"/>
-</Appenders>]]></pre>
-          <p>
-            This lookup also supports default value syntax. In the sample 
below, when the <code>logPath</code> system
-            property is undefined, the default value <code>/var/logs</code> is 
used:
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[
-<Appenders>
-  <File name="ApplicationLog" fileName="${sys:logPath:-/var/logs}/app.log"/>
-</Appenders>]]></pre>            
-        </subsection>
-        <a name="WebLookup"/>
-        <subsection name="Web Lookup">
-          <p>
-            The WebLookup allows applications to retrieve variables that are 
associated with the ServletContext.
-            In addition to being able to retrieve various fields in the 
ServletContext, WebLookup supports looking
-            up values stored as attributes or configured as initialization 
parameters. The following table lists
-            various keys that can be retrieved:
-          </p>
-          <table>
-            <tr>
-              <th>Key</th>
-              <th>Description</th>
-            </tr>
-            <tr>
-              <td>attr.<i>name</i></td>
-              <td>Returns the ServletContext attribute with the specified 
name</td>
-            </tr>
-            <tr>
-              <td>contextPath</td>
-              <td>The context path of the web application</td>
-            </tr>
-            <tr>
-              <td>effectiveMajorVersion</td>
-              <td>Gets the major version of the Servlet specification that the 
application represented by this
-                ServletContext is based on.</td>
-            </tr>
-            <tr>
-              <td>effectiveMinorVersion</td>
-              <td>Gets the minor version of the Servlet specification that the 
application represented by this
-                ServletContext is based on.</td>
-            </tr>
-            <tr>
-              <td>initParam.<i>name</i></td>
-              <td>Returns the ServletContext initialization parameter with the 
specified name</td>
-            </tr>
-            <tr>
-              <td>majorVersion</td>
-              <td>Returns the major version of the Servlet API that this 
servlet container supports.</td>
-            </tr>
-            <tr>
-              <td>minorVersion</td>
-              <td>Returns the minor version of the Servlet API that this 
servlet container supports.</td>
-            </tr>
-            <tr>
-              <td>rootDir</td>
-              <td>Returns the result of calling getRealPath with a value of 
"/".</td>
-            </tr>
-            <tr>
-              <td>serverInfo</td>
-              <td>Returns the name and version of the servlet container on 
which the servlet is running.</td>
-            </tr>
-            <tr>
-              <td>servletContextName</td>
-              <td>Returns the name of the web application as defined in the 
display-name element of the
-                deployment descriptor</td>
-            </tr>
-          </table>
-          <p>Any other key names specified will first be checked to see if a 
ServletContext attribute exists with
-            that name and then will be checked to see if an initialization 
parameter of that name exists. If the
-            key is located then the corresponding value will be returned.</p>
-          <pre class="prettyprint linenums"><![CDATA[
-<Appenders>
-  <File name="ApplicationLog" fileName="${web:rootDir}/app.log"/>
-</Appenders>]]></pre>
-        </subsection>
-
-      </section>
-    </body>
-</document>

Reply via email to