| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/xdoc/manual/webapp.xml at 2020-05-10 |
| | Rendered using Apache Maven Fluido Skin 1.8 |
| --> |
| <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.9.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.8.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.8.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://logging.apache.org" id="bannerLeft"><img src="../images/ls-logo.jpg" alt=""/></a></div> |
| <div class="pull-right"><a href="http://logging.apache.org/log4j/2.x" id="bannerRight"><img src="../images/logo.png" alt=""/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2020-05-10<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.13.3</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="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="externalLink" title="Sonar">Sonar</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" 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="../javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</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="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../changelog.html" title="Changelog"><span class="none"></span>Changelog</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="none"></span>Security</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li> |
| <li><a href="../build.html" title="Building Log4j from Source"><span class="none"></span>Building Log4j from Source</a></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/book.png" alt="Manual" 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/compatibility.html" title="Log4j 1.x Compatibility"><span class="none"></span>Log4j 1.x Compatibility</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="none"></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="../manual/scala-api.html" 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 href="#"><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/tag.png" alt="Related Projects" border="0"/> Related Projects</li> |
| <li><a href="http://logging.apache.org/log4j/scala/index.html" class="externalLink" title="Log4j-Scala"><span class="none"></span>Log4j-Scala</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li> |
| <li><a href="http://logging.apache.org/log4j/1.2/" class="externalLink" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.3/" class="externalLink" title="Log4j 2.3 - Java 6"><span class="none"></span>Log4j 2.3 - Java 6</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.12.1" class="externalLink" title="Log4j 2.12.1 - Java 7"><span class="none"></span>Log4j 2.12.1 - Java 7</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" border="0"/> Components</li> |
| <li><a href="../log4j-api/index.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li> |
| <li><a href="../log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-jpl/index.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb2/index.html" title="Log4j MongoDB2 appender"><span class="none"></span>Log4j MongoDB2 appender</a></li> |
| <li><a href="../log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li> |
| <li><a href="../log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.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/info.png" alt="Project Information" border="0"/> Project Information</li> |
| <li><a href="../dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li> |
| <li><a href="../dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li> |
| <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li> |
| <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li> |
| <li><a href="../license.html" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="../source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li> |
| <li><a href="../changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li> |
| <li><a href="../jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li> |
| <li><a href="../rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <hr /> |
| <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> |
| In either case, you'll need to add the log4j-web 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 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 "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 <web-app> whose version |
| 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> |
| <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="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html">ServletContainerInitializer</a> |
| API added to Servlet 3.0, the relevant Filter and ServletContextListener 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 ServletContainerInitializers 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 catalina.properties and remove "log4j*.jar" from the jarsToSkip |
| 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 ServletContainerInitializer |
| (<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 ServletContext. 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 isLog4jAutoInitializationDisabled 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 web.xml. 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 log4jContextName, |
| log4jConfiguration, and/or isLog4jContextSelectorNamed context parameters. Read more |
| about this in the <a href="#ContextParams">Context Parameters</a> section below. You <i>must not</i> |
| manually configure the Log4jServletContextListener or Log4jServletFilter in your |
| deployment descriptor (web.xml) or in another initializer or listener in a Servlet 3.0 or newer |
| application <i>unless you disable auto-initialization</i> with |
| isLog4jAutoInitializationDisabled. 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 <web-app> whose version attribute has a |
| value of "2.5." The version 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 |
| version 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 isLog4jAutoInitializationDisabled 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 web.xml 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 log4jContextName, |
| log4jConfiguration, and/or isLog4jContextSelectorNamed 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 ServletContext's |
| <a class="externalLink" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getServletContextName()">context name</a> |
| as the LoggerContext 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, |
| isLog4jContextSelectorNamed, 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 isLog4jContextSelectorNamed is not specified or is anything other |
| than true, it is assumed to be false. |
| </p> |
| |
| <p> |
| If isLog4jContextSelectorNamed is true, log4jContextName must be |
| specified or display-name must be specified in web.xml; otherwise, the application |
| will fail to start with an exception. log4jConfiguration |
| <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 isLog4jContextSelectorNamed is not true, log4jConfiguration 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 |
| (web.xml) even in a Servlet 3.0 or never application. If you add them to the |
| ServletContext 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 JndiContextSelector</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> |
| </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. Simple obtain a |
| Logger 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></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 catalina.properties and remove "log4j*.jar" from the jarsToSkip |
| 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 Log4jServletFilter binds the LoggerContext to the thread handling |
| the request. After request processing completes, the filter unbinds the LoggerContext from the |
| thread. |
| </p> |
| |
| <p> |
| Similarly, when an internal request is dispatched using a javax.servlet.AsyncContext, the |
| Log4jServletFilter also binds the LoggerContext to the thread handling the request |
| and unbinds it when request processing completes. However, this only happens for requests <i>dispatched</i> |
| through the AsyncContext. There are other asynchronous activities that can take place other than |
| internal dispatched requests. |
| </p> |
| |
| <p> |
| For example, after starting an AsyncContext you could start up a separate thread to process the |
| request in the background, possibly writing the response with the ServletOutputStream. 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 isLog4jContextSelectorNamed context |
| parameter, there is no need to bind the LoggerContext to the thread. Log4j can safely locate the |
| LoggerContext on its own. In these cases, the filter provides only very modest performance |
| gains, and only when creating new Loggers. However, if you <i>did</i> specify the |
| isLog4jContextSelectorNamed context parameter with the value "true", you will need to manually |
| bind the LoggerContext to asynchronous threads. Otherwise, Log4j will not be able to locate it. |
| </p> |
| |
| <p> |
| Thankfully, Log4j provides a simple mechanism for binding the LoggerContext to asynchronous |
| threads in these special circumstances. The simplest way to do this is to wrap the Runnable |
| instance that is passed to the AsyncContext.start() 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 ServletContext attributes, call its setLoggerContext method as |
| the very first line of code in your asynchronous thread, and call its clearLoggerContext 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 |
| Runnable to the start 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 clearLoggerContext 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 finally 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 %ex{none} in your |
| PatternLayout 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-2020 <a class="external" href="http://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> |
| </body> |
| </html> |
