Summary

In the root hippo-cms7-project/pom.xml property <log4j.version>1.2.17</log4j.version> will be replaced with <log4j2.version>2.8.2</log4j2.version>. 

This triggers and requires a huge set of additional changes, affecting almost all our product projects, as well as our downstream Hippo implementation projects!

The details/impact of these changes will be described further below, most notably the changes (rewrite) needed for all log4j.xml configuration files, as well the sometimes needed changes in (end project) downstream pom.xml files.

While this upgrade from log4j1 to log4j2 definitely is required for our own product projects, it still will remain possible, at least for the next v12 release, for Hippo implementation projects to keep using log4j1 as their logging implementation. That will require some other changes which will be described in the online documentation.

Changes

Maven properties

<log4j.version>1.2.17</log4j.version>

is replaced with:

<log4j2.version>2.8.2</log4j2.version>

and along the way, the slf4j version also is bumped to the latest:

<slf4j.version>1.7.25</slf4j.version>

 Maven dependencies

<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

is replaced with:

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-api</artifactId>
  <version>${log4j2.version}</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-core</artifactId>
  <version>${log4j2.version}</version>
</dependency>

And the slf4j binding for log4j12:

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>

is replaced with the binding now provided directly by log4j2:

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-slf4j-impl</artifactId>
  <version>${log4j2.version}</version>
</dependency>

Furthermore, for supporting specific log4j1 backwards-compatible implementation code (compilation), or for 3rd party dependencies which directly/only use log4j1 as logger
the following dependency is also added (test scope only!) to the global dependency management:

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-1.2-api</artifactId>
  <version>${log4j2.version}</version>
  <scope>test</scope>
</dependency>

log4j2 configuration files

Log4j2 at startup now looks for a file named log4j2.xml instead of log4j.xml
Therefore all log4j.xml files (and derivates, like log4j-dev.xml and log4j-prod.xml) in the source trees have been renamed accordingly to log4j2.xml (and likewise log4j2-dev.xml and log4j2-prod.xml).

Besides the needed rewrite of the log4j configuration itself, for which the online log4j2 migration manual should be consulted,
the default log4j2-dev.xml and log4j2-prod.xml files provided by the hippo project archetype (see also below) can be reviewed and compared against the earlier log4j-dev.xml and log4j-prod.xml as a guideline.

Most notable changes are the new log4j2 filters provided by Hippo itself:

• the LookupFilter for context based filtering replacing the MdcOrJndiPropertyFilter, see -CMS-10709-
• the re-implemented StringMatchFilter used for unit tests, see -CMS-10710-

Log4j2 runtime parameters

The system parameter through which you can configure log4j2 to use a specific configuration file has also changed!

Instead of using:

-Dlog4j.configuration=<configuration file path>

you now need to use:

-Dlog4j.configurationFile=<configuration file path>

This is a required change for all deployed environments, for example in Tomcat setenv.sh.

Note: when using a file: reference to the configuration file, make sure to use the file:// prefix, not the shorter file: which did work with log4j1 but no longer works with log4j2 on Windows!
See CMS-10711 for more background.

In the cargo.run profile of the Hippo project archetype this results in the following change from the old log4j1 parameter configuration:

<log4j.configuration>file:${project.basedir}/conf/log4j-dev.xml</log4j.configuration>

to the new log4j2 parameter configuration (note again the required file:// prefix):

<log4j.configurationFile>file://${project.basedir}/conf/log4j2-dev.xml</log4j.configurationFile>

More specific changes in the Hippo project archetype are described further below.

In addition, 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 our standard LoggingServlet, through which you can dynamically change log level by default won't 'see' the aggregate of all existing log4j loggers.

To fix this, another new 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 for all cargo-maven2-plugin usages in the root hippo-cms7-project pom.xml, so doesn't need additional configuration changes for running Hippo using cargo. 

This is another required change (additional parameter to be set) for all deployed environments, again for example in Tomcat setenv.sh.

Hippo project archetype changes

For existing Hippo projects based on the Hippo project archetype, the following upgrade changes are needed:

Renamed and rewritten conf/log4j2-dev.xml conf/log4j2-prod.xml

The archetype now provides and uses these log4j2 based configuration files instead of the old conf/log4j-dev.xml and conf/log4j-prod.xml files.

The now obsolete log4j1 log4j.dtd has been removed. 

cargo-maven2-plugin configuration

As already mentioned before, within the project root pom.xml cargo-run profile the log4j1 log4j.configuration system property needs to be changed, 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 it is adviced to remove the rebel.log4j-plugin system property which no longer is functional (being log4j1 based).
Note: changing it to rebel.log4j2_plugin, which is supposed to work, doesn't seem to work anymore either.
A better and more generic solution is adding the attribute monitorInterval="5" to the log4j2 Configuration element in conf/log4j2-dev.xml, which is left to be decided by the project developers.

dist and dist-with-content distribution configuration changes

As the log4j2 dependencies are different, the configuration for building a distribution needs to be adjusted.

Within the project root pom.xml dist and (since v11) dist-with-content profiles, 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>
  ...

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

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

Hippo Development Changes

• -CMS-10708- The ExecuteOnLogLevel test utility has been dropped and replaced with Log4jInterceptor
• When using PowerMock, you need to use the @PowerMockIgnore("javax.management.")* annotation to prevent huge stacktrace dump reported from within log4j2!