Google Git
Sign in
apache / logging-log4j-site / refs/heads/asf-site-old / . / log4j-2.0.1 / manual / webapp.html
blob: 849c7a7fc18902af5e4a047e67e4d3c08cde9b62 [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 Jul 29, 2014 -->
<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 2 Web Applications - 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="Nick Williams" />
<meta name="author" content="Matt Sicker" />
<meta name="Date-Revision-yyyymmdd" content="20140729" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
<img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="http://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>
</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="none">
<a href="../maven-artifacts.html" title="Maven and Ivy">Maven and Ivy</a>
</li>
<li class="none">
<a href="../build.html" title="Build">Build</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>
<li class="none">
<a href="../changelog.html" title="Changelog">Changelog</a>
</li>
<li class="collapsed">
<a href="../javadoc.html" title="Javadoc">Javadoc</a>
</li>
<li class="none">
<a href="../faq.html" title="FAQ">FAQ</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="API">API</a>
</li>
<li class="collapsed">
<a href="../manual/configuration.html" title="Configuration">Configuration</a>
</li>
<li class="expanded active">
<a href="../manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a>
<ul>
<li class="none">
<a href="../manual/webapp.html#Servlet-3.0" title="Servlet 3.0 and Newer">Servlet 3.0 and Newer</a>
</li>
<li class="none">
<a href="../manual/webapp.html#Servlet-2.5" title="Servlet 2.5">Servlet 2.5</a>
</li>
<li class="none">
<a href="../manual/webapp.html#ContextParams" title="Context Parameters">Context Parameters</a>
</li>
<li class="none">
<a href="../manual/webapp.html#WebLookup" title="Configuration Lookups">Configuration Lookups</a>
</li>
<li class="none">
<a href="../manual/webapp.html#JspLogging" title="JavaServer Pages Logging">JavaServer Pages Logging</a>
</li>
<li class="none">
<a href="../manual/webapp.html#Async" title="Asynchronous Requests">Asynchronous Requests</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="../manual/plugins.html" title="Plugins">Plugins</a>
</li>
<li class="collapsed">
<a href="../manual/lookups.html" title="Lookups">Lookups</a>
</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="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/customconfig.html" title="Extending Log4j Configuration">Extending 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-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-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 NG Appender">Apache Flume NG 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-nosql/index.html" title="Log4j NoSQL support">Log4j NoSQL support</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>Using Log4j 2 in Web Applications<a name="Using_Log4j_2_in_Web_Applications"></a></h2>
<p>
You must take particular care when using Log4j or any other logging framework within a Java EE web application.
It's important for logging resources to be properly cleaned up (database connections closed, files closed, etc.)
when the container shuts down or the web application is undeployed. Because of the nature of class loaders
within web applications, Log4j resources cannot be cleaned up through normal means. Log4j must be &quot;started&quot; when
the web application deploys and &quot;shut down&quot; when the web application undeploys. How this works varies depending
on whether your application is a <a href="#Servlet-3.0">Servlet 3.0 or newer</a> or
<a href="#Servlet-2.5">Servlet 2.5</a> web application.
</p>
<p>
In either case, you'll need to add the <tt>log4j-web</tt> module to your deployment as detailed in the
<a href="../maven-artifacts.html">Maven, Ivy, and Gradle Artifacts</a> manual page.
</p>
<p class="big-red">
To avoid problems the Log4j shutdown hook will automatically be disabled when the log4j-web jar is included.
</p>
<a name="Configuration"></a>
<div class="section"><h3>Configuration<a name="Configuration"></a></h3>
<p>Log4j allows the configuration file to be specified in web.xml using the log4jConfiguration context parameter.
Log4j will search for configuration files by:
</p>
<ol style="list-style-type: decimal">
<li>If a location is provided it will be searched for as a servlet context resource. For example,
if log4jConfiguration contains &quot;logging.xml&quot; then Log4j will look for a file with that name in the
root directory of the web application.
</li>
<li>If no location is defined Log4j will search for a file that starts with &quot;log4j2&quot; in the WEB-INF directory.
If more than one file is found then if a file that starts with &quot;log4j2-<i>name</i>&quot;, where <i>name</i> is the
name of the web application, is present it will be used. Otherwise the first file will be used.
</li>
<li>The &quot;normal&quot; search sequence using the classpath and file URLs will be used to locate the configuration
file.
</li>
</ol>
</div>
<div class="section"><h3>Servlet 3.0 and Newer Web Applications<a name="Servlet_3.0_and_Newer_Web_Applications"></a></h3>
<a name="Servlet-3.0"></a>
<p>
A Servlet 3.0 or newer web application is any <tt>&lt;web-app&gt;</tt> whose <tt>version</tt>
attribute has a value of &quot;3.0&quot; or higher. Of course, the application must also be running in a compatible
web container. Some examples are: Tomcat 7.0 and higher, GlassFish 3.0 and higher, JBoss 7.0 and higher,
Oracle WebLogic 12c and higher, and IBM WebSphere 8.0 and higher.
</p>
<div class="section"><h4>The Short Story<a name="The_Short_Story"></a></h4>
<p>
Log4j 2 &quot;just works&quot; in Servlet 3.0 and newer web applications. It is capable of automatically starting when
the application deploys and shutting down when the application undeploys.
</p>
<p>
<b><i>Important Note!</i></b> For performance reasons, containers often ignore certain JARs known not to
contain TLDs or <tt>ServletContainerInitializer</tt>s and do not scan them for web-fragments and
initializers. Importantly, Tomcat 7 &lt;7.0.43 ignores all JAR files named log4j*.jar, which prevents this
feature from working. This has been fixed in Tomcat 7.0.43, Tomcat 8, and later. In Tomcat 7 &lt;7.0.43 you
will need to change <tt>catalina.properties</tt> and remove &quot;log4j*.jar&quot; from the <tt>jarsToSkip</tt>
property. You may need to do something similar on other containers if they skip scanning Log4j JAR files.
</p>
</div><div class="section"><h4>The Long Story<a name="The_Long_Story"></a></h4>
<p>
The Log4j 2 Core JAR file is a web-fragment configured to order before any other web fragments in your
application. It contains a <tt>ServletContainerInitializer</tt>
(<a href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContainerInitializer.html">Log4jServletContainerInitializer</a>) that the container automatically discovers and initializes. This adds
the <a href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html">Log4jServletContextListener</a> and
<a href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html">Log4jServletFilter</a> to the <tt>ServletContext</tt>. These classes properly initialize
and deinitialize the Log4j configuration.
</p>
<p>
For some users, automatically starting Log4j is problematic or undesirable. You can easily disable this
feature using the <tt>isLog4jAutoInitializationDisabled</tt> context parameter. Simply add it to your
deployment descriptor with the value &quot;true&quot; to disable auto-initialization. You <i>must</i> define the
context parameter in <tt>web.xml</tt>. If you set in programmatically, it will be too late for Log4j
to detect the setting.
</p>
<div class="prettyprint linenums"><pre> &lt;context-param&gt;
&lt;param-name&gt;isLog4jAutoInitializationDisabled&lt;/param-name&gt;
&lt;param-value&gt;true&lt;/param-value&gt;
&lt;/context-param&gt;</pre></div>
<p>
Once you disable auto-initialization, you must initialize Log4j as you would a
<a href="#Servlet-2.5">Servlet 2.5 web application</a>. You must do so in a way that this initialization
happens before any other application code (such as Spring Framework startup code) executes.
</p>
<p>
You can customize the behavior of the listener and filter using the <tt>log4jContextName</tt>,
<tt>log4jConfiguration</tt>, and/or <tt>isLog4jContextSelectorNamed</tt> context parameters. Read more
about this in the <a href="#ContextParams">Context Parameters</a> section below. You <i>must not</i>
manually configure the <tt>Log4jServletContextListener</tt> or <tt>Log4jServletFilter</tt> in your
deployment descriptor (<tt>web.xml</tt>) or in another initializer or listener in a Servlet 3.0 or newer
application <i>unless you disable auto-initialization</i> with
<tt>isLog4jAutoInitializationDisabled</tt>. Doing so will result in startup errors and unspecified
erroneous behavior.
</p>
</div></div>
<div class="section"><h3>Servlet 2.5 Web Applications<a name="Servlet_2.5_Web_Applications"></a></h3>
<a name="Servlet-2.5"></a>
<p>
A Servlet 2.5 web application is any <tt>&lt;web-app&gt;</tt> whose <tt>version</tt> attribute has a
value of &quot;2.5.&quot; The <tt>version</tt> attribute is the only thing that matters; even if the web application
is running in a Servlet 3.0 or newer container, it is a Servlet 2.5 web application if the
<tt>version</tt> attribute is &quot;2.5.&quot; Note that Log4j 2 does not support Servlet 2.4 and older web
applications.
</p>
<p>
If you are using Log4j in a Servlet 2.5 web application, or if you have disabled auto-initialization with
the <tt>isLog4jAutoInitializationDisabled</tt> context parameter, you <i>must</i> configure the
<a href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html">Log4jServletContextListener</a> and
<a href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html">Log4jServletFilter</a> in the deployment descriptor or programmatically. The filter should match all
requests of any type. The listener should be the very first listener defined in your application, and the
filter should be the very first filter defined and mapped in your application. This is easily accomplished
using the following <tt>web.xml</tt> code:
</p>
<div class="prettyprint linenums"><pre> &lt;listener&gt;
&lt;listener-class&gt;org.apache.logging.log4j.web.Log4jServletContextListener&lt;/listener-class&gt;
&lt;/listener&gt;
&lt;filter&gt;
&lt;filter-name&gt;log4jServletFilter&lt;/filter-name&gt;
&lt;filter-class&gt;org.apache.logging.log4j.web.Log4jServletFilter&lt;/filter-class&gt;
&lt;/filter&gt;
&lt;filter-mapping&gt;
&lt;filter-name&gt;log4jServletFilter&lt;/filter-name&gt;
&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;dispatcher&gt;REQUEST&lt;/dispatcher&gt;
&lt;dispatcher&gt;FORWARD&lt;/dispatcher&gt;
&lt;dispatcher&gt;INCLUDE&lt;/dispatcher&gt;
&lt;dispatcher&gt;ERROR&lt;/dispatcher&gt;
&lt;dispatcher&gt;ASYNC&lt;/dispatcher&gt;&lt;!-- Servlet 3.0 w/ disabled auto-initialization only; not supported in 2.5 --&gt;
&lt;/filter-mapping&gt;</pre></div>
<p>
You can customize the behavior of the listener and filter using the <tt>log4jContextName</tt>,
<tt>log4jConfiguration</tt>, and/or <tt>isLog4jContextSelectorNamed</tt> context parameters. Read more
about this in the <a href="#ContextParams">Context Parameters</a> section below.
</p>
</div>
<div class="section"><h3>Context Parameters<a name="Context_Parameters"></a></h3>
<a name="ContextParams"></a>
<p>
By default, Log4j 2 uses the <tt>ServletContext</tt>'s context name as the <tt>LoggerContext</tt> name
and uses the standard pattern for locating the Log4j configuration file. There are three context parameters
that you can use to control this behavior. The first, <tt>isLog4jContextSelectorNamed</tt>, specifies
whether the context should be selected using the
<a href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JndiContextSelector.html">JndiContextSelector</a>. If <tt>isLog4jContextSelectorNamed</tt> is not specified or is anything other
than <tt>true</tt>, it is assumed to be <tt>false</tt>.
</p>
<p>
If <tt>isLog4jContextSelectorNamed</tt> is <tt>true</tt>, <tt>log4jContextName</tt> must be
specified; otherwise, the application will fail to start with an exception. <tt>log4jConfiguration</tt>
<i>should</i> also be specified in this case, and must be a valid URI for the configuration file; however,
this parameter is not required.
</p>
<p>
If <tt>isLog4jContextSelectorNamed</tt> is not <tt>true</tt>, <tt>log4jConfiguration</tt> may
optionally be specified and must be a valid URI or path to a configuration file or start with &quot;classpath:&quot; to
denote a configuration file that can be found on the classpath. Without this parameter, Log4j will use the
standard mechanisms for locating the configuration file.
</p>
<p>
When specifying these context parameters, you must specify them in the deployment descriptor
(<tt>web.xml</tt>) even in a Servlet 3.0 or never application. If you add them to the
<tt>ServletContext</tt> within a listener, Log4j will initialize before the context parameters are
available and they will have no effect. Here are some sample uses of these context parameters.
</p>
<div class="section"><h4>Set the Logging Context Name to &quot;myApplication&quot;<a name="Set_the_Logging_Context_Name_to_myApplication"></a></h4>
<div class="prettyprint linenums"><pre> &lt;context-param&gt;
&lt;param-name&gt;log4jContextName&lt;/param-name&gt;
&lt;param-value&gt;myApplication&lt;/param-value&gt;
&lt;/context-param&gt;</pre></div>
</div><div class="section"><h4>Set the Configuration Path/File/URI to &quot;/etc/myApp/myLogging.xml&quot;<a name="Set_the_Configuration_PathFileURI_to_etcmyAppmyLogging.xml"></a></h4>
<div class="prettyprint linenums"><pre> &lt;context-param&gt;
&lt;param-name&gt;log4jConfiguration&lt;/param-name&gt;
&lt;param-value&gt;file:///etc/myApp/myLogging.xml&lt;/param-value&gt;
&lt;/context-param&gt;</pre></div>
</div><div class="section"><h4>Use the <tt>JndiContextSelector</tt><a name="Use_the_JndiContextSelector"></a></h4>
<div class="prettyprint linenums"><pre> &lt;context-param&gt;
&lt;param-name&gt;isLog4jContextSelectorNamed&lt;/param-name&gt;
&lt;param-value&gt;true&lt;/param-value&gt;
&lt;/context-param&gt;
&lt;context-param&gt;
&lt;param-name&gt;log4jContextName&lt;/param-name&gt;
&lt;param-value&gt;appWithJndiSelector&lt;/param-value&gt;
&lt;/context-param&gt;
&lt;context-param&gt;
&lt;param-name&gt;log4jConfiguration&lt;/param-name&gt;
&lt;param-value&gt;file:///D:/conf/myLogging.xml&lt;/param-value&gt;
&lt;/context-param&gt;</pre></div>
<p>
Note that in this case you must also set the &quot;Log4jContextSelector&quot; system property to
&quot;org.apache.logging.log4j.core.selector.JndiContextSelector.&quot;
</p>
</div></div>
<div class="section"><h3>Using Web Application Information During the Configuration<a name="Using_Web_Application_Information_During_the_Configuration"></a></h3>
<a name="WebLookup"></a>
<p>
You may want to use information about the web application during configuration. For example, you could embed
the web application's context path in the name of a Rolling File Appender. See WebLookup in
<a href="./lookups.html#WebLookup">Lookups</a> for more information.
</p>
</div>
<div class="section"><h3>JavaServer Pages Logging<a name="JavaServer_Pages_Logging"></a></h3>
<a name="JspLogging"></a>
<p>
You may use Log4j 2 within JSPs just as you would within any other Java code. Simple obtain a
<tt>Logger</tt> and call its methods to log events. However, this requires you to use Java code within
your JSPs, and some development teams rightly are not comfortable with doing this. If you have a dedicated
user interface development team that is not familiar with using Java, you may even have Java code disabled in
your JSPs.
</p>
<p>
For this reason, Log4j 2 provides a JSP Tag Library that enables you to log events without using any Java
code. To read more about using this tag library, <a href="../log4j-taglib/index.html">read the Log4j Tag
Library documentation.</a>
</p>
<p>
<b><i>Important Note!</i></b> As noted above, containers often ignore certain JARs known not to
contain TLDs and do not scan them for TLD files. Importantly, Tomcat 7 &lt;7.0.43 ignores all JAR files named
log4j*.jar, which prevents the JSP tag library from being automatically discovered. This does not affect
Tomcat 6.x and has been fixed in Tomcat 7.0.43, Tomcat 8, and later. In Tomcat 7 &lt;7.0.43 you
will need to change <tt>catalina.properties</tt> and remove &quot;log4j*.jar&quot; from the <tt>jarsToSkip</tt>
property. You may need to do something similar on other containers if they skip scanning Log4j JAR files.
</p>
</div>
<div class="section"><h3>Asynchronous Requests and Threads<a name="Asynchronous_Requests_and_Threads"></a></h3>
<a name="Async"></a>
<p>
The handling of asynchronous requests is tricky, and regardless of Servlet container version or configuration
Log4j cannot handle everything automatically. When standard requests, forwards, includes, and error resources
are processed, the <tt>Log4jServletFilter</tt> binds the <tt>LoggerContext</tt> to the thread handling
the request. After request processing completes, the filter unbinds the <tt>LoggerContext</tt> from the
thread.
</p>
<p>
Similarly, when an internal request is dispatched using a <tt>javax.servlet.AsyncContext</tt>, the
<tt>Log4jServletFilter</tt> also binds the <tt>LoggerContext</tt> to the thread handling the request
and unbinds it when request processing completes. However, this only happens for requests <i>dispatched</i>
through the <tt>AsyncContext</tt>. There are other asynchronous activities that can take place other than
internal dispatched requests.
</p>
<p>
For example, after starting an <tt>AsyncContext</tt> you could start up a separate thread to process the
request in the background, possibly writing the response with the <tt>ServletOutputStream</tt>. Filters
cannot intercept the execution of this thread. Filters also cannot intercept threads that you start in
the background during non-asynchronous requests. This is true whether you use a brand new thread or a thread
borrowed from a thread pool. So what can you do for these special threads?
</p>
<p>
You may not need to do anything. If you didn't use the <tt>isLog4jContextSelectorNamed</tt> context
parameter, there is no need to bind the <tt>LoggerContext</tt> to the thread. Log4j can safely locate the
<tt>LoggerContext</tt> on its own. In these cases, the filter provides only very modest performance
gains, and only when creating new <tt>Logger</tt>s. However, if you <i>did</i> specify the
<tt>isLog4jContextSelectorNamed</tt> context parameter with the value &quot;true&quot;, you will need to manually
bind the <tt>LoggerContext</tt> to asynchronous threads. Otherwise, Log4j will not be able to locate it.
</p>
<p>
Thankfully, Log4j provides a simple mechanism for binding the <tt>LoggerContext</tt> to asynchronous
threads in these special circumstances. The simplest way to do this is to wrap the <tt>Runnable</tt>
instance that is passed to the <tt>AsyncContext.start()</tt> method.
</p>
<div class="prettyprint linenums"><pre>
import java.io.IOException;
import javax.servlet.AsyncContext;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.web.WebLoggerContextUtils;
public class TestAsyncServlet extends HttpServlet {
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
final AsyncContext asyncContext = req.startAsync();
asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(getServletContext(), new Runnable() {
@Override
public void run() {
final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
logger.info(&quot;Hello, servlet!&quot;);
}
}));
}
}
</pre></div>
<p>
This can be slightly more convenient when using Java 1.8 and lambda functions as demonstrated below.
</p>
<div class="prettyprint linenums"><pre>
import java.io.IOException;
import javax.servlet.AsyncContext;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.web.WebLoggerContextUtils;
public class TestAsyncServlet extends HttpServlet {
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
final AsyncContext asyncContext = req.startAsync();
asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(this.getServletContext(), () -&gt; {
final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
logger.info(&quot;Hello, servlet!&quot;);
}));
}
}
</pre></div>
<p>
Alternatively, you can obtain the
<a href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jWebLifeCycle.html">Log4jWebLifeCycle</a>
instance from the <tt>ServletContext</tt> attributes, call its <tt>setLoggerContext</tt> method as
the very first line of code in your asynchronous thread, and call its <tt>clearLoggerContext</tt> method
as the very last line of code in your asynchronous thread. The following code demonstrates this. It uses the
container thread pool to execute asynchronous request processing, passing an anonymous inner
<tt>Runnable</tt> to the <tt>start</tt> method.
</p>
<div class="prettyprint linenums"><pre>
import java.io.IOException;
import javax.servlet.AsyncContext;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.web.Log4jWebLifeCycle;
import org.apache.logging.log4j.web.WebLoggerContextUtils;
public class TestAsyncServlet extends HttpServlet {
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
final AsyncContext asyncContext = req.startAsync();
asyncContext.start(new Runnable() {
@Override
public void run() {
final Log4jWebLifeCycle webLifeCycle =
WebLoggerContextUtils.getWebLifeCycle(TestAsyncServlet.this.getServletContext());
webLifeCycle.setLoggerContext();
try {
final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
logger.info(&quot;Hello, servlet!&quot;);
} finally {
webLifeCycle.clearLoggerContext();
}
}
});
}
}
</pre></div>
<p>
Note that you <i>must</i> call <tt>clearLoggerContext</tt> once your thread is finished
processing. Failing to do so will result in memory leaks. If using a thread pool, it can even disrupt the
logging of other web applications in your container. For that reason, the example here shows clearing the
context in a <tt>finally</tt> block, which will always execute.
</p>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2014 <a class="external" href="http://www.apache.org">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://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>