////
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
////
= Migrating from Log4j 1.x
Ralph Goers <rgoers@apache.org>

++++
<link rel="stylesheet" type="text/css" href="../css/tables.css">
++++

[#Log4j1.2Bridge]
== When to use this the Log4j 1.x bridge

This bridge is useful as a dependency of an "application" which would like to use Log4j v2 as its main logging framework, if either that application itself hasn't been changed from using the Log4j 1.x API to the 1.x API, or if such an application depends on one or several (perhaps old) libraries that are "out of your control", and which themselves still contain code and thus a compile dependency on Log 1.x only. 

Once you have migrated all of your own application & library code under your control, you may not need this bridge. Note that when you use a library/framework that can be configured to use several logging frameworks, then you typically don't need this bridge either anymore, as you may be able to directly configure it to use Log4j v2 instead v1.  Some libraries/frameworks even auto-detect the presence of certain logging framework implementations on their classpath, and automagically switch their internal logging delegation accordingly; try simple removing the Log4j v1 dependency instead of replacing it with this bridge, and test if logging from all of your depenencies still work.

If you own or can contribute open source to the library you depend on, then you likely would prefer replacing its use of the Log4j v1 Logging API with the v2 API. (It typically does not make sense for libraries to depend on this bridge and support both the v1 and v2 Log4j API, because end-users of such a library would still have to replace their Log4j configuration v1 with a different v2 config anyway; see below.)

== Using the Log4j 1.x bridge

Perhaps the simplest way to convert to using Log4j 2 is to replace the
log4j 1.x jar file with Log4j 2's `log4j-1.2-api.jar`. However, to use
this successfully applications must meet the following requirements:

1.  They must not access methods and classes internal to the Log4j 1.x
implementation such as `Appender`s, `LoggerRepository` or `Category`'s
`callAppenders` method.
2.  They must not programmatically configure Log4j.
3.  They must not configure by calling the classes `DOMConfigurator` or
`PropertyConfigurator`.

== Converting to the Log4j 2 API

For the most part, converting from the Log4j 1.x API to Log4j 2 should
be fairly simple. Many of the log statements will require no
modification. However, where necessary the following changes must be
made.

.  The main package in version 1 is `org.apache.log4j`, in version 2 it
is `org.apache.logging.log4j`
.  Calls to `org.apache.log4j.Logger.getLogger()` must be modified to
`org.apache.logging.log4j.LogManager.getLogger()`.
.  Calls to `org.apache.log4j.Logger.getRootLogger()` or
`org.apache.log4j.LogManager.getRootLogger()` must be replaced with
`org.apache.logging.log4j.LogManager.getRootLogger()`.
.  Calls to `org.apache.log4j.Logger.getLogger` that accept a
`LoggerFactory` must remove the `org.apache.log4j.spi.LoggerFactory` and
use one of Log4j 2's other extension mechanisms.
.  Replace calls to `org.apache.log4j.Logger.getEffectiveLevel()` with
`org.apache.logging.log4j.Logger.getLevel()`.
.  Remove calls to `org.apache.log4j.LogManager.shutdown()`, they are
not needed in version 2 because the Log4j Core now automatically adds a
JVM shutdown hook on start up to perform any Core clean ups.
..  Starting in Log4j 2.1, you can specify a custom
link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html[`ShutdownCallbackRegistry`]
to override the default JVM shutdown hook strategy.
..  Starting in Log4j 2.6, you can now use
`org.apache.logging.log4j.LogManager.shutdown()` to initiate shutdown
manually.
.  Calls to `org.apache.log4j.Logger.setLevel()` or similar methods are
not supported in the API. Applications should remove these. Equivalent
functionality is provided in the Log4j 2 implementation classes, see
`org.apache.logging.log4j.core.config.Configurator.setLevel()`, but may
leave the application susceptible to changes in Log4j 2 internals.
.  Where appropriate, applications should convert to use parameterized
messages instead of String concatenation.
.  http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html[`org.apache.log4j.MDC`]
and
http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/NDC.html[`org.apache.log4j.NDC`]
have been replaced by the link:thread-context.html[Thread Context].

== Configuring Log4j 2

Although the Log4j 2 configuration syntax is different than that of
Log4j 1.x, most, if not all, of the same functionality is available.

Note that system property interpolation via the `${foo}` syntax has been
extended to allow property lookups from many different sources. See the
link:lookups.html[Lookups] documentation for more details. For example,
using a lookup for the system property named `catalina.base`, in Log4j
1.x, the syntax would be `${catalina.base}`. In Log4j 2, the syntax
would be `${sys:catalina.base}`.

The Log4j 1 `XmlLayout` can be emulated using the `Log4j1XmlLayout` provided by the `log4j-1.2-api` module of Log4j 2.
The Log4j 1 `SimpleLayout` and `TTCCLayout` can be emulated using the Log4j 2 `PatternLayout` configured with `%level - %m%n` and `%r [%t] %p %c %notEmpty\{%ndc }- %m%n` patterns, respectively.

Both `PatternLayout` and `EnhancedPatternLayout` in Log4j 1.x can be
replaced with `PatternLayout` in Log4j 2. The log4j-1.2-api module
contains two pattern conversions "%ndc" and "%properties" which can be
used to emulate "%x" and "%X" in Log4j 1.x PatternLayout ("%x" and %X"
in Log4j 2 have a slightly different format).

Below are the example configurations for Log4j 1.x and their
counterparts in Log4j 2.

=== Sample 1 - Simple configuration using a Console Appender

Log4j 1.x XML configuration

.log4j.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
  <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <category name="org.apache.log4j.xml">
    <priority value="info" />
  </category>
  <Root>
    <priority value ="debug" />
    <appender-ref ref="STDOUT" />
  </Root>
</log4j:configuration>
----

Log4j 2 XML configuration

.log4j2.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
  <Appenders>
    <Console name="STDOUT" target="SYSTEM_OUT">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="org.apache.log4j.xml" level="info"/>
    <Root level="debug">
      <AppenderRef ref="STDOUT"/>
    </Root>
  </Loggers>
</Configuration>
----

=== Sample 2 - Simple configuration using a File Appender, XMLLayout and SimpleLayout

Log4j 1.x XML configuration

.log4j.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
  <appender name="A1" class="org.apache.log4j.FileAppender">
    <param name="File"   value="A1.log" />
    <param name="Append" value="false" />
    <layout class="org.apache.log4j.xml.XMLLayout" />
  </appender>
  <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.SimpleLayout" />
  </appender>
  <category name="org.apache.log4j.xml">
    <priority value="debug" />
    <appender-ref ref="A1" />
  </category>
  <root>
    <priority value ="debug" />
    <appender-ref ref="STDOUT" />
  </Root>
</log4j:configuration>
----

Log4j 2 XML configuration

.log4j2.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
  <Appenders>
    <File name="A1" fileName="A1.log" append="false">
      <Log4j1XmlLayout />
    </File>
    <Console name="STDOUT" target="SYSTEM_OUT">
      <PatternLayout pattern="%level - %m%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="org.apache.log4j.xml" level="debug">
      <AppenderRef ref="A1"/>
    </Logger>
    <Root level="debug">
      <AppenderRef ref="STDOUT"/>
    </Root>
  </Loggers>
</Configuration>
----

=== Sample 3 - SocketAppender

Log4j 1.x XML configuration. This example from Log4j 1.x is misleading.
The SocketAppender does not actually use a Layout. Configuring one will
have no effect.

.log4j.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
  <appender name="A1" class="org.apache.log4j.net.SocketAppender">
    <param name="RemoteHost" value="localhost"/>
    <param name="Port" value="5000"/>
    <param name="LocationInfo" value="true"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
    </layout>
  </appender>
  <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <category name="org.apache.log4j.xml">
    <priority value="debug"/>
    <appender-ref ref="A1"/>
  </category>
  <root>
    <priority value="debug"/>
    <appender-ref ref="STDOUT"/>
  </Root>
</log4j:configuration>
----

Log4j 2 XML configuration

.log4j2.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
  <Appenders>
    <Socket name="A1" host="localHost" port="5000">
      <PatternLayout pattern="%t %-5p %c{2} - %m%n"/>
    </Socket>
    <Console name="STDOUT" target="SYSTEM_OUT">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="org.apache.log4j.xml" level="debug">
      <AppenderRef ref="A1"/>
    </Logger>
    <Root level="debug">
      <AppenderRef ref="STDOUT"/>
    </Root>
  </Loggers>
</Configuration>
----

=== Sample 4 - AsyncAppender and TTCCLayout

Log4j 1.x XML configuration using the AsyncAppender.

.log4j.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
  <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
    <appender-ref ref="TEMP"/>
  </appender>
  <appender name="TEMP" class="org.apache.log4j.FileAppender">
    <param name="File" value="temp"/>
    <layout class="org.apache.log4j.TTCCLayout">
      <param name="ThreadPrinting" value="true"/>
      <param name="CategoryPrefixing" value="true"/>
      <param name="ContextPrinting" value="true"/>
    </layout>
  </appender>
  <root>
    <priority value="debug"/>
    <appender-ref ref="ASYNC"/>
  </Root>
</log4j:configuration>
----

Log4j 2 XML configuration.

.log4j2.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="debug">
  <Appenders>
    <File name="TEMP" fileName="temp">
      <PatternLayout pattern="%r [%t] %p %c %notEmpty{%ndc }- %m%n"/>
    </File>
    <Async name="ASYNC">
      <AppenderRef ref="TEMP"/>
    </Async>
  </Appenders>
  <Loggers>
    <Root level="debug">
      <AppenderRef ref="ASYNC"/>
    </Root>
  </Loggers>
</Configuration>
----

=== Sample 5 - AsyncAppender with Console and File

Log4j 1.x XML configuration using the AsyncAppender.

.log4j.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
  <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
    <appender-ref ref="TEMP"/>
    <appender-ref ref="CONSOLE"/>
  </appender>
  <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <appender name="TEMP" class="org.apache.log4j.FileAppender">
    <param name="File" value="temp"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <root>
    <priority value="debug"/>
    <appender-ref ref="ASYNC"/>
  </Root>
</log4j:configuration>
----

Log4j 2 XML configuration. Note that the Async Appender should be
configured after the appenders it references. This will allow it to
shutdown properly.

.log4j2.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="debug">
  <Appenders>
    <Console name="CONSOLE" target="SYSTEM_OUT">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </Console>
    <File name="TEMP" fileName="temp">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </File>
    <Async name="ASYNC">
      <AppenderRef ref="TEMP"/>
      <AppenderRef ref="CONSOLE"/>
    </Async>
  </Appenders>
  <Loggers>
    <Root level="debug">
      <AppenderRef ref="ASYNC"/>
    </Root>
  </Loggers>
</Configuration>
----
