| <?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 Web Applications</title> |
| <author email="nickwilliams@apache.org">Nick Williams</author> |
| <author email="mattsicker@apache.org">Matt Sicker</author> |
| </properties> |
| |
| <body> |
| <section name="Using Log4j 2 in Web Applications"> |
| <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 "started" when |
| the web application deploys and "shut down" 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 <code>log4j-web</code> 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"> |
| <i class="icon-exclamation-sign"/> |
| To avoid problems the Log4j shutdown hook will automatically be disabled when the log4j-web jar is included. |
| </p> |
| <a name="Configuration"/> |
| <subsection name="Configuration"> |
| <p> |
| Log4j allows the configuration file to be specified in web.xml using the <code>log4jConfiguration</code> |
| context parameter. Log4j will search for configuration files by: |
| </p> |
| <ol> |
| <li> |
| If a location is provided it will be searched for as a servlet context resource. For example, if |
| <code>log4jConfiguration</code> contains "logging.xml" 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 "log4j2" in the WEB-INF directory. |
| If more than one file is found, and if a file that starts with "log4j2-<var>name</var>" is present, where |
| <var>name</var> is the name of the web application, then it will be used. Otherwise the first file will be |
| used. |
| </li> |
| <li> |
| The "normal" search sequence using the classpath and file URLs will be used to locate the configuration file. |
| </li> |
| </ol> |
| </subsection> |
| <subsection name="Servlet 3.0 and Newer Web Applications"> |
| <a name="Servlet-3.0" /> |
| <p> |
| A Servlet 3.0 or newer web application is any <code><web-app></code> whose <code>version</code> |
| attribute has a value of "3.0" 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> |
| <h4>The Short Story</h4> |
| <p> |
| Log4j 2 "just works" 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. Thanks to the |
| <a class="javadoc" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html">ServletContainerInitializer</a> |
| API added to Servlet 3.0, the relevant <code>Filter</code> and <code>ServletContextListener</code> classes |
| can be registered dynamically on web application startup. |
| </p> |
| <p> |
| <strong class="text-warning"><i class="icon-exclamation-sign"/> Important Note!</strong> |
| For performance reasons, containers often ignore certain JARs known not to |
| contain TLDs or <code>ServletContainerInitializer</code>s and do not scan them for web-fragments and |
| initializers. Importantly, Tomcat 7 <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 <7.0.43 you |
| will need to change <code>catalina.properties</code> and remove "log4j*.jar" from the <code>jarsToSkip</code> |
| property. You may need to do something similar on other containers if they skip scanning Log4j JAR files. |
| </p> |
| <h4>The Long Story</h4> |
| <p> |
| The Log4j 2 Web JAR file is a web-fragment configured to order before any other web fragments in your |
| application. It contains a <code>ServletContainerInitializer</code> |
| (<a class="javadoc" href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jServletContainerInitializer.html" |
| >Log4jServletContainerInitializer</a>) that the container automatically discovers and initializes. This adds |
| the <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html" |
| >Log4jServletContextListener</a> and |
| <a class="javadoc" href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html" |
| >Log4jServletFilter</a> to the <code>ServletContext</code>. 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 <code>isLog4jAutoInitializationDisabled</code> context parameter. Simply add it to your |
| deployment descriptor with the value "true" to disable auto-initialization. You <em>must</em> define the |
| context parameter in <code>web.xml</code>. If you set in programmatically, it will be too late for Log4j |
| to detect the setting. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ <context-param> |
| <param-name>isLog4jAutoInitializationDisabled</param-name> |
| <param-value>true</param-value> |
| </context-param>]]></pre> |
| <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 <code>log4jContextName</code>, |
| <code>log4jConfiguration</code>, and/or <code>isLog4jContextSelectorNamed</code> context parameters. Read more |
| about this in the <a href="#ContextParams">Context Parameters</a> section below. You <em>must not</em> |
| manually configure the <code>Log4jServletContextListener</code> or <code>Log4jServletFilter</code> in your |
| deployment descriptor (<code>web.xml</code>) or in another initializer or listener in a Servlet 3.0 or newer |
| application <em>unless you disable auto-initialization</em> with |
| <code>isLog4jAutoInitializationDisabled</code>. Doing so will result in startup errors and unspecified |
| erroneous behavior. |
| </p> |
| </subsection> |
| <subsection name="Servlet 2.5 Web Applications"> |
| <a name="Servlet-2.5" /> |
| <p> |
| A Servlet 2.5 web application is any <code><web-app></code> whose <code>version</code> attribute has a |
| value of "2.5." The <code>version</code> 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 |
| <code>version</code> attribute is "2.5." 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 <code>isLog4jAutoInitializationDisabled</code> context parameter, you <em>must</em> configure the |
| <a class="javadoc" href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html" |
| >Log4jServletContextListener</a> and |
| <a class="javadoc" href="../log4j-web/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 <code>web.xml</code> code: |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ <listener> |
| <listener-class>org.apache.logging.log4j.web.Log4jServletContextListener</listener-class> |
| </listener> |
| |
| <filter> |
| <filter-name>log4jServletFilter</filter-name> |
| <filter-class>org.apache.logging.log4j.web.Log4jServletFilter</filter-class> |
| </filter> |
| <filter-mapping> |
| <filter-name>log4jServletFilter</filter-name> |
| <url-pattern>/*</url-pattern> |
| <dispatcher>REQUEST</dispatcher> |
| <dispatcher>FORWARD</dispatcher> |
| <dispatcher>INCLUDE</dispatcher> |
| <dispatcher>ERROR</dispatcher> |
| <dispatcher>ASYNC</dispatcher><!-- Servlet 3.0 w/ disabled auto-initialization only; not supported in 2.5 --> |
| </filter-mapping>]]></pre> |
| <p> |
| You can customize the behavior of the listener and filter using the <code>log4jContextName</code>, |
| <code>log4jConfiguration</code>, and/or <code>isLog4jContextSelectorNamed</code> context parameters. Read more |
| about this in the <a href="#ContextParams">Context Parameters</a> section below. |
| </p> |
| </subsection> |
| <subsection name="Context Parameters"> |
| <a name="ContextParams" /> |
| <p> |
| By default, Log4j 2 uses the <code>ServletContext</code>'s |
| <a href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getServletContextName()">context name</a> |
| as the <code>LoggerContext</code> 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, |
| <code>isLog4jContextSelectorNamed</code>, specifies whether the context should be selected using the |
| <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JndiContextSelector.html" |
| >JndiContextSelector</a>. If <code>isLog4jContextSelectorNamed</code> is not specified or is anything other |
| than <code>true</code>, it is assumed to be <code>false</code>. |
| </p> |
| <p> |
| If <code>isLog4jContextSelectorNamed</code> is <code>true</code>, <code>log4jContextName</code> must be |
| specified or <code>display-name</code> must be specified in <code>web.xml</code>; otherwise, the application |
| will fail to start with an exception. <code>log4jConfiguration</code> |
| <em>should</em> 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 <code>isLog4jContextSelectorNamed</code> is not <code>true</code>, <code>log4jConfiguration</code> may |
| optionally be specified and must be a valid URI or path to a configuration file or start with "classpath:" 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 |
| (<code>web.xml</code>) even in a Servlet 3.0 or never application. If you add them to the |
| <code>ServletContext</code> 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> |
| <h4>Set the Logging Context Name to "myApplication"</h4> |
| <pre class="prettyprint linenums"><![CDATA[ <context-param> |
| <param-name>log4jContextName</param-name> |
| <param-value>myApplication</param-value> |
| </context-param>]]></pre> |
| <h4>Set the Configuration Path/File/URI to "/etc/myApp/myLogging.xml"</h4> |
| <pre class="prettyprint linenums"><![CDATA[ <context-param> |
| <param-name>log4jConfiguration</param-name> |
| <param-value>file:///etc/myApp/myLogging.xml</param-value> |
| </context-param>]]></pre> |
| <h4>Use the <code>JndiContextSelector</code></h4> |
| <pre class="prettyprint linenums"><![CDATA[ <context-param> |
| <param-name>isLog4jContextSelectorNamed</param-name> |
| <param-value>true</param-value> |
| </context-param> |
| <context-param> |
| <param-name>log4jContextName</param-name> |
| <param-value>appWithJndiSelector</param-value> |
| </context-param> |
| <context-param> |
| <param-name>log4jConfiguration</param-name> |
| <param-value>file:///D:/conf/myLogging.xml</param-value> |
| </context-param>]]></pre> |
| <p> |
| Note that in this case you must also set the "Log4jContextSelector" system property to |
| "<kbd>org.apache.logging.log4j.core.selector.JndiContextSelector</kbd>". |
| </p> |
| </subsection> |
| <subsection name="Using Web Application Information During the Configuration"> |
| <a name="WebLookup" /> |
| <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> |
| </subsection> |
| <subsection name="JavaServer Pages Logging"> |
| <a name="JspLogging" /> |
| <p> |
| You may use Log4j 2 within JSPs just as you would within any other Java code. Simple obtain a |
| <code>Logger</code> 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> |
| <strong class="text-warning"><i class="icon-exclamation-sign"/> Important Note!</strong> |
| As noted above, containers often ignore certain JARs known not to |
| contain TLDs and do not scan them for TLD files. Importantly, Tomcat 7 <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 <7.0.43 you |
| will need to change <code>catalina.properties</code> and remove "log4j*.jar" from the <code>jarsToSkip</code> |
| property. You may need to do something similar on other containers if they skip scanning Log4j JAR files. |
| </p> |
| </subsection> |
| <subsection name="Asynchronous Requests and Threads"> |
| <a name="Async" /> |
| <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 <code>Log4jServletFilter</code> binds the <code>LoggerContext</code> to the thread handling |
| the request. After request processing completes, the filter unbinds the <code>LoggerContext</code> from the |
| thread. |
| </p> |
| <p> |
| Similarly, when an internal request is dispatched using a <code>javax.servlet.AsyncContext</code>, the |
| <code>Log4jServletFilter</code> also binds the <code>LoggerContext</code> to the thread handling the request |
| and unbinds it when request processing completes. However, this only happens for requests <em>dispatched</em> |
| through the <code>AsyncContext</code>. There are other asynchronous activities that can take place other than |
| internal dispatched requests. |
| </p> |
| <p> |
| For example, after starting an <code>AsyncContext</code> you could start up a separate thread to process the |
| request in the background, possibly writing the response with the <code>ServletOutputStream</code>. 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 <code>isLog4jContextSelectorNamed</code> context |
| parameter, there is no need to bind the <code>LoggerContext</code> to the thread. Log4j can safely locate the |
| <code>LoggerContext</code> on its own. In these cases, the filter provides only very modest performance |
| gains, and only when creating new <code>Logger</code>s. However, if you <em>did</em> specify the |
| <code>isLog4jContextSelectorNamed</code> context parameter with the value "true", you will need to manually |
| bind the <code>LoggerContext</code> to asynchronous threads. Otherwise, Log4j will not be able to locate it. |
| </p> |
| <p> |
| Thankfully, Log4j provides a simple mechanism for binding the <code>LoggerContext</code> to asynchronous |
| threads in these special circumstances. The simplest way to do this is to wrap the <code>Runnable</code> |
| instance that is passed to the <code>AsyncContext.start()</code> method. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| 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(final HttpServletRequest req, final HttpServletResponse resp) throws ServletException, IOException { |
| final AsyncContext asyncContext = req.startAsync(); |
| asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(this.getServletContext(), new Runnable() { |
| @Override |
| public void run() { |
| final Logger logger = LogManager.getLogger(TestAsyncServlet.class); |
| logger.info("Hello, servlet!"); |
| } |
| })); |
| } |
| |
| @Override |
| protected void doPost(final HttpServletRequest req, final HttpServletResponse resp) throws ServletException, IOException { |
| final AsyncContext asyncContext = req.startAsync(); |
| asyncContext.start(new Runnable() { |
| @Override |
| public void run() { |
| final Log4jWebSupport webSupport = |
| WebLoggerContextUtils.getWebLifeCycle(TestAsyncServlet.this.getServletContext()); |
| webSupport.setLoggerContext(); |
| // do stuff |
| webSupport.clearLoggerContext(); |
| } |
| }); |
| } |
| } |
| ]]></pre> |
| <p> |
| This can be slightly more convenient when using Java 1.8 and lambda functions as demonstrated below. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| 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(), () -> { |
| final Logger logger = LogManager.getLogger(TestAsyncServlet.class); |
| logger.info("Hello, servlet!"); |
| })); |
| } |
| } |
| ]]></pre> |
| <p> |
| Alternatively, you can obtain the |
| <a class="javadoc" href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jWebLifeCycle.html">Log4jWebLifeCycle</a> |
| instance from the <code>ServletContext</code> attributes, call its <code>setLoggerContext</code> method as |
| the very first line of code in your asynchronous thread, and call its <code>clearLoggerContext</code> 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 |
| <code>Runnable</code> to the <code>start</code> method. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| 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("Hello, servlet!"); |
| } finally { |
| webLifeCycle.clearLoggerContext(); |
| } |
| } |
| }); |
| } |
| } |
| ]]></pre> |
| <p> |
| Note that you <em>must</em> call <code>clearLoggerContext</code> 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 <code>finally</code> block, which will always execute. |
| </p> |
| </subsection> |
| <subsection name="Using the Servlet Appender"> |
| <p> |
| Log4j provides a Servlet Appender that uses the servlet context as the log target. For example: |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <Configuration status="WARN" name="ServletTest"> |
| |
| <Appenders> |
| <Servlet name="Servlet"> |
| <PatternLayout pattern="%m%n%ex{none}"/> |
| </Servlet> |
| </Appenders> |
| |
| <Loggers> |
| <Root level="debug"> |
| <AppenderRef ref="Servlet"/> |
| </Root> |
| </Loggers> |
| |
| </Configuration>]]></pre> |
| <p> |
| To avoid double logging of exceptions to the servlet context, you must use <code>%ex{none}</code> in your |
| <code>PatternLayout</code> as shown in the example. The exception will be omitted from the message text but |
| it is passed to the servlet context as the actual Throwable object. |
| </p> |
| </subsection> |
| </section> |
| </body> |
| |
| </document> |
