Upgrade from log4j to log4j2

As part of the upgrade from version 11 to 12, Hippo CMS moved from using log4j to log4j2. This change triggers a few actions on Hippo projects upgrading to CMS 12.

Rename and rewrite logging configuraton

Before version 12, the Hippo archetype generated the files conf/log4j-dev.xml and conf/log4j-prod.xml. These files can best be renamed to conf/log4j2-dev.xml and conf/log4j2-prod.xml respectively.

Their content needs to be rewritten to the log4j2 format. We recommend consulting the online log4j2 migration manual. Also, for reference and inspiration, you may want to check out the log4j2 files generated by a fresh CMS 12 archetype.

After the migration, the file conf/log4j.dtd is obsolete and should be removed from the project.

MdcOrJndiPropertyFilter has been dropped and replaced with the LookupFilter.

Before:

<filter class="org.onehippo.cms7.logging.log4j.MdcOrJndiPropertyFilter">
    <param name="name" value="logging/contextName" />
    <param name="resourceRef" value="true" />
    <param name="value" value="cms" />
    <param name="onMatchOption" value="ACCEPT" />
</filter>

After:

<LookupFilter key="jndi:logging/contextName" value="cms" onMatch="ACCEPT"/>

Adjust cargo configuration

In the project's root pom.xml, the configuration of the cargo-maven2-plugin specifies which logging configuration file to use when running the project locally. This configuration should be adjusted from:

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    <configuration>
    ...
    <container>
      <systemProperties>
        <log4j.configuration>file:${project.basedir}/conf/log4j-dev.xml</log4j.configuration>
        <rebel.log4j-plugin>true</rebel.log4j-plugin>
        ...

to:

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    <configuration>
    ...
    <container>
      <systemProperties>
        <log4j.configurationFile>file://${project.basedir}/conf/log4j2-dev.xml</log4j.configurationFile>
        ...

In addition we recommend to remove the rebel.log4j-plugin system property, which is no longer functional with log4j2. Using its log4j2 counterpart rebel.log4j2_plugin doesn't seem to work reliably; instead, as a more generic solution, we recommend adding the attribute monitorInterval="5" to the <Configuration> element in conf/log4j2-dev.xml.

Update the distribution file(s)

Since log4j2 comes with a different set of dependencies than log4j, the configuration for building  a distribution needs to be adjusted.

In the dist and (since v11) dist-with-content profiles of the project's root pom.xml, replace the log4j1 specific dependencies:

<profile>
  <id>dist</id>
  <dependencies>
    ...
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
      <scope>provided</scope>
      </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>jcl-over-slf4j</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
      <scope>provided</scope>
    </dependency>
    ...
  </dependencies>
  ...

with:

<profile>
  <id>dist</id>
  <dependencies>
    ...
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-slf4j-impl</artifactId>
      <scope>provided</scope>
      </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>jcl-over-slf4j</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-api</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-core</artifactId>
      <scope>provided</scope>
    </dependency>
    ...
  </dependencies>
  ...

For the Maven assembly configuration, two more changes are needed.

• in src/main/assembly/conf-component.xml replace:

  <files>
    <file>
      <source>conf/log4j-dist.xml</source>
      <outputDirectory>conf</outputDirectory>
      <destName>log4j.xml</destName>
    </file>
    <file>
      <source>conf/log4j.dtd</source>
      <outputDirectory>conf</outputDirectory>
      <destName>log4j.dtd</destName>
    </file>
    ...

  with:

  <files>
    <file>
      <source>conf/log4j2-dist.xml</source>
      <outputDirectory>conf</outputDirectory>
      <destName>log4j2.xml</destName>
    </file>
    ...

• in src/main/assembly/shared-lib-component.xml replace:

  <includes>
    ...
    <include>org.slf4j:slf4j-log4j12</include>
    <include>log4j:log4j</include>
    ...
  </includes>

  with:

  <includes>
    ...
    <include>org.apache.logging.log4j:log4j-slf4j-impl</include>
    <include>org.apache.logging.log4j:log4j-api</include>
    <include>org.apache.logging.log4j:log4j-core</include>
    ...
  </includes>

Adjust the Context Selector

The way the log4j2 LogManager works in multi 'context' environments has changed (by default). Effectively, this means that, by default, separate logging contexts are maintained per web application when Hippo is deployed.
This also means that Hippo's standard LoggingServlet, through which you can dynamically change log levels won't 'see' the aggregate of all existing log4j loggers by default. To fix this, a system parameter needs to be set to change the default log4j2 behavior:

-DLog4jContextSelector=org.apache.logging.log4j.core.selector.BasicContextSelector

See the log4j2 Logging Separation manual for additional background.

This parameter is already configured through the project's parent POM (hippo-cms7-project), so no change is necessary for running locally. But you may need to add this configuration for non-local deployment environments, for example into the Tomcat setenv.sh.