SLF4J User manual

The Simple Logging Facade for Java or (SLF4J) is intended to serve as a simple facade for various logging APIs allowing to plug in the desired implementation at deployment time.

Typical usage pattern

 1: import org.slf4j.Logger;
 2: import org.slf4j.LoggerFactory;
 3: 
 4: public class Wombat {
 5:  
 6:   final Logger logger = LoggerFactory.getLogger(Wombat.class);
 7:   Integer t;
 8:   Integer oldT;
 9:
10:   public void setTemperature(Integer temperature) {
11:    
12:     oldT = t;        
13:     t = temperature;
14:
15:     logger.debug("Temperature set to {}. Old temperature was {}.", t, oldT);
16:
17:     if(temperature.intValue() > 50) {
18:       logger.info("Temperature has risen above 50 degrees.");
19:     }
20:   }
21: }
      

The example above illustrates the typical usage pattern for SLF4j. Note the use of formatted log messages on line 15. See the question "What is the fastest way of logging?" in the FAQ for more details.

Swapping implementations at deployment time

SLF4J supports multiple logging systems, namely, NOP, Simple, log4j version 1.2, JDK 1.4 logging, JCL and logback. The SLF4J distribution ships with several jar files slf4j-nop.jar, slf4j-simple.jar, slf4j-log4j12.jar, slf4j-log4j13.jar, slf4j-jdk14.jar and slf4j-jcl.jar. Each of these jar files is hardwired at compile-time to use just one implementation, that is NOP, Simple, log4j version 1.2, JDK 1.4 logging, and repectively JCL. As of SLF4J version 1.1.0, all of the bindings shipped with SLF4J depend on slf4j-api.jar which must be present on the class path for the binding to function properly. The figure below illustrates the general idea.

 

click to enlarge

 

Small applications

Small applications where configuring a fully-fledged logging systems can be somewhat of an overkill, can drop in slf4j-api.jar+slf4j-simple.jar instead of a binding for a fully-fledged logging system.

Libraries

Authors of widely-distributed components and libraries may code against the SLF4J interface in order to avoid imposing an logging system on the end-user. At deployment time, the end-user may choose the desired logging system by inserting the corresponding jar file in her classpath. This stupid, simple and robust approach avoids many of the painful bugs associated with dynamic discovery processes.

Simplicity

The SLF4J interfaces and their various adapters are extremely simple. Most developers familiar with the Java language should be able to read and fully understand the code in less than one hour.

As noted earlier, SLF4J does not rely on any special class loader machinery. Every variant of slf4j-<impl>.jar is statically hardwired at compile time to use one and only specific implementation. Thus, SLF4J suffers from none of the class loader problems observed when using JCL.

Hopefully, the simplicity of the SLF4J interfaces and the deployment model will make it easy for developers of other logging APIs to conform to the SLF4J model.

Built-in support in logback

The ch.qos.logback.classic.Logger class in logback directly implements SLF4J's org.slf4j.Logger interface.

Logback's built-in (a.k.a. native) support for SLF4J means that the adapter for does not need to wrap logback objects in order to make them conform to SLF4J's Logger interface. A logback ch.qos.logback.classic.Logger is a org.slf4j.Logger. Thus, using SLF4J in conjunction with logback involves strictly zero memory and computational overhead.

Mapped Diagnostic Context (MDC) support

As of version 1.4.1, SLF4J supports MDC, or mapped diagnosic context. If the underlying logging system offers MDC functionality, then SLF4J will delegate to the underlying system's MDC. Note that at this time, only log4j and logback offer MDC functionality. If the undelying system does not offer MDC, then SLF4J will silently drop MDC information.

Thus, as a SLF4J user, you can take advantage of MDC information in the presence of log4j or logback, but without forcing these upon your users as dependencies.

As of SLF4J version 1.5.0, SLF4J provides MDC support for java.util.logging (JDK 1.4 logging) as well.

For more information on MDC please see the chapter on MDC in the logback manual.

Gradual migration to SLF4J from Jakarta Commons Logging (JCL)

This section has been moved elsewhere.

Executive summary

Advantage Description
Swappable logging API implementations The desired logging API can be plugged in at deployment time by inserting the appropriate jar file on your classpath.
Fail-fast operation Assuming the appropriate jar file is available on the classpath, under no circumstances will SLF4J cause your application to fail. SLF4J's simple and robust design ensures that SLF4J never causes exceptions to be thrown.

Contrast this with LogConfigurationException thrown by JCL which will cause your otherwise functioning application to fail. JCL-logging will throw a LogConfigurationException in case the Log interface and its dynamically discovered implementation are loaded by different class loaders.

Adapter implementations for popular logging systems SLF4J supports popular logging systems, namely log4j, JDK 1.4 logging, Simple logging and NOP. The logback project supports SLF4J natively.
Bridging legacy logging APIs

The implementation of JCL over SLF4J, i.e jcl-over-slf4j.jar, will allow your project to migrate to SLF4J piecemeal, without breaking compatibility with existing software using JCL. Similarly, log4j-over-slf4j.jar and jul-to-slf4j modules will allow you to redirect log4j and respectively java.util.logging calls to SLF4J.

Migrate your source code The slf4j-migrator utility can help you migrate your source to use SLF4J.
Support for formated log messages All SLF4J adapters support formated log messages with significantly improved performace results.