Installation
In this page we will elaborate on various ways to install Log4j in your library or application.
Shortcuts
Below we share some shortcuts for the impatient.
We strongly advise you to skim through this page to get a grip on fundamental logging concepts and understand which recipe fits your bill best. |
- Are you a library developer?
-
You just need to log against a logging API. See Installing Log4j API.
- Are you an application developer?
-
Your code and libraries it depends on are most probably already logging against a logging API, you just need to install a logging implementation. See Installing Log4j Core.
- Are you a Spring Boot application developer?
- Are you migrating from…
Concepts (APIs, Implementations, and Bridges)
It is crucial to understand certain concepts in logging to be able to talk about the installation of them.
- Logging API
-
A logging API is an interface your code or your dependencies directly logs against. It is required at compile-time. It is implementation agnostic to ensure that your application can write logs, but is not tied to a specific logging implementation. Log4j API, SLF4J, JUL (Java Logging), JCL (Apache Commons Logging), JPL (Java Platform Logging) and JBoss Logging are major logging APIs.
- Logging implementation
-
A logging implementation is only required at runtime and can be changed without the need to recompile your software. Log4j Core, JUL (Java Logging), Logback are the most well-known logging implementations.
- Logging bridge
-
Logging implementations accept input from a single logging API of their preference; Log4j Core from Log4j API, Logback from SLF4J, etc. A logging bridge is a simple logging implementation of a logging API that forwards all messages to a foreign logging API. Logging bridges allow a logging implementation to accept input from other logging APIs that are not their primary logging API. For instance,
log4j-slf4j2-impl
bridges SLF4J calls to Log4 API and effectively enables Log4j Core to accept input from SLF4J.
With this in mind, the type of software you are writing determines whether you should be installing a logging API, implementation, or bridge:
- Libraries
-
They only require a logging API and delegate the choice of the implementation to applications. If a logging implementation is required by tests of the library, it should be in the appropriate test scope.
- Applications
-
They need a logging implementation, but also bridges of each of the major logging APIs to support log statements from the libraries they use. For example, your application might be logging against Log4j API and one of its dependencies against SLF4J. In this case, you need to install
log4j-core
andlog4j-slf4j2-impl
.
To make things a little bit more tangible, consider the following visualization of a typical Log4j Core installation with bridges for an application:
@startuml frame "Compile time" { [Application] --> [Log4j API] : logs to [Log4j API] #Cyan [SLF4J] #Cyan [Library 1] --> [SLF4J] : logs to [Application] --> [Library 1] : uses [Application] --> [Library 2] : uses [Application] --> [Library 3] : uses } frame Runtime { [Log4j Core] <.. [Log4j API] : is implemented by [Log4j Core] <.. (log4j2.xml) : is provided to [Log4j Core] #LightGreen [JPL-to-Log4j] ..> [Log4j Core] : forwards to [JPL-to-Log4j] #Yellow [SLF4J-to-Log4j] ..> [Log4j Core] : forwards to [SLF4J-to-Log4j] #Yellow [JUL-to-Log4j] ..> [Log4j Core] : forwards to [JUL-to-Log4j] #Yellow frame JRE { [JPL] #Cyan [JUL] #Cyan } } [Library 2] --> [JUL] : logs to [Library 3] --> [JPL] : logs to [JPL] ..> [JPL-to-Log4j] : is implemented by [JUL] ..> [JUL-to-Log4j] : is implemented by [SLF4J] ..> [SLF4J-to-Log4j] : is implemented by legend top right | <#LightGreen> | Logging implementation | | <#Yellow> | Logging bridge | | <#Cyan> | Logging API | | <size:18><U+2192></size> | Compile-time usage | | <size:18><U+21E2></size> | Runtime usage | endlegend @enduml
Requirements
The Log4j 2 runtime requires a minimum of Java 8. See the Download page for older releases supporting Java 6 and 7.
Configuring the build tool
The easiest way to install Log4j is through a build tool such as Maven or Gradle. The rest of the instructions in this page assume you use one of these.
Importing the Bill-of-Materials (aka. BOM)
To keep your Log4j module versions in sync with each other, a BOM (Bill of Material) file is provided for your convenience. You can import the BOM in your build tool of preference:
-
Maven
-
Gradle
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-bom</artifactId>
<version>2.24.1</version>
<scope>import</scope>
<type>pom</type>
</dependency>
</dependencies>
</dependencyManagement>
dependencies {
implementation platform('org.apache.logging.log4j:log4j-bom:2.24.1')
}
Once you import the BOM, you don’t need to explicitly provide the versions of the Log4j artifacts managed by it.
In the rest of the explanations, we will assume that the Log4j BOM is imported.
Using snapshots
Do you want to test the latest (unstable!) development version? Click here details.
You can access the latest development snapshots by using the https://repository.apache.org/content/groups/snapshots/
repository.
Snapshots are published for development and testing purposes; they should not be used at production! |
-
Maven
-
Gradle
<repositories>
<repository>
<id>apache.snapshots</id>
<name>Apache Snapshot Repository</name>
<url>https://repository.apache.org/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
</repository>
</repositories>
repositories {
mavenCentral()
maven { url 'https://repository.apache.org/snapshots' }
}
Installing Log4j API
The easiest way to install Log4j API is through a dependency management tool such as Maven or Gradle, by adding the following dependency:
-
Maven
-
Gradle
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
<version>${log4j-api.version}</version>
</dependency>
implementation 'org.apache.logging.log4j:log4j-api:${log4j-api.version}'
Installing a logging implementation
Log4j provides several modules to facilitate the deployment of different logging implementations:
log4j-core
-
The reference implementation. Log4 Core primarily accepts input from Log4j API. Refer to Installing Log4j Core for the installation instructions.
log4j-to-jul
-
The bridge that translates Log4j API calls to JUL (Java Logging). See Installing JUL for the installation instructions.
log4j-to-slf4j
-
The bridge that translates Log4j API calls to SLF4J. Since currently only Logback implements SLF4J natively, refer to Installing Logback for the installation instructions.
To ensure that your code does not directly depend on a particular logging implementation, the logging backend should be put in the appropriate scope of your dependency manager:
|
Installing Log4j Core
Log4j Core is the reference logging implementation of the Log4j project. It primarily accepts input from Log4j API.
Do you have a Spring Boot application? You can directly skip to Installing Log4j Core for Spring Boot applications. |
To install Log4j Core as your logging implementation, you need to add the following dependency to your application:
-
Maven
-
Gradle
<dependencies>
<!-- Logging implementation (Log4j Core) -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<scope>runtime</scope>
</dependency>
<!-- Logging bridges will follow... -->
</dependencies>
runtimeOnly 'org.apache.logging.log4j:log4j-core'
// Logging bridges will follow...
Installing bridges
If either your application or one of its dependencies logs against a logging API that is different from Log4j API, you need to bridge that API to Log4j API.
Do you need bridges? And if so, which ones?
|
The following sections explain the installation of Log4j-provided bridges.
Installing SLF4J-to-Log4j bridge
You can translate SLF4J calls to Log4j API using the log4j-slf4j2-impl
artifact:
-
Maven
-
Gradle
We assume you use log4j-bom
for dependency management.
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-slf4j2-impl</artifactId>
<scope>runtime</scope>
</dependency>
We assume you use log4j-bom
for dependency management.
runtimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl'
Are you still using SLF4J 1.x?
Add this example instead:
-
Maven
-
Gradle
We assume you use log4j-bom
for dependency management.
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-slf4j-impl</artifactId>
<scope>runtime</scope>
</dependency>
We assume you use log4j-bom
for dependency management.
runtimeOnly 'org.apache.logging.log4j:log4j-slf4j-impl'
Installing JUL-to-Log4j bridge
You can translate JUL (Java Logging) calls to Log4j API using the log4j-jul
artifact:
-
Maven
-
Gradle
We assume you use log4j-bom
for dependency management.
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-jul</artifactId>
<scope>runtime</scope>
</dependency>
We assume you use log4j-bom
for dependency management.
runtimeOnly 'org.apache.logging.log4j:log4j-jul'
In order to activate the bridge from JUL to Log4j API, you also need to add:
-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager
to the JVM parameters in your application launcher.
The JUL-to-Log4j bridge supports additional configuration and installation methods. See JUL-to-Log4j bridge for more information.
Installing JPL-to-Log4j bridge
You can translate JPL (Java Platform Logging) calls to Log4j API using the log4j-jpl
artifact:
-
Maven
-
Gradle
We assume you use log4j-bom
for dependency management.
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-jpl</artifactId>
<scope>runtime</scope>
</dependency>
We assume you use log4j-bom
for dependency management.
runtimeOnly 'org.apache.logging.log4j:log4j-jpl'
Installing JCL-to-Log4j bridge
Since version 1.3.0
Apache Commons Logging natively supports Log4j API.
You can enforce the version of a transitive dependency using the dependency management mechanism appropriate to your build tool:
-
Maven
-
Gradle
Maven users should add an entry to the <dependencyManagement>
section of their POM file:
<dependencyManagement>
<dependency>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
<version>1.3.4</version>
</dependency>
</dependencyManagement>
Gradle users should refer to the Using a platform to control transitive versions of the Gradle documentation.
Are you using Commons Logging 1.2.0 or earlier?
You need to install the following dependency instead:
-
Maven
-
Gradle
We assume you use log4j-bom
for dependency management.
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-jcl</artifactId>
<scope>runtime</scope>
</dependency>
We assume you use log4j-bom
for dependency management.
runtimeOnly 'org.apache.logging.log4j:log4j-jcl'
Installing JBoss Logging-to-Log4j bridge
JBoss Logging is shipped with an integrated bridge to Log4j API and requires no steps on your part. See Supported Log Managers for more information.
Installing Log4j Core for Spring Boot applications
Spring Boot users should replace the spring-boot-starter-logging
dependency with spring-boot-starter-log4j2
:
-
Maven
-
Gradle
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-log4j2</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>
configurations {
all.exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging'
}
dependencies {
runtimeOnly group: 'org.springframework.boot', module: 'spring-boot-starter-log4j2'
}
The spring-boot-starter-log4j2
artifact will automatically install Log4j Core, JUL-to-Log4j bridge, and configure them.
You don’t need to add any other dependency or configure JUL anymore.
See Spring Boot Logging documentation for further information.
Configuring Log4j Core
As with any other logging implementation, Log4j Core needs to be properly configured. Log4j Core supports many different configuration formats: JSON, XML, YAML, and Java properties. To configure Log4j Core, see Configuration file. A basic configuration can be obtained by adding one of these files to your application’s classpath:
-
log4j2.xml
-
log4j2.json
-
log4j2.yaml
-
log4j2.properties
<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="https://logging.apache.org/xml/ns"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://logging.apache.org/xml/ns
https://logging.apache.org/xml/ns/log4j-config-2.xsd">
<appenders>
<Console name="CONSOLE">
<PatternLayout pattern="%d [%t] %5p %c{1.} - %m%n"/>(1)
</Console>
</appenders>
<loggers>
<root level="INFO">
<AppenderRef ref="CONSOLE"/>
</root>
</loggers>
</Configuration>
{
"Configuration": {
"Appenders": {
"Console": {
"name": "CONSOLE",
"PatternLayout": {
"pattern": "%d [%t] %5p %c{1.} - %m%n" (1)
}
}
},
"Loggers": {
"Root": {
"level": "INFO",
"AppenderRef": {
"ref": "CONSOLE"
}
}
}
}
}
Configuration:
Appenders:
Console:
name: CONSOLE
PatternLayout:
pattern: "%d [%t] %5p %c{1.} - %m%n" (1)
Loggers:
Root:
level: INFO
AppenderRef:
ref: CONSOLE
appender.0.type = Console
appender.0.name = CONSOLE
appender.0.layout = PatternLayout (1)
appender.0.layout.pattern = %d [%t] %5p %c{1.} - %m%n
rootLogger.level = INFO
rootLogger.appenderRef.0.ref = CONSOLE
1 | While Pattern Layout is a good first choice and preferable for tests, we recommend using a structured format such as JSON Template Layout for production deployments. |
To use these formats, the following additional dependencies are required:
-
log4j2.xml
-
log4j2.json
-
log4j2.yaml
-
log4j2.properties
JPMS users need to add:
module foo.bar {
requires java.xml;
}
to their module-info.java
descriptor.
-
Maven
-
Gradle
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.18.0</version>
<scope>runtime</scope>
</dependency>
runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:2.18.0'
-
Maven
-
Gradle
<dependency>
<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-yaml</artifactId>
<version>2.18.0</version>
<scope>runtime</scope>
</dependency>
runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.0'
No dependency required.
Installing JUL
Are you using JBoss Log Manager as your JUL implementation?
You can skip this section and use the |
Java Platform contains a very simple logging API and its implementation called JUL (Java Logging). Since it is embedded in the platform, it only requires the addition of bridges from Log4j API and SLF4J:
-
Maven
-
Gradle
<dependencies>
<!-- Log4j-to-JUL bridge -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-to-jul</artifactId>
<scope>runtime</scope>
</dependency>
<!-- SLF4J-to-JUL bridge -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-jdk14</artifactId>
<version>2.0.16</version>
<scope>runtime</scope>
</dependency>
<!-- ... -->
</dependencies>
runtimeOnly 'org.apache.logging.log4j:log4j-to-jul' // Log4j-to-JUL bridge
runtimeOnly 'org.slf4j:slf4j-jdk14:2.0.16' // SLF4J-to-JUL bridge
See also:
-
java.util.logging.LogManager
, to learn more about JUL configuration, -
Log4j-to-JUL bridge to learn more about the
log4j-to-jul
artifact.
Installing Logback
To install Logback as the logging implementation, you only need to add a Log4j-to-SLF4J bridge:
-
Maven
-
Gradle
<dependencies>
<!-- Logging implementation (Logback) -->
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>{logback-version}</version>
<scope>runtime</scope>
</dependency>
<!-- Log4j-to-SLF4J bridge -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-to-slf4j</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>
runtimeOnly 'ch.qos.logback:logback-classic:1.5.5'
runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j' // Log4j-to-SLF4J bridge
To configure Logback, see Logback’s configuration documentation.