SMILA/Project Concepts/Logging

Description

Create concept of logging.

Discussion

Combination of LogService and Log4j/commons-logging

• Georg Schmidt: Currently I did not understand how such technologies will fit together or whether the are orthogonal approaches. If so which will be the suggested way of working? How do we handle backward compatibility e.g. to Lucene?

• • Andrey Basalve: LogService and Log4j/commons-logging don't contradict to each other. Nay we can use log4j/commons-logging to log event which was handled by LogService via implementing LogListener. On the other hand we can implement custom log4j appender which will send log messages to the OSGi LogService. What do you mean at backward compatibility (eg lucene doesn't use commons-logging)?

• Georg Schmidt: There are several applications/APIs that are using commons-logging/log4j. How do we support a migration process?

• • Andrey Basalve: I haven't any issues with it, it is needed to set org.apache.commons.logging.Log property and to configure log4j and then all application/API's begins work with it. Tested with Apache ODE and ActiveMQ bundles.

Mapping of log Methods of OSGi Logging Service and log4j/commons-logging

• Georg Schmidt: How do you map the log methods of those approaches?

• • Andrey Basalve: Added 'Mapping' Section.

Technical proposal

The main idea is using Commons-Logging interface and log4* as background. Also it is necessary to listen OSGi LogService.

Normalize log format

There is standard layout for log format:

%d   %-50.50c{2} %-5p [%-10.10t] - %m%n

2008-03-13 16:17:11,171   test.Log4JLogListener                              INFO  [Dispatcher] - org.eclipse.osgi: FrameworkEvent STARTLEVEL CHANGED
2008-03-13 16:17:11,171   test.Activator                                     DEBUG [Thread-1  ] - debug

Code Guards

Code guards are typically used to guard code that only needs to execute in support of logging, that otherwise introduces undesirable runtime overhead in the general case (logging disabled). Examples are multiple parameters, or expressions (i.e. string + " more") for parameters. Use the guard methods of the form log.is<Priority>() to verify that logging should be performed, before incurring the overhead of the logging method call. Yes, the logging methods will perform the same check, but only after resolving parameters.

Logs system

Commons-Logging and log4j

To use log4j as background for the Commons-Logging it is necessary to set up a two variables (in the $\{eclipse.home\}/configuration/config.ini where $\{eclipse.home\} is a path to the product folder)

org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger
log4j.configuration=file:${eclipse.home}configuration/log4j.properties

{info:title=Useful information} If you working in the eclipse you can add a following arguments to the VM arguments section in the Run As wizard: -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger -Dlog4j.configuration=file:${eclipse_home\}configuration/log4j.properties {info}

Also it is needed to add the org.apache.log4j package to the commons-logging bundle as dependency.

Import-Package: org.apache.log4j;resolution:=optional

For using logging system in the other bundles you should add Commons-Logging bundle as dependency and simply use Commons-Logging interface:

public class SomeClass {
 
    private static final Log s_log = LogFactory.getLog(SomeClass.class);
 
    public void someMethod() {
      if (log.isDebugEnable()) {    
           log.debug("Enter to some method");
      }
 
      ....
 
      if (log.isDebugEnable()) {    
           log.debug("Exit from some method");
      }
    }
}

It is possible to automatically reload a configuration file if it is changed. Both the DOMConfigurator and the PropertyConfigurator support automatic reloading through the configureAndWatch method. Because the configureAndWatch launches a separate wathdog thread, and because there is no way to stop this thread in log4j 1.2, the configureAndWatch method is unsafe for use in J2EE envrironments where applications are recycled.

{info:title=Configuring} The best way, in my opinion, is use our configuration management system (basis on OSGi ConfigurationAdminService) to configure log4j. It allows to dynamically update configuration and removes associating with file system. {info}

Java Logging

The newer logging API, which has been included in the JRE since 1.4, incorporates many of the same concepts as log4j. It has loggers and appenders.

//Get a logger; the logger is automatically created if it doesn't already exist
Logger logger = Logger.getLogger("com.mycompany.BasicLogging");
 
