How To Do Logging In Java

Since Java 1.4 (2002), the JDK comes bundled with its own logging 'framework', called java.util.logging, often abbreviated to JUL. Here’s an example of how you would log things with JUL:

As is the case for every logging library, first you get a Logger for a specific class or package, and then you can log statements. You might think that the log levels 'severe' and 'fine' look weird, but they basically correspond to the 'error' and 'debug' levels of all modern Java logging libraries.

And of course, you can configure your loggers with so called handlers, like a FileHandler (which writes log statements to files) or a ConsoleHandler (which writes to System.err).

So, you might be asking, if there’s JUL, why would anyone need another logging framework?

While JUL does the job, there have been discussions about its shortcomings in the past, spanning its inconsistent API, slow performance, lack of (complex) configuration options, documentation etc - which ultimately lead to people developing and using other logging frameworks.

For a long time, the most popular choice for logging in Java land was Log4j (version 1), which was initially released in 2001 and maintained until 2015. In fact, you’ll still find it being used in a fair number of corporate projects, in 2018.

With Log4j, the logging example from above would look like this:

It’s not only that Log4j has sane log level names, like 'error' and 'debug'. It also comes with a ton of different and clever appenders, like SMTPAppender (to e-mail log events), SyslogAppenders (to send events to a remote syslog daemon), JdbcAppenders (to send them to the database) and many more.

Also it gives you a fair amount of control over what exactly a log message should look like, with the help of PatternLayouts. So, the same log event in your Java application, could be printed out in a log file like so, depending on the layout:

Log4j does the job quite well, but got superseded by Log4j2 in the past years, which is not fully compatible with Log4j1, hence we will talk about it in the next section.

Around the same time, in 2002, another library popped up, called JCL, which goes by two names. Jakarta Commons Logging or Apache Commons Logging.

The interesting thing about JCL is, that it is not a logging framework implementation itself. Rather, it is an interface for other logging implementations. What does that mean?

As you might have guessed, the logging code itself stays fairly simple, only instead of referencing JUL or Log4j classes, you now reference the JCL classes - provided you have the JCL library on your classpath.

So, your code only uses JCL specific classes. But then the actual logging is done by another logging framework, and it doesn’t matter if it is Log4j, JUL or (the long defunct) Apache Avalon.

That means you need another library, like Log4j, on your classpath and configure these two to work together.

Why would anyone want to do this?

Why wouldn’t you want to use Log4j directly, instead? There’s one major use-case, which is writing libraries:

When writing libraries, you simply do not know which logging framework a user of your library wants to use in his own application. It therefore makes sense to write your library to use a logging interface - and then the user can plug in any logging implementation that he or she wants, whenever he deploys his own application.

Where’s the catch?

The problem with JCL is, that it relies on classloader hacks to find out which logging implementation it should use - at runtime. And that can lead to a lot of pain. In addition, you’ll find that the API is somewhat inflexible, that it comes with a fair amount of cruft, and there’s simply better alternatives out there, nowadays.

At some point, the original creator of Log4j, Ceki Gülcü, decided to split from the Log4j project and create a successor, which was not called Log4j2, but Logback. You can read about what he tried to make better with Logback here.

Suffice to say, that Logback is a mature and solid logging library, with a ton of features, of which auto-reloading of configuration files in production is one that developers seem to remember the most.

Somewhat in parallel, he also started writing the Simple Logging Facade for Java, also known as SLF4J, which is very similar to the Apache Commons Logging 'bridging' library above, just with a better implementation. Let’s see what that means:

To get started with SLF4J, you only need one library on the classpath, the slf4j-api dependency (see screencast for the following section). If you are using a dependency management tool like Maven, then you would add the following dependency to your dependencies section:

Having the API on your classpath will allow you to write log statements like the following:

Just like JCL, SLF4J cannot do logging itself. It needs a logging library to do the actual logging, like Log4j, JUL, Logback etc. So, say you want to use Log4j v1, you would then need the slf4j-log4j12 binding library in your classpath:

