Introduction

What is logback?

Logback is intended as a successor to the popular log4j project. It was designed by Ceki Gülcü, log4j's founder. It builds upon a decade long experience gained in designing industrial-strength logging systems. The resulting product, logback is faster with a smaller footprint than all existing logging systems, sometimes by a wide margin. Logback also offers unique and rather useful features such as Markers, parameterized logging statements, conditional stack tracing and powerful event filtering. These are only few examples of useful features logback has to offer. For its own error reporting, logback relies on Status objects, which greatly facilitate troubleshooting. You may wish to rely on Status objects in contexts other than logging. Logback-core bundles Joran, a powerful and generic configuration system, which can be put to use in your own projects to great effect.

First Baby Step

Requirements

Logback-classic module requires the presence slf4j-api.jar, logback-core.jar in addition to logback-classic.jar on the classpath.

Let us now begin experimenting with logback.

package chapter1;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class HelloWorld1 {

  public static void main(String[] args) {

    Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld1");
    logger.debug("Hello world.");

  }
}

The HelloWorld class is defined in the chapter1 package. It starts by importing the Logger and LoggerFactory classes defined in the SLF4J API, more specifically within the org.slf4j package.

On the first line of the main() method, the variable named logger is assigned a Logger instance retreived by invoking the static method getLogger in the LoggerFactory class. This logger is named "chapter1.HelloWorld1". The main method proceeds to call the debug method of this logger passing "Hello World" as an argument. We say that the main method contains a logging statement of level debug with the message "Hello world".

You will note that the above example does not reference any logback classes. In most cases, as far as logging is concerned, your classes will need to import only SLF4J classes. In principle, you will have to import logback classes only for configuring logback. Thus, the vast majority of your classes will only be cognizant of SLF4J API and oblivious to the existence of logback.

You can launch the first sample application, chapter1.HelloWord1 with the command:

java chapter1.HelloWorld1

Launching the HelloWorld1 application will output a single line on the console. By virtue of to logback's default configuration policy, when no default file is found to configure logback explicitely, logback will add a ConsoleAppender to the root logger.

20:49:07.962 [main] DEBUG chapter1.HelloWorld1 - Hello world.

Logback can report information about its internal state using a built-in status system. Important events occuring during logback's lifetime can be accessed through a StatusManager. For the time being, let us instruct logback to print its internal state. This is accomplished by a static method in the LoggerStatusPrinter class.

package chapter1;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import ch.qos.logback.classic.util.LoggerStatusPrinter;

public class HelloWorld2 {

  public static void main(String[] args) {
    Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld2");
    logger.debug("Hello world.");
    LoggerStatusPrinter.printStatusInDefaultContext();
  }
}

Running the HelloWorld2 application will produce the following output:

20:49:07.962 [main] DEBUG chapter1.HelloWorld2 - Hello world.
|-INFO in ch.qos.logback.classic.BasicConfigurator@1c1ea29 - Setting up default configuration.

Logback explains that it configured itself using its default policy, which is a basic ConsoleAppender. An Appender is a class that can be seen as an output destination. Appenders exist for many different destinations including the console, files, Syslog, TCP Socket, JMS and many more. Users can also easily create their own Appenders as appropriate for their specific situation.

The previous examples are rather simple. However, actual logging in a larger application would not be any different. The general pattern logging statements will not change. Only the configuration process will be different since you will certainly need a more specific configuration than what logback provides by default. As you will see later on in this document, configuring logback can be done in different flexible and powerfull ways. Note that, normally, you won't need to invoke LoggerStatusPrinter after your log statements.

Here is a list of the three required steps in order to enable logging in your application.

Configure the logback environment. You can do so in several more or less sophisticated ways. More on this later.

In every class where you wish to perform logging, retrieve a Logger instance by invoking the org.slf4j.LoggerFactory class' getLogger() method, passing the current class name or the class itself as parameter.

Use this logger instance by invoking its printing methods, namely the debug(), info(), warn() and error(). This will produce logging output on the configured appenders.

Building logback

Logback relies on Maven2 as its build tool. Maven2 is a widely-used open-source build tool.

Once you have installed Maven2, building the logback project, including all its modules, should be as easy as issuing a mvn package command in a terminal or command window from within the directory where you unarchived the logback distribution file. Maven will automatically download the required external libraries and use them. However, certain artefacts cannot be downloaded from the Maven2 repository. At present, time only the JMS API from from SUN Inc. needs to be downloaded and installed separately into your local repository.

You can manually download the JMS API from Sun. Once you have downloaded the jms.jar file, you can install it in your local Maven 2 repository by issuing the command:

mvn install:install-file -DgroupId=javax.jms -DartifactId=jms -Dversion=1.1 / -Dpackaging=jar -Dfile=/path/to/jms.jar.file

Logback distributions contain complete source code such that you can modify parts of logback library and build your own version of it. You may even redistribute the modified version, as long as you adhere to the conditions of the LGPL License.