Embracing SLF4J in Couchbase Java SDK 3.5

Hi Java/Scala/Kotlin devs!

When we release the next minor version of the JVM SDKs (date TBD), we’re planning to add the SLF4J API as a required dependency.

If your project already uses SLF4J, you can skip this post and get on with your day :slight_smile:

Why are we planning to require SLF4J?

Previous versions of the Couchbase JVM SDKs had a custom logging abstraction. This abstraction provided negative value, for all the reasons described in the SLF4J FAQ entry on whether making SLF4J an optional dependency is a good idea. Spoiler: it’s not a good idea :smiley:

Another motivation is that we’d like to repackage some third-party Open Source libraries that require the SLF4J API.

Finally, SLF4J has wide adoption, and is already included in many projects. We believe this change will affect very few users. (If we’re wrong, please let us know; that’s why we’re talking about this before the release.)

What is changing?

The SDK will always log directly to SFL4J. It will no longer detect the presence of Log4J2 without SLF4J, nor will it fall back to java.util.logging or write log messages directly to the console. (You’ll still be able to do all those things, but you’ll chose the behavior you want by selecting an appropriate SLF4J binding.)

The following SDK client settings will be deprecated, because they will have no effect:

  • logger.disableSlf4J
  • logger.fallbackToConsole
  • logger.consoleLoggerFormatter

How can I adapt to this change?

  • If your project already uses SLF4J, you won’t need to change anything.

  • If your project uses Log4j2 (but not SLF4J), add the appropriate SLF4J binding as a dependency of your project.

  • If your project doesn’t use SLF4J or Log4j2, and you don’t set logger.fallbackToConsole=true, you can retain the previous logging behavior by adding the SLF4J JDK14 Binding (slf4j-jdk14.jar) as a dependency of your project. This routes the SDKs log messages to java.util.logging, just like before.

  • If your project doesn’t use SLF4J, and sets logger.fallbackToConsole=true, then you can preserve the existing behavior by adding an SFL4J binding to your project, and configuring it to log to the console.

What version of the SLF4J API will the Couchbase SDK require?

The Couchbase SDK’s POM will declare a dependency on SLF4J API 1.7.x. You can upgrade it to version 2 by having you project declare a dependency on SLF4J API 2.x.

How can I make this a seamless transition?

The Couchbase SDK already uses the SLF4J API if it is present on the classpath. If you’re not already using SLF4J, you can prepare for the change by adding an SLF4J binding to your project today.