// Log a few message at different severity levels
logger.severe("my severe message");
logger.warning("my warning message");
logger.info("my info message");
logger.config("my config message");
logger.fine("my fine message");
logger.finer("my finer message");
logger.finest("my finest message");

OSGi LogService

The Log Service provides a general purpose message logger for the OSGi Service Platform. It consists of two services, one for logging information and another for retrieving current or previously recorded log information. The OSGi specification defines the methods and semantics of interfaces which bundle developers can use to log entries and to retrieve log entries.

There is an eclipse implementation of the OSGi LogService (org.eclipse.equinox.log bundle).

final ServiceReference reference = context.getServiceReference(LogService.class.getName());
final LogService logService = (LogService) context.getService(reference);
logService.log(LogService.LOG_DEBUG, "Test Log Message");

LogService vs log4j

Using the log4j in the OSGi LogService

There is a way to use log4j for logging messages from OSGi Log Service. For this it is necessary to implement LogListener(which uses log4j) and to register it via the LogReaderService OSGi Service.

public class Activator implements BundleActivator {
 
  private Log4JLogListener _listener;
 
  public void start(BundleContext context) throws Exception {
    _listener = new Log4JLogListener();
 
    ServiceReference reference = context.getServiceReference(LogReaderService.class.getName());
    final LogReaderService readerService = (LogReaderService) context.getService(reference);
    readerService.addLogListener(_listener);
  }
 
  public void stop(BundleContext context) throws Exception {
    final ServiceReference reference = context.getServiceReference(LogReaderService.class.getName());
    final LogReaderService readerService = (LogReaderService) context.getService(reference);
    readerService.removeLogListener(_listener);
  }
}

public class Log4JLogListener implements LogListener {
 
  private static Log s_log = LogFactory.getLog(Log4JLogListener.class); 
 
  public void logged(LogEntry entry) {
    switch (entry.getLevel()) {
      case LogService.LOG_DEBUG:
        if (s_log.isDebugEnabled()) {
          final Throwable throwable = entry.getException();
          if (throwable == null) {
            s_log.debug(getMessage(entry));
          } else {
            s_log.debug(getMessage(entry), throwable);
          }
        }
        break;
 
      ....
 
      default:
        throw new IllegalArgumentException("Unexpected log level " + entry.getLevel());
    }
  }
 
  private String getMessage(LogEntry entry) {
    final StringBuilder builder = new StringBuilder();
    builder.append(entry.getBundle().getSymbolicName());
    builder.append(": ");
    builder.append(entry.getMessage());
    return builder.toString();
  }
 
}

For implement and register LogService we need a bundle(and in particular BundleContext). There are two ways:

1. Create single bundle for this purposes.
2. Add LogListener implementation to the product bundle (BrandingBundle) and register it on start application.

I prefer the first way because is allows stop/update/start this service.

Using the the OSGi LogService in the log4j

On the other hand we can implement custom log4j appender which will send log messages to the OSGi LogService. For this we should create a special bundle which have the log4j appender implementation and track LogService.

public class LogServiceAppender extends AppenderSkeleton {
 
  protected void append(LoggingEvent le) {
 
    // getLogService use service tracker to obtain LogService 
    LogService logService = getLogService();
 
    if (logService == null) {
      return;
    }
 
    if (le.getLevel().equals(Level.DEBUG)) {
      logService.log(LogService.LOG_DEBUG, le.getRenderedMessage());
    } else if (le.getLevel().equals(Level.INFO)) {
      ...
    }
  }
 
}

Mapping

There are several different log levels in each log system and it is necessary to compare theirs.

Log4j	Commons Logging	Java Logging	OSGi LogService
Fatal	Fatal	Severe	Error
Error	Error	Severe	Error
Warn	Warn	Warning	Warning
Info	Info	Info	Info
Debug	Debug	Fine	Debug
Trace	Trace	Finer and Finest	Debug

Summary

There is an issue with a third party bundles because they are used different log systems. But we needed a centralized log. Therefore it is suggested to use log4j(in conjunction with commons-logging) as a basis because it is possible to easily redirect other loggers to log4j.