That dependency will transitively pull in Log4j (v1) for you and also make sure that SLF4J logs 'through' Log4j. If you are interested in how this works, read the section about bindings in the SLF4J manual.

Other libraries, like Logback, don’t need a binding library, because they implement SLF4J natively, so you can simply use the slf4j-api dependency, drop in the logback-classic jar as well, and you can log through Logback.

The beauty of this approach is, that your code only knows SLF4J. There are no references to Log4j, Logback or Jul. And if you are writing a library, that’s even better. Because if your library uses SLF4J, then the end-user of your library can decide to log either with Log4j, or Logback, or whatever library he wants. Because that choice can simply be made by adding or removing a couple of jars to or from the classpath.

Hold on, aren’t we missing something?

Things get interesting, whenever you are using 3rd party libraries, that are hardcoded to use a specific logging library. Imagine you are using a PDF generator library, which is hardcoded to use Log4j. You are also using an e-mail sending library, which uses JUL. Your own application uses SLF4J, but you cannot just go and change the source code of these libraries to use SLF4J as well.

What to do now?

Thankfully, the SLF4J creators thought about that use-case as well (see screencast here). Let’s see what that looks like, by looking at the Maven dependencies first:

Whenever you pull in a 3rd party-library that uses Log4j, it will, obviously, pull in the Log4j dependency. The Log4j dependency looks like this:

You then need to make sure to exclude that dependency from your project and use the following drop-in replacement instead:

Here’s the trick: Inside that log4j-over-slf4j.jar, you’ll find classes like org.apache.log4j.Logger, but they have nothing to do with Log4j! Instead, these are SLF4J specific classes, i.e. your code 'thinks' it calls Log4j, but instead everything gets routed to SLF4J. (The same is true for the other 'over-slf4j' libraries, except for the JUL library, which you can read about here).

Which in turn means, that you, as the end-user of a library, can use whatever logging library you want, even though the original library creator wanted you to use Log4j specifically.

Real-Life

So, depending on what you are building and the third-party libraries you are using, you might end-up with the following libraries in your classpath:

Main Takeaway

With SLF4J, you code to the API, and can choose the implementation (Log4j, Logback etc.) later (compile time). In addition, you can use bridging libraries to make legacy 3rd party libraries 'speak' SLF4J.

While all of this might look scary for beginners, it all makes sense with a bit of experience.

One might think that SLF4J, with all the surrounding logging libraries, would cover almost all logging needs. Seems to be not so. In 2014, a successor to the Log4j (v1) library was released, called Log4j2 - being a complete rewrite and of course heavily inspired by all other existing logging libraries.

Additionally, just like SLF4J, or JCL, or Commons Logging, Log4j2 can be used as a bridge, as it comes with two dependencies:

An API dependency:

And the actual logging implementation:

The API dependency works with a variety of other logging frameworks, just like SLF4J or JCL do. You can drop in Log4j2’s own logging implementation, use an SLF4J implementation, or use one of the bridging/adapter libraries to setup your logging in whatever way you wish. Your code, however, will only reference the Log4j2 classes like so:

If you have read the previous sections, you might conclude that SLF4J and Log4j2 have a lot in common and it is unclear, why one would want to use Log4j2 instead of just sticking with SLF4J.

The creators of Log4j2 have tried to answer this question themselves here, with the main difference seemingly being the performance (AsyncLogger, Garbage Collections] and the slightly better API (Abilities to log objects, not just strings, Lambda Support etc).

Though it should be said that, while these reasons might make a difference in complex high-load applications, developers working on 'normal' applications likely won’t notice a difference.

Talking about logging libraries wouldn’t be complete, without mentioning JBoss-Logging. It’s yet another logging bridge, very similar to SLF4J or JCL, so you’ll have to use it with another logging implementation, or even SLF4J itself.

