Flogger: A Fluent Logging API for Java

What is it?

Flogger is a fluent logging API for Java. It supports a wide variety of features, and has many benefits over existing logging APIs.

Come for more self-documenting log statements:

logger.atInfo().withCause(exception).log("Log message with: %s", argument);

Stay for additional features that help you manage your logging better:

logger.atSevere()
    .atMostEvery(30, SECONDS)
    .log("Value: %s", lazy(() -> doExpensiveCalculation()));

Benefits

While some users prefer "fluency" as a style, this is not what the argument for Flogger rests on. Flogger offers these key, concrete advantages over other logging APIs:

Logging at disabled levels is effectively free. Finally, you can add as many fine-grained log statements to your code as you want, without worry.
Flogger also has very high performance for enabled log statements.
A fluent API accommodates a variety of present and future features without combinatorial explosion, and without requiring separate logging façades.
Less reliance on long parameter lists makes it harder to misuse and yields more self-documenting code.

Yet another logging API?

The field of open-source Java logging APIs is already extremely crowded, so why add another?

To paraphrase Douglas Adams "Google's codebase is big. Really big. You just won’t believe how vastly hugely mind-bogglingly big it is". Inevitably this resulted in many different debug logging APIs being used throughout the Java codebase, each with its own benefits and issues. Developers were forced to switch between APIs as they worked on different projects, and differences between APIs caused confusion and bugs.

Flogger is the result of an attempt to create a unified logging API, suitable for the vast majority of Java projects in Google.

For something of this magnitude it would have been preferable to use an existing logging API, rather than creating and maintaining our own. However, the Java Core Libraries Team (i.e. Guava maintainers) concluded that Flogger was not slightly better than the alternatives, but much better.

By switching the majority of Java code in Google to use Flogger, many thousands of bugs have been fixed and the cost to developers of learning new logging APIs as they move through the codebase has been eliminated. Flogger is now the sole recommended Java logging API within Google.

How to use Flogger

1. Add the dependencies on Flogger

All code that uses flogger should depend on com.google.flogger:flogger:<version> and com.google.flogger:flogger-system-backend:<version>.

Note: the dependency on flogger-system-backend is only required to be included when the binary is run. If you have a modularized build, you can include this dependency by the root module that builds your app/binary, and can be runtime scope.

2. Add an import for `FluentLogger`

import com.google.common.flogger.FluentLogger;

3. Create a `private static final` instance

private static final FluentLogger logger = FluentLogger.forEnclosingClass();

4. Start logging:

logger.atInfo().withCause(exception).log("Log message with: %s", argument);

Log messages can use any of Java's printf format specifiers; such as %s, %d, %016x etc.

Note that you may also see code and documentation that references the GoogleLogger class. This is a minor variant of the default FluentLogger designed for use in Google's codebase. The FluentLogger API is recommended for non-Google code, since its API should remain more stable over time.

More information

Flogger was designed and implemented by David Beaumont, with invaluable help from the Java Core Libraries Team and many other Googlers.

If you interested in a deeper dive into the rationale behind Flogger's API, please see Anatomy of an API.

HiskeyCheng/flogger