Tomcat components

The tomcat-log4j artifact contains Tomcat classloaders that delegate the Log4j API classes to the parent.

Classloaders

One of the main obstacles to the usage of Log4j as a global logging backend for the server and all applications is the Servlet API parent-last delegation model:

The container should not allow applications to override or access the container’s implementation classes. It is recommended also that the application class loader be implemented so that classes and resources packaged within the WAR are loaded in preference to classes and resources residing in container-wide library JARs.

Servlet API Specification 10.7.2

This delegation model implies that applications that ship with their own copy of Log4j API will not use the global logging backend. The tomcat-log4j artifact contains two classloaders that solve this problem by always looking for Log4j API in the parent classloader first.

Installation

To use a global Log4j API for all web applications, you need to:

Click here for a definition of CATALINA_BASE and CATALINA_HOME

A Tomcat installation can be split in two separate folders:

CATALINA_HOME: This is the folder that contains the code of the server and the default configuration of Tomcat instances.
CATALINA_BASE: This is the folder that contains the runtime configuration and working directories of a specific Tomcat instance.

The typical location of these folders varies between OSes:

Debian: On Debian and derived GNU/Linux distributions CATALINA_BASE is located in the /var/lib folder (e.g. /var/lib/tomcat10). CATALINA_HOME on the other hand is located in /usr/share (e.g. /usr/share/tomcat10).
Windows: If you installed Tomcat from the MSI package, both CATALINA_BASE and CATALINA_HOME point to the same subfolder of C:\Program Files\Apache Software Foundation, e.g. C:\Program Files\Apache Software Foundation/Tomcat 10.1.

Install Log4j API in either the system or common Tomcat classloader:
- If you wish to replace at the same time Tomcat’s logging subsystem, follow the Bridge installation instructions.
- If you do not with to replace Tomcat’s logging subsystem, add the log4j-api-2.23.1.jar artifact and a Log4j API implementation to the $CATALINA_BASE/lib folder of your Tomcat instance. You can download the artifact from this Maven Central location. See Installing a logging implementation for details on how to install the implementation.
Add the tomcat-log4j-3.0.0-beta1.jar artifact to the $CATALINA_BASE/lib folder of your Tomcat installation. You can download the artifact from this Maven Central location.

Configure the context of each web application to use eu.copernik.tomcat.log4j.loader.Log4jParallelWebappClassLoader as classloader. You can do it by modifying the $CATALINA_BASE/conf/context.xml file to include a properly configured Loader element:

<?xml version="1.0" encoding="UTF-8"?>
<Context>
  <!-- Default set of monitored resources. If one of these changes, the    -->
  <!-- web application will be reloaded.                                   -->
  <WatchedResource>WEB-INF/web.xml</WatchedResource>
  <WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>
  <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>

  <!-- Uncomment this to enable session persistence across Tomcat restarts -->
  <!--
  <Manager pathname="SESSIONS.ser" />
  -->

  <!-- Use global Log4j API installation -->
  (1)
  <Loader loaderClass="eu.copernik.tomcat.log4j.loader.Log4jParallelWebappClassLoader"/>
</Context>

1	Specifies an alternative classloader to use.

See Defining a context in Tomcat documentation for more ways to define the context of a web application.