Using logging in Java libraries

While logging can be very useful in an application, it's still a question to me whether it is desirable to use logging statements in a library. If the library is well-designed, is there a need for logging? Is it not up to the application to log what seems relevant to it?

Use cases for logging
There are use cases for logging events in your application, including performance logging of audit logs. These can be seen as the implementation of functional requirements, and are typically implemented using AOP. The application signals some sort of an event, and one implementation could be to simply write out the event in a logfile. But these kinds of logging are hardly ever implemented in libraries, as they are the result of functional requirements.

Another typical case of logging is error handling. But a well-designed library should signal the application using the library something is wrong, and let the application decide what to do when an error occurs. Often this involves at least logging it, once and only once by the way!

So why include logging in a library? It might be useful if it's a closed source library you can't easily debug. But for open source libraries using a debugger is the way to go if you want to know what's going on.

Logging in a library
If a library has logging in it anyway, how should it be implemented ideally? There are some useful tips listed in the dark art of logging about what and how to log in general, but there's more...

In a library, please think about the logging library dependency. When writing code, an important part of controlling dependencies is by depending on interfaces instead of implementations. So when depending on a logging library, please just depend on an interface or facade (such as slf4j) instead of an implementation (such as log4j). A single dependency on e.g. slf4j-api would be sufficient, let the application using the library decide which implementation it wishes to use.

Unfortunately there are still a lot of libraries out there depending on commons-logging, log4j or other implementations. Using these libraries in an application involves a process of excluding the logging dependencies and including the slf4j bridging implementations, e.g. using the Maven dependency management. This way the applications and its libraries all log via the slf4j-api, and a single logging implementation can be chosen by the application or the environment it is deployed on (OSGi container anyone?).

Using log4j
Finally a special note to the log4j adepts out there. If you insist on using log4j in your library, try to avoid depending on the log4j appenders and filters, or use the PropertyConfigurator. Doing so makes it impossible to use the slf4j bridging.

It's also not a good idea to include a log4j.properties file in your library jar. Since log4j looks for a config file on the classpath, this config file might get to be used for the entire application although the application adds a config file itself to the classpath. In that case it's a matter of who comes first on the classpath, which might lead to unexpected logging behavior that is really hard to figure out.

It is in fact a tip if you're using log4j and your application logging don't seem to use your own log4j.properties: search the classpath, including third-party jars, for other config files.