Migrating from Log4j 2

If you are migrating from Log4j 1, check the Migrating from Log4j 1 guide in the Log4j 2 manual.

Since Log4j 3 uses Log4j 2 API as logging API, no code changes should be necessary for most users.

In order to migrate to Log4j 3, you only need to:

update your dependencies,
if you use configuration properties to fine tune the Log4j 3 backend, check your configuration properties,
if you used the Java properties configuration format, migrate your configuration file,

Runtime dependencies

Log4j 2 Core contains many features that depend on optional runtime dependencies. In order to comply with the Java Platform Module System and help users managing those dependencies, some features were moved to separate Maven modules. This change has the following advantages:

you don’t need to consult the documentation to find out, which third-party libraries are necessary to use a specific feature: adding the appropriate Log4j 3 artifact is enough.
Log4j 3 does not have optional dependencies, so third-party libraries used by Log4j will be upgraded automatically by your dependency management tool, when you upgrade Log4j.

The following log4j-core features were moved to their own modules or were removed:

Table 1. New Log4j 3 modules
Log4j 2 feature	Log4j 3 module
Asynchronous appender: Conversant Disruptor-based queue	`log4j-conversant`
Asynchronous appender: JCTools-based queue	`log4j-jctools`
Asynchronous logger	`log4j-async-logger`
Cassandra appender	removed without replacement ^[1]
CouchDB appender	removed without replacement ^[1]
Configuration file: Java properties format	`log4j-config-properties`
Configuration file: YAML format	`log4j-config-yaml`
CSV layouts	`log4j-csv`
GELF layout	replaced by `JsonTemplateLayout` and the included `GelfLayout.json` template
JDBC appender	`log4j-jdbc` or one of the `log4j-jdbc-*` artifacts below.
JDBC appender with DBCP 2 connection source	`log4j-jdbc-dbcp2`
JDBC appender with JNDI connection source	`log4j-jdbc-jndi`
JeroMQ appender	replaced by external `loghublog4j2` module
JMS appender: Java EE version	removed without replacement ^[1]
JNDI lookup	`log4j-jndi`
JPA appender	removed without replacement ^[1]
JSP Tag library	removed without replacement ^[1]
Kafka appender	removed without replacement ^[1]
Kubernetes lookup	replaced by external `kubernetes-log4j` module
Scripting support	`log4j-script`
Servlet application support: Java EE version	removed without replacement ^[1]
SMTP appender: Java EE version	removed without replacement ^[1]
Spring Boot lookup	integrated into Spring Boot 3

Migrate configuration properties

In order to support per-logger context configuration properties, the configuration properties sub-system of Log4j has been rewritten and the naming convention of properties have changed. To help you with the migration process a backward compatibility system has been implemented, which translates Log4j 2 property names to their Log4j 3 equivalents.

If you use configuration properties to finely tune Log4j Core:

you are advised to migrate to the new Log4j 3 naming convention for configuration properties,
in the meantime you can continue to use the Log4j 2 naming convention introduced in Log4j 2.10,
other naming conventions, including variations in the case of property names are not supported.

Java properties configuration file format

The Java properties configuration file format in Log4j 3 has been rewritten to use jackson-dataformat-properties to convert Java properties into the native JSON configuration file format. See Jackson documentation for more details on the conversion.

The only significant changes between the Log4j 2 and Log4j 3 properties format are:

As an alternative to using the type configuration attribute to specify the plugin type of a Log4j component, you can append the plugin type to the prefix of the parent component. For example, instead of:

appender.0.type = Console
appender.0.name = CONSOLE
appender.1.type = File
appender.1.name = MAIN
appender.1.fileName = logs/main.log
appender.2.type = File
appender.2.name = DEBUG_LOG
appender.2.fileName = logs/debug.log

you can write:

Appenders.Console.name = CONSOLE
Appenders.File[1].name = MAIN
Appenders.File[1].fileName = logs/main.log
Appenders.File[2].name = DEBUG_LOG
Appenders.File[2].fileName = logs/debug.log

The Java properties format specific quirks are no longer recognized, which means that:
- The following direct children of Configuration need to use the same prefix as the other formats:
  You need to replace the appender prefix with Appenders,
  
  You need to replace the logger prefix with Loggers,
  
  You need to replace the script prefix with Scripts.
- Properties that start with property, which are used for property substitution, need to be rewritten from:
  property.<key> = <value>
  to
  Properties.Property[<n>].key = <key> Properties.Property[<n>].value = <value>
  where <n> is an increasing positive integer.
- Properties that start with customLevel, which are used to define custom levels, need to be rewritten from:
  customLevel.<name> = <intLevel>
  to
  CustomLevels.CustomLevel[<n>].name = <name> CustomLevels.CustomLevel[<n>].intLevel = <intLevel>
  where <n> is an increasing positive integer.
- You need to replace the rootLogger prefix with Loggers.Root.
- The shorthand notation:
  rootLogger = INFO, APPENDER1, APPENDER2
  must be rewritten into:
  Loggers.Root.level = INFO Loggers.Root.AppenderRef[1] = APPENDER1 Loggers.Root.AppenderRef[2] = APPENDER2
- All the prefixes of the form:
  logger.<name>.appenderRef.<id>
  where <name> and <id> are arbitrary, must be rewritten to
  Loggers.Logger[<n>].AppenderRef[<m>]
  where <n> and <m> are increasing positive integers.

1. If you are using these components, and you can help us to maintain them, please contact us on our support channels.