| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/xdoc/manual/webapp.xml at 2024-03-06 |
| | Rendered using Apache Maven Fluido Skin 1.11.2 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> |
| <meta name="author" content="Nick Williams" /> |
| <meta name="author" content="Matt Sicker" /> |
| <title>Log4j – Log4j 2 Web Applications</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.11.2.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.11.2.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="../../.." id="bannerLeft"><img src="../images/ls-logo.jpg" alt="" style="" /></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/logo.png" alt="" style="" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2024-03-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.23.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/home.png" alt="Apache Log4j™ 2" style="border: 0;" /> Apache Log4j™ 2</li> |
| <li><a href="../index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="../download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="../release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</a></li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="../performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="../articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="../security.html" title="Security"><span class="icon-chevron-right"></span>Security</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" style="border: 0;" /> Manual</li> |
| <li><a href="../manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="../manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="../manual/api-separation.html" title="API Separation"><span class="none"></span>API Separation</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></span>Log4j 1.x Migration</a></li> |
| <li><a href="../manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../../kotlin" title="Kotlin API"><span class="none"></span>Kotlin API</a></li> |
| <li><a href="../../scala" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="../manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="../manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li class="active"><a><span class="icon-chevron-down"></span>Web Applications and JSPs</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/webapp.html#Servlet-3.0" title="Servlet 3.0 and Newer"><span class="none"></span>Servlet 3.0 and Newer</a></li> |
| <li><a href="../manual/webapp.html#Servlet-2.5" title="Servlet 2.5"><span class="none"></span>Servlet 2.5</a></li> |
| <li><a href="../manual/webapp.html#ContextParams" title="Context Parameters"><span class="none"></span>Context Parameters</a></li> |
| <li><a href="../manual/webapp.html#WebLookup" title="Configuration Lookups"><span class="none"></span>Configuration Lookups</a></li> |
| <li><a href="../manual/webapp.html#JspLogging" title="JavaServer Pages Logging"><span class="none"></span>JavaServer Pages Logging</a></li> |
| <li><a href="../manual/webapp.html#Async" title="Asynchronous Requests"><span class="none"></span>Asynchronous Requests</a></li> |
| </ul></li> |
| <li><a href="../manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="../manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li><a href="../manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li><a href="../manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="../manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="../manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="../manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="../manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="../manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="../manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="../manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="../manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" style="border: 0;" /> For Contributors</li> |
| <li><a href="../guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="../javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" style="border: 0;" /> Components</li> |
| <li><a href="../log4j-api.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-jcl.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-jpl.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="../log4j-to-slf4j.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-jakarta-web.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li> |
| <li><a href="../log4j-appserver.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb3.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-mongodb4.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li> |
| <li><a href="../log4j-cassandra.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-docker.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-kubernetes.html" title="Log4j Kubernetes Support"><span class="none"></span>Log4j Kubernetes Support</a></li> |
| <li><a href="../log4j-spring-boot.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li> |
| <li><a href="../log4j-spring-cloud-config-client.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/tag.png" alt="Related Projects" style="border: 0;" /> Related Projects</li> |
| <li><a href="../../../chainsaw/2.x/index.html" title="Chainsaw"><span class="none"></span>Chainsaw</a></li> |
| <li><a href="../../../log4cxx/latest_stable/index.html" title="Log4Cxx"><span class="none"></span>Log4Cxx</a></li> |
| <li><a href="../../../log4j-audit/latest/index.html" title="Log4j Audit"><span class="none"></span>Log4j Audit</a></li> |
| <li><a href="../../kotlin" title="Log4j Kotlin"><span class="none"></span>Log4j Kotlin</a></li> |
| <li><a href="../../scala" title="Log4j Scala"><span class="none"></span>Log4j Scala</a></li> |
| <li><a href="../../transform" title="Log4j Transform"><span class="none"></span>Log4j Transform</a></li> |
| <li><a href="../../../log4net/index.html" title="Log4Net"><span class="none"></span>Log4Net</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" style="border: 0;" /> Legacy Sites</li> |
| <li><a href="../../log4j-2.12.4/" title="Log4j 2.12.4 - Java 7"><span class="none"></span>Log4j 2.12.4 - Java 7</a></li> |
| <li><a href="../../log4j-2.3.2/" title="Log4j 2.3.2 - Java 6"><span class="none"></span>Log4j 2.3.2 - Java 6</a></li> |
| <li><a href="../../1.2/" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" style="border: 0;" /> Project Information</li> |
| <li><a href="../team.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="https://github.com/apache/logging-log4j2" class="externalLink" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="none"></span>Javadoc</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| <section> |
| <h2><a name="Using_Log4j_2_in_Web_Applications"></a>Using Log4j 2 in Web Applications</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 "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> |
| Due to the namespace change from <code>javax</code> to <code>jakarta</code> you need to use |
| <code>log4j-jakarta-web</code> instead of <code>log4j-web</code> for Servlet 5.0 or newer. |
| </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></i> |
| To avoid problems the Log4j shutdown hook will automatically be disabled when the log4j-web jar is included. |
| </p> |
| <a name="Configuration"></a> |
| <section> |
| <h3><a name="Configuration"></a>Configuration</h3> |
| |
| <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 style="list-style-type: decimal"> |
| |
| <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> |
| </section> |
| <section> |
| <h3><a name="Servlet_3.0_and_Newer_Web_Applications"></a>Servlet 3.0 and Newer Web Applications</h3> |
| <a name="Servlet-3.0"></a> |
| |
| <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. |
| </p> |
| |
| <p> |
| Some examples are: |
| </p> |
| |
| <ul> |
| |
| <li>Tomcat 7.0 and higher</li> |
| |
| <li>GlassFish 3.0 and higher</li> |
| |
| <li>JBoss 7.0 and higher</li> |
| |
| <li>Oracle WebLogic 12c and higher</li> |
| |
| <li>IBM WebSphere 8.0 and higher</li> |
| </ul> |
| <section> |
| <h4><a name="The_Short_Story"></a>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="https://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> |
| <b><i></i> Important Note!</b> |
| 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> |
| </section><section> |
| <h4><a name="The_Long_Story"></a>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 href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jServletContainerInitializer.html" class="javadoc">Log4jServletContainerInitializer</a>) that the container automatically discovers and initializes. This adds |
| the <a href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html" class="javadoc">Log4jServletContextListener</a> and |
| <a href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html" class="javadoc">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 <i>must</i> 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> |
| |
| <div> |
| <pre class="prettyprint linenums"> <context-param> |
| <param-name>isLog4jAutoInitializationDisabled</param-name> |
| <param-value>true</param-value> |
| </context-param></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 <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 <i>must not</i> |
| 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 <i>unless you disable auto-initialization</i> with |
| <code>isLog4jAutoInitializationDisabled</code>. Doing so will result in startup errors and unspecified |
| erroneous behavior. |
| </p> |
| </section></section> |
| <section> |
| <h3><a name="Servlet_2.5_Web_Applications"></a>Servlet 2.5 Web Applications</h3> |
| <a name="Servlet-2.5"></a> |
| |
| <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 <i>must</i> configure the |
| <a href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html" class="javadoc">Log4jServletContextListener</a> and |
| <a href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html" class="javadoc">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> |
| |
| <div> |
| <pre class="prettyprint linenums"> <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></div> |
| |
| <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> |
| </section> |
| <section> |
| <h3><a name="Context_Parameters"></a>Context Parameters</h3> |
| <a name="ContextParams"></a> |
| |
| <p> |
| By default, Log4j 2 uses the <code>ServletContext</code>'s |
| <a class="externalLink" href="https://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 href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JndiContextSelector.html" class="javadoc">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> |
| <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 <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> |
| <section> |
| <h4><a name="Set_the_Logging_Context_Name_to_.22myApplication.22"></a>Set the Logging Context Name to "myApplication"</h4> |
| |
| <div> |
| <pre class="prettyprint linenums"> <context-param> |
| <param-name>log4jContextName</param-name> |
| <param-value>myApplication</param-value> |
| </context-param></pre></div> |
| </section><section> |
| <h4><a name="Set_the_Configuration_Path.2FFile.2FURI_to_.22.2Fetc.2FmyApp.2FmyLogging.xml.22"></a>Set the Configuration Path/File/URI to "/etc/myApp/myLogging.xml"</h4> |
| |
| <div> |
| <pre class="prettyprint linenums"> <context-param> |
| <param-name>log4jConfiguration</param-name> |
| <param-value>file:///etc/myApp/myLogging.xml</param-value> |
| </context-param></pre></div> |
| </section><section> |
| <h4><a name="Use_the_JndiContextSelector"></a>Use the <code>JndiContextSelector</code></h4> |
| |
| <div> |
| <pre class="prettyprint linenums"> <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></div> |
| |
| <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> |
| |
| <p>For security reasons, from Log4j 2.17.0, JNDI must be enabled by setting system property <code>log4j2.enableJndiContextSelector=true</code>.</p> |
| </section></section> |
| <section> |
| <h3><a name="Using_Web_Application_Information_During_the_Configuration"></a>Using Web Application Information During the Configuration</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> |
| </section> |
| <section> |
| <h3><a name="JavaServer_Pages_Logging"></a>JavaServer Pages Logging</h3> |
| <a name="JspLogging"></a> |
| |
| <p> |
| You may use Log4j 2 within JSPs just as you would within any other Java code. Simply 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 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></i> Important Note!</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 <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> |
| </section> |
| <section> |
| <h3><a name="Asynchronous_Requests_and_Threads"></a>Asynchronous Requests and Threads</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 <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 <i>dispatched</i> |
| 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 <i>did</i> 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> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| 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></div> |
| |
| <p> |
| This can be slightly more convenient when using Java 1.8 and lambda functions as demonstrated below. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| 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></div> |
| |
| <p> |
| Alternatively, you can obtain the |
| <a href="../log4j-web/apidocs/org/apache/logging/log4j/web/Log4jWebLifeCycle.html" class="javadoc">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> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| 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></div> |
| |
| <p> |
| Note that you <i>must</i> 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> |
| </section> |
| <section> |
| <h3><a name="Using_the_Servlet_Appender"></a>Using the Servlet Appender</h3> |
| |
| <p> |
| Log4j provides a Servlet Appender that uses the servlet context as the log target. For example: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <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></div> |
| |
| <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> |
| </section> |
| </section> |
| |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2024 <a class="external" href="https://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| <script> |
| if(anchors) { |
| anchors.add(); |
| } |
| </script> |
| </body> |
| </html> |
