SLF4J user manual
The Simple Logging Facade for Java or (SLF4J) serves as a simple facade or abstraction for various logging frameworks, e.g. java.util.logging, log4j and logback, allowing the end-user to plug in the desired logging framework at deployment time.
Hello World
In accordance with programming tradition, here is an example illustrating the simplest way to output "Hello world" using SLF4J. It begins by getting a logger with the name "HelloWorld". This logger is in turn used to log the message "Hello World".
Binding with a logging framework at deployment time
As mentioned previously, SLF4J supports various logging frameworks. The SLF4J distribution ships with several jar files referred to as "SLF4J bindings", with each binding corresponding to a supported framework.
- slf4j-log4j12-1.6.1.jar
- Binding for log4j
version 1.2
, a widely used logging framework. You also
need to place log4j.jar
on your class path.
- slf4j-jdk14-1.6.1.jar
- Binding for java.util.logging, also referred to as JDK 1.4
logging
- slf4j-nop-1.6.1.jar
- Binding for NOP
,
silently discarding all logging.
- slf4j-simple-1.6.1.jar
- Binding for Simple
implementation, which outputs all events to
System.err. Only messages of level INFO and higher are
printed. This binding may be useful in the context of small
applications.
- slf4j-jcl-1.6.1.jar
- Binding for Jakarta Commons
Logging
. This binding will delegate all SLF4J logging to
JCL.
There are also SLF4J bindings external to the SLF4J project,
e.g. logback
which
implements SLF4J natively. Logback's
ch.qos.logback.classic.Logger
class is a direct
implementation of SLF4J's
org.slf4j.Logger
interface. Thus, using SLF4J
in conjunction with logback involves strictly zero memory and
computational overhead.
To switch logging frameworks, just replace slf4j bindings on your class path. For example, to switch from java.util.logging to log4j, just replace slf4j-jdk14-1.6.1.jar with slf4j-log4j12-1.6.1.jar.
SLF4J does not rely on any special class loader machinery. In fact, the each SLF4J binding is hardwired at compile time to use one and only one specific logging framework. For example, the slf4j-log12-1.6.1.jar binding is bound at compile time to use log4j. In your code, in addition to slf4j-api-1.6.1.jar , you simply drop one and only one binding of your choice onto the appropriate class path location. Do not place more than one binding on your class path. Here is a graphical illustration of the general idea.
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. No knowledge of class loaders is necessary as SLF4J does not make use nor does it directly access any class loaders. As a consequence, SLF4J suffers from none of the class loader problems or memory leaks observed with Jakarta Commons Logging (JCL).
Given the simplicity of the SLF4J interfaces and its deployment model, developers of new logging frameworks should find it very easy to write SLF4J bindings.
Libraries
Authors of widely-distributed components and libraries may code against the SLF4J interface in order to avoid imposing an logging framework on the end-user of the component or library. Thus, the end-user may choose the desired logging framework at deployment time by inserting the corresponding slf4j binding on the classpath, which may be changed later by replacing an existing binding with another on the class path and restarting the application. This approach has proven to be simple and very robust.
As of SLF4J version 1.6.0
, if no binding is found on
the class path, then slf4j-api will default to a no-operation
implementation discarding all log requests. Thus, instead of
throwing a NoClassDefFoundError
because the
org.slf4j.impl.StaticLoggerBinder
class is missing,
SLF4J version 1.6.0 and later will emit a single warning message
about the absence of a binding and proceed to discard all log
requests without further protest. For example, let Wombat be
some biology-related framework depending on SLF4J for
logging. In order to avoid imposing a logging framework on the
end-user, Wombat's distribution includes slf4j-api.jar
but no binding. Even in the absence of any SLF4J binding on the
class path, Wombat's distribution will still work
out-of-the-box, and without requiring the end-user to download a
binding from SLF4J's web-site. Only when the end-user decides to
enable logging will she need to install the SLF4J binding
corresponding to the logging framework chosen by the end-user.
Consolidate logging via SLF4J
Often times, a given project will depend on various components which rely on logging APIs other than SLF4J. It is common to find projects depending on a combination of JCL, java.util.logging, log4j and SLF4J. It then becomes desirable to consolidate logging through a single channel. SLF4J caters for this common use-case by providing bridging modules for JCL, java.util.logging and log4j. For more details, please refer to the page on Bridging legacy APIs .
Mapped Diagnostic Context (MDC) support
"Mapped Diagnostic Context" is essentially a map maintained by the logging framework where the application can provided key-value pairs, which can then be inserted by the logging framework in log messages.
SLF4J supports MDC, or mapped diagnostic context. If the underlying logging framework offers MDC functionality, then SLF4J will delegate to the underlying framework's MDC. Note that at this time, only log4j and logback offer MDC functionality. If the underlying framework does not offer MDC, for example java.util.logging, then SLF4J will still store MDC data but the information therein will need to be retrieved by custom user code.
Thus, as a SLF4J user, you can take advantage of MDC information in the presence of log4j or logback, but without forcing these logging frameworks upon your users as dependencies.
For more information on MDC please see the chapter on MDC in the logback manual.
Executive summary
| Advantage | Description |
|---|---|
| Select your logging framework at deployment time | The desired logging framework can be plugged in at deployment time by inserting the appropriate jar file (binding) on your class path. |
| Fail-fast operation | Due to the way that classes are loaded by the JVM, the framework binding will be verified automatically very early on. SLF4J will abort execution with a warning if no binding is present. |
| Bindings for popular logging frameworks | SLF4J supports popular logging frameworks, namely log4j, java.util.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. See the page on Bridging legacy APIs for more details. |
| Migrate your source code | The slf4j-migrator utility can help you migrate your source to use SLF4J. |
| Support for parameterized log messages | All SLF4J bindings support parameterized log messages with significantly improved performance results. |