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.
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.
For more information on MDC please see the chapter on MDC in the logback manual.
Gradual migration to SLF4J from Jakarta Commons Logging (JCL)
jcl104-over-slf4j.jar
To ease migration to SLF4J from JCL, recent SLF4J distributions include the jar file jcl104-over-slf4j.jar. This jar file is intended as a drop-in replacement for JCL version 1.0.4. It implements the public API of JCL but using SLF4J underneath, hence the name "JCL over SLF4J."
Our JCL over SLF4J implementation will allow you to migrate to SLF4J gradually, especially if some of the libraries your software depends on continue to use JCL for the foreseeable future. You can immediately enjoy the benefits of SLF4J's reliability and preserve backward compatibility at the same time. Just replace commons-logging.jar with jcl104-over-slf4j.jar. Subsequently, the selection of the underlying logging system will be done by SLF4J instead of JCL but without the class loader headaches. The underlying logging system can be any of NOP, simple, jdk14 logging, log4j or logback. Any existing dependency on commons-logging therefore becomes less of an issue.
slf4j-jcl.jar
Some of our users after having switched to SLF4J API realize that in some contexts the use of JCL is mandatory and their use of SLF4J can be a problem. For this uncommon but important case, SLF4J offers a JCL binding, found in the file slf4j-jcl.jar. The JCL binding will delegate all logging calls made through SLF4J API to JCL. Thus, if for some reason an existing application must use JCL, your part of that application can still code against the SLF4J API in a manner transparent to the larger application environment. Your choice of SLF4J API will be invisible to the rest of the application which can continue to use JCL.
jcl104-over-slf4j.jar should not be confused with slf4j-jcl.jar
JCL-over-SLF4J, i.e. jcl104-over-slf4j.jar, comes in handy in situations where JCL needs to be supported for backward compatibility reasons. It can be used to fix problems associated with JCL, without necessarily adopting the SLF4J API, a decision which can be deferred to a later time.
On the other hand, slf4j-jcl.jar is useful after you have already adopted the SLF4J API for your component which needs to be embedded in a larger application environment where JCL is a formal requirement. Your software component can still use SLF4J API without disrupting the larger application. Indeed, slf4j-jcl.jar will delegate all logging decisions to JCL so that the dependency on SLF4J API by your component will be transparent to the larger whole.
Please note that jcl104-over-slf4j.jar and slf4j-jcl.jar cannot be deployed at the same time. The former jar file will cause JCL to delegate the choice of the logging system to SLF4J and the latter jar file will cause SLF4J to delegate the choice of the logging system to JCL, resulting in an infinite loop.
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
|
| Adapter implementations for popular logging systems | SLF4J supports popular logging systems, namely log4j, JDK 1.4 logging, Simple logging and NOP whereas the logback API supports SLF4J natively. |
| Easy migration path |
The implementation of JCL over SLF4J, i.e jcl104-over-slf4j.jar, will allow your project to migrate to SLF4J piecemeal, without breaking compatibility with existing software using JCL. |
| Support for formated log messages | All SLF4J adapters support formated log messages with significantly improved performace results. |