| <?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="rgoers@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="DockerLookup"/> |
| <subsection name="Docker Lookup"> |
| <p> |
| The DockerLookup can be used to lookup attributes from the Docker container the application is running |
| in. |
| </p> |
| Log4j Docker provides access to the following container attributes: |
| <table> |
| <tr><td>containerId</td><td>The full id assigned to the container.</td></tr> |
| <tr><td>containerName</td><td>The name assigned to the container.</td></tr> |
| <tr><td>imageId</td><td>The id assigned to the image.</td></tr> |
| <tr><td>imageName</td><td>The name assigned to the image.</td></tr> |
| <tr><td>shortContainerId</td><td>The first 12 characters of the container id.</td></tr> |
| <tr><td>shortImageId</td><td>The first 12 characters of the image id.</td></tr> |
| </table> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <JsonLayout properties="true" compact="true" eventEol="true"> |
| <KeyValuePair key="containerId" value="${docker:containerId}"/> |
| <KeyValuePair key="containerName" value="${docker:containerName}"/> |
| <KeyValuePair key="imageName" value="${docker:imageName}"/> |
| </JsonLayout>]]></pre> |
| <p> |
| This Lookup is subject to the requirements listed at <a href="../log4j-docker/index.html">Log4j Docker Support</a> |
| </p> |
| </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="EventLookup"/> |
| <subsection name="EventLookup"> |
| <p> |
| The EventLookup provides access to fields within the log event from the configuration. |
| </p> |
| <table> |
| <tr> |
| <th>Key</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>Exception</td> |
| <td>Returns the simple class name of the Exception, if one is included in the event.</td> |
| </tr> |
| <tr> |
| <td>Level</td> |
| <td>Returns the logging Level of the event.</td> |
| </tr> |
| <tr> |
| <td>Logger</td> |
| <td>Returns the name of the Logger.</td> |
| </tr> |
| <tr> |
| <td>Marker</td> |
| <td>Returns the name of the Marker associated with the log event, if one is present.</td> |
| </tr> |
| <tr> |
| <td>Message</td> |
| <td>Returns the formatted Message string.</td> |
| </tr> |
| <tr> |
| <td>ThreadId</td> |
| <td>Returns the thread id associated with the log event.</td> |
| </tr> |
| <tr> |
| <td>ThreadName</td> |
| <td>Returns the name of the thread associate with the log event.</td> |
| </tr> |
| <tr> |
| <td>Timestamp</td> |
| <td>Returns the time in milliseconds when the event occurred.</td> |
| </tr> |
| </table> |
| <p> |
| In this example the RoutingAppender picks a route based on the presence of a Marker named "AUDIT" being |
| present in the log event. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="WARN" name="RoutingTest"> |
| <Appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT" /> |
| <Flume name="AuditLogger" compress="true"> |
| <Agent host="192.168.10.101" port="8800"/> |
| <Agent host="192.168.10.102" port="8800"/> |
| <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/> |
| </Flume> |
| <Routing name="Routing"> |
| <Routes> |
| <Route pattern="$${event:Marker}"> |
| <RollingFile |
| name="Rolling-${mdc:UserId}" |
| fileName="${mdc:UserId}.log" |
| filePattern="${mdc:UserId}.%i.log.gz"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| <SizeBasedTriggeringPolicy size="500" /> |
| </RollingFile> |
| </Route> |
| <Route ref="AuditLogger" key="AUDIT"/> |
| <Route ref="STDOUT" key="STDOUT"/> |
| </Routes> |
| <IdlePurgePolicy timeToLive="15" timeUnit="minutes"/> |
| </Routing> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Routing" /> |
| </Root> |
| </Loggers> |
| </Configuration>]]></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="KubernetesLookup"/> |
| <subsection name="Kubernetes Lookup"> |
| <p> |
| The KubernetesLookup can be used to lookup attributes from the Kubernetes environment for the container |
| the application is running in. |
| </p> |
| Log4j Kubernetes provides access to the following container attributes: |
| <table> |
| <tr><td>accountName</td><td>The service account name</td></tr> |
| <tr><td>clusterName</td><td>The name of the cluster the application is deployed in</td></tr> |
| <tr><td>containerId</td><td>The full id assigned to the container</td></tr> |
| <tr><td>containerName</td><td>The name assigned to the container</td></tr> |
| <tr><td>host</td><td>The name assigned to the host operating system</td></tr> |
| <tr><td>hostIp</td><td>The host's ip address</td></tr> |
| <tr><td>imageId</td><td>The id assigned to the container image</td></tr> |
| <tr><td>imageName</td><td>The name assigned to the container image</td></tr> |
| <tr><td>labels</td><td>All labels formatted in a list</td></tr> |
| <tr><td>labesl.app</td><td>The application name</td></tr> |
| <tr><td>labels.podTemplateHash</td><td>The pod's template hash value</td></tr> |
| <tr><td>masterUrl</td><td>The URL used to access the API server</td></tr> |
| <tr><td>namespaceId</td><td>The id of the namespace the various kubernetes components are located within</td></tr> |
| <tr><td>namespaceName</td><td>The namespace the various kubernetes components are located within</td></tr> |
| <tr><td>podId</td><td>The pod's ip number</td></tr> |
| <tr><td>podIp</td><td>The pod's ip address</td></tr> |
| <tr><td>podName</td><td>The name of the pod</td></tr> |
| </table> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <GelfLayout includeStackTrace="true" host="${hostName}" includeThreadContext="true" includeNullDelimiter="true" |
| compressionType="OFF"> |
| <ThreadContextIncludes>requestId,sessionId,loginId,userId,ipAddress,callingHost</ThreadContextIncludes> |
| <MessagePattern>%d [%t] %-5p %X{requestId, sessionId, loginId, userId, ipAddress} %C{1.}.%M:%L - %m%n</MessagePattern> |
| <KeyValuePair key="docker.containerId" value="${docker:containerId:-}"/> |
| <KeyValuePair key="application" value="$${lower:${spring:spring.application.name}}"/> |
| <KeyValuePair key="kubernetes.serviceAccountName" value="${k8s:accountName:-}"/> |
| <KeyValuePair key="kubernetes.clusterName" value="${k8s:clusterName:-}/> |
| <KeyValuePair key="kubernetes.containerId" value="${k8s:containerId:-}"/> |
| <KeyValuePair key="kubernetes.containerName" value="${k8s:containerName:-}"/> |
| <KeyValuePair key="kubernetes.host" value="${k8s:host:-}"/> |
| <KeyValuePair key="kubernetes.labels.app" value="${k8s:labels.app:-}"/> |
| <KeyValuePair key="kubernetes.labels.pod-template-hash" value="${k8s:labels.podTemplateHash:-}"/> |
| <KeyValuePair key="kubernetes.master_url" value="${k8s:masterUrl:-}"/> |
| <KeyValuePair key="kubernetes.namespaceId" value="${k8s:namespaceId:-}"/> |
| <KeyValuePair key="kubernetes.namespaceName" value="${k8s:namespaceName:-}"/> |
| <KeyValuePair key="kubernetes.podID" value="${k8s:podId:-}"/> |
| <KeyValuePair key="kubernetes.podIP" value="${k8s:podIp:-}"/> |
| <KeyValuePair key="kubernetes.podName" value="${k8s:podName:-}"/> |
| <KeyValuePair key="kubernetes.imageId" value="${k8s:imageId:-}"/> |
| <KeyValuePair key="kubernetes.imageName" value="${k8s:imageName:-}"/> |
| </GelfLayout>]]></pre> |
| <p> |
| This Lookup is subject to the configuration requirements listed at <a href="../log4j-kubernetes/index.html">Log4j Kubernetes Support</a> |
| </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="LowerLookup"/> |
| <subsection name="Lower Lookup"> |
| <p> |
| The LowerLookup converts the passed in argument to lower case. Presumably the value will be the |
| result of a nested lookup. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <File name="Application" fileName="application.log"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] $${lower:{${spring:spring.application.name}} %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> |
| Note: Many applications use leading dashes to identify command arguments. Specifying |
| <code>${main:--file}</code> would result in the lookup failing because it would look for a variable |
| named "main" with a default value of "-file". To avoid this the ":" separating the Lookup name from the |
| key must be followed by a backslash as an escape character as in <code>${main:\--file}</code> |
| <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> |
| <tr> |
| <td>${main:\--quiet:-true}</td> |
| <td> |
| <p><code>true</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="SpringLookup"/> |
| <subsection name="Spring Boot Lookup"> |
| <p> |
| The Spring Boot Lookup retrieves the values of Spring properties from the Spring configuration as well as |
| values of the active and default profiles. Specifying a key of "profiles.active" will reutrn the active |
| profiles while a key of "profiles.default" will return the default profiles. The default and active |
| profiles can be an array. If more than one profile is present they will be returned as a comma separated |
| list. To retrieve a single item from the array append "[{index}]" to the key. For example, to return the |
| first active profile in the list specify "profiles.active[0]". |
| </p> |
| <p> |
| This Lookup will return null values until Spring Boot initializes application logging. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <File name="Application" fileName="application-${spring:profiles.active[0]}.log"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] $${spring:spring.application.name} %m%n</pattern> |
| </PatternLayout> |
| </File>]]></pre> |
| <p>This Lookup requires log4j-spring-cloud-config-client be included in the application.</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="UpperLookup"/> |
| <subsection name="Upper Lookup"> |
| <p> |
| The UpperLookup converts the passed in argument to upper case. Presumably the value will be the |
| result of a nested lookup. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <File name="Application" fileName="application.log"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] $$upper{${spring:spring.application.name}} %m%n</pattern> |
| </PatternLayout> |
| </File>]]></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>contextPathName</td> |
| <td>The first token in the context path of the web application splitting on "/" characters.</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> |