It’s main claim to fame, compared to these other logging bridges, seems to be its internationalization features. Other than that there seems to be very little reason to base your project entirely on jboss-logging, though you will find projects like Hibernate use it, because both libraries are developed under the RedHat umbrella.

If you have a look across different Java projects in your organization, or even just look at one project, you’ll likely see a variety of ways that people try to get a Logger instance: The class that enables them to log in the first-place.

This can take the looks of:

Now what should this look like instead? To which there is an easy answer. If the class you are creating, and the method you are calling to create that class, both have the word "logger" inside, then call the variable 'logger'.

Don’t fret too much about static or non-static, final or non-final, just make sure to be homogeneous in your choice, throughout your entire project.

And finally, there is really no need to UPPER_CASE your logger just for the sake of it, certainly not as the only exception in your codebase.

An insanely interesting topic is: To which log level should you actually log to? You have the choice of TRACE, DEBUG, INFO, WARN, ERROR, FATAL and a fair amount of developers feel unsure of when to use which one.

Here’s a general approach that I’ve seen used successfully in a few places, but note that this is not written in stone (see screencast here). Make changes to these guidelines where appropriate, but make sure you have a solid use case and reasoning for it. And most importantly, make sure that your developers and operations guys are on the same page.

Now let’s first have a look at the "error group" log levels individually, and what you might use them for.

To make correlation of log statements strong, there’s another important concept to know, especially if you are working with multiple distributed processes (microservices): The Mapped Diagnostic Context (MDC) or Thread Context.

Imagine you have a user-request coming in, that is routed to multiple, different microservices. When something goes wrong, a request fails, how do you know which log lines from which microservices correspond to that very request. Easy: You need a generated request-id that you want to log out with every log message.

And because you are lazy, you don’t want to have to manually log out that id, it should just work automatically. That’s where the MDC comes in.

Somewhere in your code, in an HTTP servlet-filter, you’ll have something like this:

That’s enough. Just one call to a static method.

Later, in your application code, you will continue logging as usual:

You also need to configure your log library to log out the MDC variable with every log statement (see here). Which will give you log messages that look like this:

Then it’s very easy to correlate all corresponding log messages, you simply have to specify or search for the same request-id across all your log files or in your centralized logging server.

It goes without saying that you should avoid (read: must not) logging out sensitive information: User credentials (i.e. passwords) or financial information (like credit card numbers etc.) or similar sensitive user details.

Depending on the complexity of your system, you might however not want to worry about fixing up every individual log statement in your system (though you might be forced to, by means of an audit), but have more of a generic solution that makes sure that certain information is masked - either partially or completely, depending on the security standards you need to adhere to.

In the case of Log4j2 for example this means writing a custom LogEventPatternConverter, that masks log events according to your regulations.

Obviously, a full masking solution is out of the scope of this guide, but you can get some pointers here and here.

Another topic that isn’t really covered in detail anywhere, is WHAT exactly to write inside your log statements. And that brings us to the concept of proactive help.

A great example is the Spring Boot framework. When you are building a web application with Spring Boot and start it up for testing, the application will run under port 8080, so you can access it in your browser from http://localhost:8080.

Sometimes it happens, that you have another Spring Boot application or an older version of the same application already running on port 8080. Which means you cannot start up your application as that will fail. In older Spring Boot versions, they simply logged out the "raw" exception, which looks like this:

Developers can of course make the mental translation needed to go from "Failed to start connector" → "Another Spring Boot instance is running", but a better way would be what Spring Boot offers in newer versions:

It could be even more improved by adding that it could be a random process or just another (IDE) instance of your application that needs to be shutdown manually.

The main takeaway here is however, that it makes sense to not only log out an error message wherever you can, but also hint at possible fixes/calls for action, if you can. That will save time later on, when analysing bugs and the corresponding log files.

(If you want to see more examples of proactive help, you can also have a look at the Apache Wicket framework, which comes with a 'suggested fix' for a fair amount of errors. Have a look at its source code for more details.)