Servlet 3.0 and Newer Web Applications

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.

The Short Story
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.

Important Note! 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.

The Long Story
The Log4j 2 Core JAR file is a web-fragment configured to order before any other web fragments in your application. It contains a ServletContainerInitializer (Log4jServletContainerInitializer) that the container automatically discovers and initializes. This adds the Log4jServletContextListener and Log4jServletFilter to the ServletContext. These classes properly initialize and deinitialize the Log4j configuration.

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 Context Parameters section below. You must not 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. Doing so will result in startup errors and unspecified erroneous behavior.

Servlet 2.5 Web Applications

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.

If you are using Log4j in a Servlet 2.5 web application, you must configure the Log4jServletContextListener and Log4jServletFilter in the deployment descriptor. The filter should match all requests of any type. The listener should be the very first listener defined in the deployment descriptor, and the filter should be the very first filter defined and mapped in the deployment descriptor. This is easily accomplished using the following web.xml code:

    <listener>
        <listener-class>org.apache.logging.log4j.core.web.Log4jServletContextListener</listener-class>
    </listener>

    <filter>
        <filter-name>log4jServletFilter</filter-name>
        <filter-class>org.apache.logging.log4j.core.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>
    </filter-mapping>

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 Context Parameters section below.

Context Parameters

By default, Log4j 2 uses the ServletContext's context name 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 JNDIContextSelector. If isLog4jContextSelectorNamed is not specified or is anything other than true, it is assumed to be false.

If isLog4jContextSelectorNamed is true, log4jContextName must be specified; otherwise, the application will fail to start with an exception. log4jConfiguration should also be specified in this case, and must be a valid URI for the configuration file; however, this parameter is not required.

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.

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.

Set the Logging Context Name to "myApplication"

    <context-param>
        <param-name>log4jContextName</param-name>
        <param-value>myApplication</param-value>
    </context-param>

Set the Configuration Path/File/URI to "/etc/myApp/myLogging.xml"

    <context-param>
        <param-name>log4jConfiguration</param-name>
        <param-value>file:///etc/myApp/myLogging.xml</param-value>
    </context-param>

Use the JNDIContextSelector

    <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>

JavaServer Pages Logging

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.

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, read the Log4j Tag Library documentation.

Important Note! 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.