The Carbon Java Framework  

Logging with Apache Commons Logging

Logging Service Usage

Printer Friendly Version

Author: Akash Tayal (atayal at
Version: $Revision: 1.4 $($Author: atayal $ / $Date: 2003/04/14 10:28:11 $)
Created: March 2003


The Jakarta Commons Logging (JCL) provides a Log interface that is intended to be both light-weight and independent of numerous logging toolkits. It provides the middleware/tooling developer a simple logging abstraction, that allows the user (application developer) to plug in a specific logging implementation. Familiarity with high-level details of various Logging implementations is presumed. The Jakarta Commons Logging provides a Log interface with thin-wrapper implementations for other logging tools, including Log4J, Avalon LogKit, and JDK 1.4. The interface maps closely to Log4J and LogKit.

Code Usage

Imports required

To use Jakarta commons logging from a Java class, please include the following import statements:
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

For each class definition, declare and initialize a log attribute as follows:
public class CLASS
   private Log log = LogFactory.getLog(getClass());

Using the API

Messages are logged to a logger, such as log by invoking a method corresponding to priority. The org.apache.commons.logging.Log interface defines the following methods for use in writing log/trace messages to the log:

log.fatal(Object message);
log.fatal(Object message, Throwable t);
log.error(Object message);
log.error(Object message, Throwable t);
log.warn(Object message);
log.warn(Object message, Throwable t); message); message, Throwable t);
log.debug(Object message);
log.debug(Object message, Throwable t);
log.trace(Object message);
log.trace(Object message, Throwable t);

Semantics for these methods are such that it is expected that the severity, from highest to lowest, of messages is ordered as above.

In addition to the logging methods, the following are provided for code guards:

Code Example

Example of logging calls

/** log at appropriate level **/

// following logs at FATAL level
if (log.isFatalEnabled()) {
    log.fatal("Testing Fatal output");

// following logs at ERROR level
if (log.isErrorEnabled()) {
    log.error("Testing Error output");

// following logs at WARN level
if (log.isWarnEnabled()) {
    log.warn("Testing Warn output");

// following logs at INFO level
if (log.isInfoEnabled()) {"Testing Info output");

// following logs at DEBUG level
if (log.isDebugEnabled()) {
    log.debug("Testing Debug output");

// following logs at TRACE level
if (log.isTraceEnabled()) {
    log.trace("Testing Trace output");

Best Practices

General - Message Priorities/Levels

It is important to ensure that log message are appropriate in content and severity. The following guidelines are suggested:

  • FATAL - Severe errors that cause premature termination. Expect these to be immediately visible on a status console.
  • ERROR - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a status console.
  • WARN - Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a status console.
  • INFO - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum.
  • DEBUG - Detailed information on flow of through the system. Expect these to be written to logs only.
  • TRACE - More detailed information. Expect these to be written to logs only.

General - Default Message Priority/Level

By default the message priority should be no lower than info. That is, by default debug message should not be seen in the logs.

Why info level instead of debug?
You want to have exception/problem information available for first-pass problem determination in a production level enterprise application without turning on debug as a default log level. There is simply too much information in debug to be appropriate for day-to-day operations.

Severity Mapping

Following table shows the mapping between Commons/Carbon severities and severity provided by various log implementations

Carbon SeverityEnum Commons Log Log4J JDK 1.4 Logger LogKit
Fatal Fatal Fatal Severe Fatal_Error
Error Error Error Severe Error
Warn Warn Warn Warning Warn
Info Info Info Info Info
Debug Debug Debug Fine Debug
Trace Trace Debug Finest Debug


Resource URL

Commons Javadoc API documents

Commons API


This documenation is prepared using the user guide and documentation available on Jakarta Commons Project.

Copyright © 2001-2003, Sapient Corporation