Logging

This page collects rule-of-thumb directives to harmonize log messages in JEMMA (tentative release to complete the harmonization: v0.2).

Logging framework

JEMMA adopts OPS4J Pax Logging. It supports several logging backends, but in JEMMA SLF4j should be used whereas possible.

(To be confirmed by the community)

Client code example

SLF4J-style Example from the OPS4J Pax Logging documentation

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class MyClass
{
    private static final Logger LOG = LogFactory.getLogger( MyClass.class );
 
    private void treatment()
    {
	if( LOG.isDebugEnabled() )
	{
	     LOG.debug( "This is a debug message" );
	}
    }
}

Inside your maven-bundle-plugin configuration in your bundle's pom.xml

<Import-Package> org.slf4j,
...
</Import-Package>

Dependencies in your bundle's pom.xml

<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-api</artifactId>
	<version>${org.slf4j.version}</version>
</dependency>

Logging conventions and guidelines

Logging levels have been adapted from here. General guideline: log everything that is relevant, but, in doubt use the lowest level (e.g. having a lot of TRACE messages is better than having a lot of DEBUG messages).

Overall rules

• Exceptions shall be logged as in the following example
  • LOG.error("Exception occurred creating OSGi service", e);

FATAL

The FATAL level designates very severe error events that will presumably lead the full application to abort. No bundles shall use this level in JEMMA (as these errors are normally delegated to the OSGi runtime).

ERROR

The ERROR level designates error events that might still allow the application to continue running. In JEMMA this case covers rare error situations which do not allow the bundle to work properly.

Examples

• Port address in use for a bundle hosting a web-service.
• ...

WARNING

The WARN level designates potentially harmful or unexpected situations. In JEMMA warnings are used to signal potentially risky situation, but which do not interfere with the normal behavior of the bundle.

Examples

• Configuration file not found, creating a new one
• ...

INFO

The INFO level designates informational messages that highlight the progress of the application at coarse-grained level. You should think INFO as the level which is used when you are interested in looking at all bundles running together.

Examples

• start/stop events in BundleActivator, e.g.
  • LOG.info("Bundle jemma.osgi.javagal starting");
• ...

DEBUG

The DEBUG Level designates fine-grained informational events that are most useful to debug an application. In JEMMA, it can be used to log important aspects that help understanding the status and behavior of bundle internal features.

Examples

• Important method calls (e.g. belonging to a public Interface/API implemented by the current class)
• ...

TRACE

The TRACE Level designates finer-grained informational events than the DEBUG. In JEMMA this level should be used e.g. to outline the behavior of specific functions or internal classes. As a rule of thumb, you should always use TRACE, then, eventually, raise the level to DEBUG and above, if you think the logged info is relevant for higher levels.

Examples

• ...