Google Git
Sign in
apache / logging-log4j-site / ac1db7db1c543d59f5028116b17c5a47140bccc2 / . / log4j-2.10.0 / manual / lookups.html
blob: 5191f62cdb52c13aa8c8c839008cd09c4d5dbdb4 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
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.
-->
<!-- Generated by Apache Maven Doxia at 2017-11-19 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Log4j &#x2013; Log4j 2 Lookups - Apache Log4j 2</title>
<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="../css/site.css" type="text/css" />
<script type="text/javascript" src="../js/jquery.min.js"></script>
<script type="text/javascript" src="../js/bootstrap.min.js"></script>
<script type="text/javascript" src="../js/prettify.min.js"></script>
<script type="text/javascript" src="../js/site.js"></script>
<meta name="author" content="Ralph Goers" />
<meta name="Date-Revision-yyyymmdd" content="20171119" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<a href="https://logging.apache.org/">
<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
</a>
<img class="logo-right" src="../images/logo.png" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="https://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="https://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="https://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
</li>
<li>
<a href="../../../" title="Logging Services">Logging Services</a>
</li>
<li>
<a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="external" target="_blank" title="Sonar">Sonar</a>
</li>
<li>
<a href="https://github.com/apache/logging-log4j2" class="external" target="_blank" title="GitHub">GitHub</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<table class="layout-table">
<tr>
<td class="sidebar">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
<li class="none">
<a href="../index.html" title="About">About</a>
</li>
<li class="none">
<a href="../download.html" title="Download">Download</a>
</li>
<li class="collapsed">
<a href="../javadoc.html" title="Javadoc">Javadoc</a>
</li>
<li class="none">
<a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts">Maven, Ivy, Gradle Artifacts</a>
</li>
<li class="none">
<a href="../runtime-dependencies.html" title="Runtime Dependencies">Runtime Dependencies</a>
</li>
<li class="none">
<a href="../changelog.html" title="Changelog">Changelog</a>
</li>
<li class="none">
<a href="../faq.html" title="FAQ">FAQ</a>
</li>
<li class="collapsed">
<a href="../performance.html" title="Performance">Performance</a>
</li>
<li class="none">
<a href="../articles.html" title="Articles and Tutorials">Articles and Tutorials</a>
</li>
<li class="none">
<a href="../thanks.html" title="Thanks">Thanks</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-pencil"></i>For Contributors</li>
<li class="none">
<a href="../build.html" title="Building Log4j from Source">Building Log4j from Source</a>
</li>
<li class="none">
<a href="../guidelines.html" title="Guidelines">Guidelines</a>
</li>
<li class="none">
<a href="../javastyle.html" title="Style Guide">Style Guide</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-book"></i>Manual</li>
<li class="none">
<a href="../manual/index.html" title="Introduction">Introduction</a>
</li>
<li class="none">
<a href="../manual/architecture.html" title="Architecture">Architecture</a>
</li>
<li class="none">
<a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
</li>
<li class="collapsed">
<a href="../manual/api.html" title="Java API">Java API</a>
</li>
<li class="none">
<a href="../manual/scala-api.html" title="Scala API">Scala API</a>
</li>
<li class="collapsed">
<a href="../manual/configuration.html" title="Configuration">Configuration</a>
</li>
<li class="collapsed">
<a href="../manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a>
</li>
<li class="expanded active">
<a href="../manual/lookups.html" title="Lookups">Lookups</a>
<ul>
<li class="none">
<a href="../manual/lookups.html#ContextMapLookup" title="Context Map">Context Map</a>
</li>
<li class="none">
<a href="../manual/lookups.html#DateLookup" title="Date">Date</a>
</li>
<li class="none">
<a href="../manual/lookups.html#EnvironmentLookup" title="Environment">Environment</a>
</li>
<li class="none">
<a href="../manual/lookups.html#JavaLookup" title="Java">Java</a>
</li>
<li class="none">
<a href="../manual/lookups.html#JndiLookup" title="JNDI">JNDI</a>
</li>
<li class="none">
<a href="../manual/lookups.html#JmxRuntimeInputArgumentsLookup" title="JVM Arguments">JVM Arguments</a>
</li>
<li class="none">
<a href="../manual/lookups.html#Log4jConfigLookup" title="Log4j Config">Log4j Config</a>
</li>
<li class="none">
<a href="../manual/lookups.html#AppMainArgsLookup" title="Main Arguments">Main Arguments</a>
</li>
<li class="none">
<a href="../manual/lookups.html#MapLookup" title="Map">Map</a>
</li>
<li class="none">
<a href="../manual/lookups.html#StructuredDataLookup" title="Structured Data">Structured Data</a>
</li>
<li class="none">
<a href="../manual/lookups.html#SystemPropertiesLookup" title="System Properties">System Properties</a>
</li>
<li class="none">
<a href="../manual/lookups.html#WebLookup" title="Web">Web</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="../manual/appenders.html" title="Appenders">Appenders</a>
</li>
<li class="collapsed">
<a href="../manual/layouts.html" title="Layouts">Layouts</a>
</li>
<li class="collapsed">
<a href="../manual/filters.html" title="Filters">Filters</a>
</li>
<li class="collapsed">
<a href="../manual/async.html" title="Async Loggers">Async Loggers</a>
</li>
<li class="collapsed">
<a href="../manual/garbagefree.html" title="Garbage-free Logging">Garbage-free Logging</a>
</li>
<li class="none">
<a href="../manual/jmx.html" title="JMX">JMX</a>
</li>
<li class="none">
<a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a>
</li>
<li class="collapsed">
<a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a>
</li>
<li class="collapsed">
<a href="../manual/plugins.html" title="Plugins">Plugins</a>
</li>
<li class="collapsed">
<a href="../manual/customconfig.html" title="Programmatic Log4j Configuration">Programmatic Log4j Configuration</a>
</li>
<li class="collapsed">
<a href="../manual/customloglevels.html" title="Custom Log Levels">Custom Log Levels</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-tags"></i>Related Projects</li>
<li class="none">
<a href="http://logging.apache.org/log4j/scala/index.html" class="external" target="_blank" title="Log4j-Scala">Log4j-Scala</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-tags"></i>Legacy</li>
<li class="none">
<a href="http://logging.apache.org/log4j/1.2/" class="external" target="_blank" title="Log4j 1.2">Log4j 1.2</a>
</li>
<li class="none">
<a href="http://logging.apache.org/log4j/log4j-2.3/" class="external" target="_blank" title="Log4j 2.3">Log4j 2.3</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Components</li>
<li class="none">
<a href="../log4j-api/index.html" title="API">API</a>
</li>
<li class="none">
<a href="../log4j-core/index.html" title="Implementation">Implementation</a>
</li>
<li class="none">
<a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a>
</li>
<li class="none">
<a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API">Log4j 1.2 API</a>
</li>
<li class="none">
<a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
</li>
<li class="none">
<a href="../log4j-jul/index.html" title="JUL Adapter">JUL Adapter</a>
</li>
<li class="none">
<a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
</li>
<li class="none">
<a href="../log4j-flume-ng/index.html" title="Apache Flume Appender">Apache Flume Appender</a>
</li>
<li class="none">
<a href="../log4j-taglib/index.html" title="Log4j Tag Library">Log4j Tag Library</a>
</li>
<li class="none">
<a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI">Log4j JMX GUI</a>
</li>
<li class="none">
<a href="../log4j-web/index.html" title="Log4j Web Application Support">Log4j Web Application Support</a>
</li>
<li class="none">
<a href="../log4j-appserver/index.html" title="Log4j Application Server Integration">Log4j Application Server Integration</a>
</li>
<li class="none">
<a href="../log4j-couchdb/index.html" title="Log4j CouchDB appender">Log4j CouchDB appender</a>
</li>
<li class="none">
<a href="../log4j-mongodb/index.html" title="Log4j MongoDB appender">Log4j MongoDB appender</a>
</li>
<li class="none">
<a href="../log4j-cassandra/index.html" title="Log4j Cassandra appender">Log4j Cassandra appender</a>
</li>
<li class="none">
<a href="../log4j-iostreams/index.html" title="Log4j IO Streams">Log4j IO Streams</a>
</li>
<li class="none">
<a href="../log4j-liquibase/index.html" title="Log4j Liquibase Binding">Log4j Liquibase Binding</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
<li class="none">
<a href="../dependencies.html" title="Dependencies">Dependencies</a>
</li>
<li class="none">
<a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li class="none">
<a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li class="none">
<a href="../team-list.html" title="Project Team">Project Team</a>
</li>
<li class="none">
<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
</li>
<li class="none">
<a href="../license.html" title="Project License">Project License</a>
</li>
<li class="none">
<a href="../source-repository.html" title="Source Repository">Source Repository</a>
</li>
<li class="none">
<a href="../project-summary.html" title="Project Summary">Project Summary</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
<li class="none">
<a href="../changes-report.html" title="Changes Report">Changes Report</a>
</li>
<li class="none">
<a href="../jira-report.html" title="JIRA Report">JIRA Report</a>
</li>
<li class="none">
<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
</li>
<li class="none">
<a href="../rat-report.html" title="RAT Report">RAT Report</a>
</li>
</ul>
</div>
<div id="poweredBy">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" />
</a>
</div>
</td>
<td class="content">
<!-- 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. -->
<div class="section">
<h2><a name="Lookups"></a>Lookups</h2>
<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"></a>
<div class="section">
<h3><a name="Context_Map_Lookup"></a>Context Map Lookup</h3>
<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 &quot;loginId&quot;. 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 &quot;%X{loginId}&quot; would achieve the same result.
</p>
<div>
<pre class="prettyprint linenums">
&lt;File name=&quot;Application&quot; fileName=&quot;application.log&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] $${ctx:loginId} %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;</pre></div>
</div>
<a name="DateLookup"></a>
<div class="section">
<h3><a name="Date_Lookup"></a>Date Lookup</h3>
<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 class="externalLink" 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>
<div>
<pre class="prettyprint linenums">
&lt;RollingFile name=&quot;Rolling-${map:type}&quot; fileName=&quot;${filename}&quot; filePattern=&quot;target/rolling1/test1-$${date:MM-dd-yyyy}.%i.log.gz&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;SizeBasedTriggeringPolicy size=&quot;500&quot; /&gt;
&lt;/RollingFile&gt;</pre></div>
</div>
<a name="EnvironmentLookup"></a>
<div class="section">
<h3><a name="Environment_Lookup"></a>Environment Lookup</h3>
<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>
<div>
<pre class="prettyprint linenums">
&lt;File name=&quot;Application&quot; fileName=&quot;application.log&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] $${env:USER} %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;</pre></div>
</div>
<a name="JavaLookup"></a>
<div class="section">
<h3><a name="Java_Lookup"></a>Java Lookup</h3>
<p>
The JavaLookup allows Java environment information to be retrieved in convenient preformatted strings
using the <tt>java:</tt> prefix.
</p>
<table border="0" class="bodyTable">
<tr class="a">
<th>Key</th>
<th>Description</th>
</tr>
<tr class="b">
<td>version</td>
<td>
<p>The short Java version, like:</p>
<p><tt>Java version 1.7.0_67</tt></p>
</td>
</tr>
<tr class="a">
<td>runtime</td>
<td>
<p>The Java runtime version, like:</p>
<p><tt>Java(TM) SE Runtime Environment (build 1.7.0_67-b01) from Oracle Corporation</tt></p>
</td>
</tr>
<tr class="b">
<td>vm</td>
<td>
<p>The Java VM version, like:</p>
<p><tt>Java HotSpot(TM) 64-Bit Server VM (build 24.65-b04, mixed mode)</tt></p>
</td>
</tr>
<tr class="a">
<td>os</td>
<td>
<p>The OS version, like:</p>
<p><tt>Windows 7 6.1 Service Pack 1, architecture: amd64-64</tt></p>
</td>
</tr>
<tr class="b">
<td>locale</td>
<td>
<p>Hardware information, like:</p>
<p><tt>default locale: en_US, platform encoding: Cp1252</tt></p>
</td>
</tr>
<tr class="a">
<td>hw</td>
<td>
<p>Hardware information, like:</p>
<p><tt>processors: 4, architecture: amd64-64, instruction sets: amd64</tt></p>
</td>
</tr>
</table>
<p>
For example:
</p>
<div>
<pre class="prettyprint linenums">
&lt;File name=&quot;Application&quot; fileName=&quot;application.log&quot;&gt;
&lt;PatternLayout header=&quot;${java:runtime} - ${java:vm} - ${java:os}&quot;&gt;
&lt;Pattern&gt;%d %m%n&lt;/Pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;</pre></div>
</div>
<a name="JndiLookup"></a>
<div class="section">
<h3><a name="Jndi_Lookup"></a>Jndi Lookup</h3>
<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 &quot;:&quot; no prefix will be added.
</p>
<div>
<pre class="prettyprint linenums">
&lt;File name=&quot;Application&quot; fileName=&quot;application.log&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] $${jndi:logging/context-name} %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;</pre></div>
<p><b>Java's JNDI module is not available on Android.</b></p>
</div>
<a name="JmxRuntimeInputArgumentsLookup"></a>
<div class="section">
<h3><a name="JVM_Input_Arguments_Lookup_JMX"></a>JVM Input Arguments Lookup (JMX)</h3>
<p>
Maps JVM input arguments -- but not <i>main</i> arguments -- using JMX to acquire the JVM arguments.
</p>
<p>
Use the prefix <tt>jvmrunargs</tt> to access JVM arguments.
</p>
<p>
See the Javadocs for
<a class="externalLink" href="http://docs.oracle.com/javase/8/docs/api/java/lang/management/RuntimeMXBean.html#getInputArguments--">
java.lang.management.RuntimeMXBean.getInputArguments()
</a>.
</p>
<p><b>Java's JMX module is not available on Android or on Google App Engine.</b></p>
</div>
<a name="Log4jConfigLookup"></a>
<div class="section">
<h3><a name="Log4j_Configuration_Location_Lookup"></a>Log4j Configuration Location Lookup</h3>
<p>
Log4j configuration properties. The expressions
<tt>${log4j:configLocation}</tt> and <tt>${log4j:configParentLocation}</tt>
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>
<div>
<pre class="prettyprint linenums">
&lt;File name=&quot;Application&quot; fileName=&quot;${log4j:configParentLocation}/logs/application.log&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;</pre></div>
</div>
<a name="AppMainArgsLookup"></a>
<div class="section">
<h3><a name="Main_Arguments_Lookup_Application"></a>Main Arguments Lookup (Application)</h3>
<p>
This lookup requires that you manually provide
the main arguments of the application to Log4j:
</p>
<div>
<pre class="prettyprint linenums">
import org.apache.logging.log4j.core.lookup.MainMapLookup;
public static void main(String args[]) {
MainMapLookup.setMainArguments(args);
...
}</pre></div>
<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 <tt>main:</tt> prefix can either be a 0-based index into the argument list,
or a string, where <tt>${main:myString}</tt> is substituted with the value that follows
<tt>myString</tt> in the main argument list.
</p>
<p>
For example, suppose the static void main String[] arguments are:
</p>
<div>
<pre>--file foo.txt --verbose -x bar</pre></div>
<p>
Then the following substitutions are possible:
</p>
<table border="0" class="bodyTable" style="width: 40%">
<tr class="a">
<th>Expression</th>
<th>Result</th>
</tr>
<tr class="b">
<td>${main:0}</td>
<td>
<p><tt>--file</tt></p>
</td>
</tr>
<tr class="a">
<td>${main:1}</td>
<td>
<p><tt>foo.txt</tt></p>
</td>
</tr>
<tr class="b">
<td>${main:2}</td>
<td>
<p><tt>--verbose</tt></p>
</td>
</tr>
<tr class="a">
<td>${main:3}</td>
<td>
<p><tt>-x</tt></p>
</td>
</tr>
<tr class="b">
<td>${main:4}</td>
<td>
<p><tt>bar</tt></p>
</td>
</tr>
<tr class="a">
<td>${main:--file}</td>
<td>
<p><tt>foo.txt</tt></p>
</td>
</tr>
<tr class="b">
<td>${main:-x}</td>
<td>
<p><tt>bar</tt></p>
</td>
</tr>
<tr class="a">
<td>${main:bar}</td>
<td>
<p><tt>null</tt></p>
</td>
</tr>
</table>
<p>
Example usage:
</p>
<div>
<pre class="prettyprint linenums">
&lt;File name=&quot;Application&quot; fileName=&quot;application.log&quot;&gt;
&lt;PatternLayout header=&quot;File: ${main:--file}&quot;&gt;
&lt;Pattern&gt;%d %m%n&lt;/Pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;</pre></div>
</div>
<a name="MapLookup"></a>
<div class="section">
<h3><a name="Map_Lookup"></a>Map Lookup</h3>
<p>
The MapLookup serves several purposes.
</p>
<ol style="list-style-type: decimal">
<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#setMainArguments28java.lang.String29">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. <tt>${name}</tt>.
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 &quot;type&quot; in the MapMessage. Note
that when used this way a value for &quot;type&quot; 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>
<div>
<pre class="prettyprint linenums">
&lt;Routing name=&quot;Routing&quot;&gt;
&lt;Routes pattern=&quot;$${map:type}&quot;&gt;
&lt;Route&gt;
&lt;RollingFile name=&quot;Rolling-${map:type}&quot; fileName=&quot;${filename}&quot;
filePattern=&quot;target/rolling1/test1-${map:type}.%i.log.gz&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;SizeBasedTriggeringPolicy size=&quot;500&quot; /&gt;
&lt;/RollingFile&gt;
&lt;/Route&gt;
&lt;/Routes&gt;
&lt;/Routing&gt;</pre></div>
</div>
<div class="section">
<h3><a name="Marker_Lookup"></a>Marker Lookup</h3>
<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>
<div>
<pre class="prettyprint linenums">
Configuration:
status: debug
Appenders:
Console:
RandomAccessFile:
- name: SQL_APPENDER
fileName: logs/sql.log
PatternLayout:
Pattern: &quot;%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n&quot;
- name: PAYLOAD_APPENDER
fileName: logs/payload.log
PatternLayout:
Pattern: &quot;%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n&quot;
- name: PERFORMANCE_APPENDER
fileName: logs/performance.log
PatternLayout:
Pattern: &quot;%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n&quot;
Routing:
name: ROUTING_APPENDER
Routes:
pattern: &quot;$${marker:}&quot;
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></div>
<div>
<pre class="prettyprint linenums">
public static final Marker SQL = MarkerFactory.getMarker(&quot;SQL&quot;);
public static final Marker PAYLOAD = MarkerFactory.getMarker(&quot;PAYLOAD&quot;);
public static final Marker PERFORMANCE = MarkerFactory.getMarker(&quot;PERFORMANCE&quot;);
final Logger logger = LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
logger.info(SQL, &quot;Message in Sql.log&quot;);
logger.info(PAYLOAD, &quot;Message in Payload.log&quot;);
logger.info(PERFORMANCE, &quot;Message in Performance.log&quot;);</pre></div>
<p>
Note the key part of the configuration is <tt>pattern: &quot;$${marker:}&quot;</tt>. This will produce three log files,
each with a log event for a specific marker. Log4j will route the log event with the <tt>SQL</tt> marker to
<tt>sql.log</tt>, the log event with the <tt>PAYLOAD</tt> marker to <tt>payload.log</tt>, and so on.
</p>
<p>
You can use the notation <tt>&quot;${marker:name}&quot;</tt> and <tt>&quot;$${marker:name}&quot;</tt> to check for the
existence of a marker where <tt>name</tt> is the marker name. If the marker exists, the expression returns
the name, otherwise <tt>null</tt>.
</p>
</div>
<a name="StructuredDataLookup"></a>
<div class="section">
<h3><a name="Structured_Data_Lookup"></a>Structured Data Lookup</h3>
<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 &quot;type&quot; is an attribute of the
<a href="../log4j-api/apidocs/org/apache/logging/log4j/message/StructuredDataMessage.html">StructuredDataMessage</a>
while &quot;type&quot; would have to be an item in the Map in a MapMessage.
</p>
<div>
<pre class="prettyprint linenums">
&lt;Routing name=&quot;Routing&quot;&gt;
&lt;Routes pattern=&quot;$${sd:type}&quot;&gt;
&lt;Route&gt;
&lt;RollingFile name=&quot;Rolling-${sd:type}&quot; fileName=&quot;${filename}&quot;
filePattern=&quot;target/rolling1/test1-${sd:type}.%i.log.gz&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;SizeBasedTriggeringPolicy size=&quot;500&quot; /&gt;
&lt;/RollingFile&gt;
&lt;/Route&gt;
&lt;/Routes&gt;
&lt;/Routing&gt;</pre></div>
</div>
<a name="SystemPropertiesLookup"></a>
<div class="section">
<h3><a name="System_Properties_Lookup"></a>System Properties Lookup</h3>
<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>
<div>
<pre class="prettyprint linenums">
&lt;Appenders&gt;
&lt;File name=&quot;ApplicationLog&quot; fileName=&quot;${sys:logPath}/app.log&quot;/&gt;
&lt;/Appenders&gt;</pre></div>
</div>
<a name="WebLookup"></a>
<div class="section">
<h3><a name="Web_Lookup"></a>Web Lookup</h3>
<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 border="0" class="bodyTable">
<tr class="a">
<th>Key</th>
<th>Description</th>
</tr>
<tr class="b">
<td>attr.<i>name</i></td>
<td>Returns the ServletContext attribute with the specified name</td>
</tr>
<tr class="a">
<td>contextPath</td>
<td>The context path of the web application</td>
</tr>
<tr class="b">
<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 class="a">
<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 class="b">
<td>initParam.<i>name</i></td>
<td>Returns the ServletContext initialization parameter with the specified name</td>
</tr>
<tr class="a">
<td>majorVersion</td>
<td>Returns the major version of the Servlet API that this servlet container supports.</td>
</tr>
<tr class="b">
<td>minorVersion</td>
<td>Returns the minor version of the Servlet API that this servlet container supports.</td>
</tr>
<tr class="a">
<td>rootDir</td>
<td>Returns the result of calling getRealPath with a value of &quot;/&quot;.</td>
</tr>
<tr class="b">
<td>serverInfo</td>
<td>Returns the name and version of the servlet container on which the servlet is running.</td>
</tr>
<tr class="a">
<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>
<div>
<pre class="prettyprint linenums">
&lt;Appenders&gt;
&lt;File name=&quot;ApplicationLog&quot; fileName=&quot;${web:rootDir}/app.log&quot;/&gt;
&lt;/Appenders&gt;</pre></div>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2017 <a class="external" href="https://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
<p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>