Summary

I used…

• FileAppender+MinimalLock to be able to read the log file while the system is running
• three Appenders one each for minimum LogLevel: debug, info and warning
• one logger per class – gave me a readable “tag” on each log item, but filtering problems with nhibernate
• an LoggerMatchFilter for nhibernate with AcceptOnMatch=false to reject messages

Getting started

To get any logging at all, you need to create a logger and configure it. The code for doing this and writing something to the log looks like this:

log4net.Config.XmlConfigurator.Configure();
var log = log4net.LogManager.GetLogger(this.GetType());
log.Debug(“debug message”);

(Yes, it’s not a typo – the namespace is lowercase, I know it’s hard, by try to ignore that…)

Those few lines of course require configuration, the app/web.config is a good place for that so let’s go there now. The config needs three parts; a configSections entry, a log4net appender and a log4net root directive. See for yourself:

<configuration>
  <configSections>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net"/>
  </configSections>
  <log4net>
    <appender name="RollingFileAppenderAll" type="log4net.Appender.RollingFileAppender">
      <file value="c:\logs\projectx_log_debug.txt" />
      <appendToFile value="true" />
      <rollingStyle value="Composite" />
      <datePattern value=".yyyyMMdd" />
      <maxSizeRollBackups value="10" />
      <maximumFileSize value="1MB" />
      <staticLogFileName value="true" />
      <lockingModel type="log4net.Appender.FileAppender+MinimalLock" />
      <layout type="log4net.Layout.Pattern Layout">
        <conversionPattern value="%date [%thread] %-6level %logger - %message %exception%newline" />
      </layout>
      <filter type="log4net.Filter.LoggerMatchFilter">
        <loggerToMatch value="Jayway.ProjectX" />
      </filter>
      <filter type="log4net.Filter.DenyAllFilter" />
    </appender>
    <root>
      <level value="ALL" />
      <appender-ref ref="RollingFileAppenderAll" />
    </root>
  </log4net>

Appender

The appender entry represents a consumer of the logging information. Here I use a RollingFileAppender which rotates the log file periodically, as specified by the datePattern. MaximumFileSize is also honored and breaking that limit also rolls the log file over.

The logging in my project is done from a WCF service with HTTP endpoints. I have testing endpoints (e.g. /log/debug) that just shows the latest log file – very handy. To be able to read from the log file while the service is running, the lockingModel has to be set to FileAppender+MinimalLock which tells log4net to lock the log file as little as possible, instead of all the time which is the default. This will create a performance hit for the logging, but that’s ok for my setup. Specifying a staticLogFileName causes log4net to always log to a specific file, and then rename older log files according to date etc. This allows my hand coded log reader to always know where the latest log info is.

Root

The root section is what connects a log consumer (the appender) with a log producer (the ILog in the code). The root section can be replaced by specifying a specific logger (<logger name=”myLogger”>), and that would only process log data from that specific logger. Which logger to process data from brings us to the next topic – filtering.

Filtering (and getting rid of nhibernate output)

As you probably know, logs can either say to little, just about right, or WAY too much – that’s where the power of filtering comes in. LogLevel is the most natural and direct thing to filter on. In my service, I have three different log files all set to different levels; one for everything, one for at least Info and one for at least Warning. This is done by having three different appender entries and three appender rows in the root entry. This is where I started bumping into problems, read on…

One logger per class

I followed the advice from Jim’s log4net recommended practices to create one logger per class – not to use one logger for the entire application. The theory behind this is to have a tag on each log entry allowing you to have a log that “reads like a novel”. I like the idea and it’s very nice to always know what class issued the statement. Here’s an example of log output:

10:24:57,830 [10] INFO   Jayway.ProjectX.Service - ping called
10:24:57,833 [10] WARN   Jayway.ProjectX.Proxy - ping called
10:28:03,084 [10] INFO   Jayway.ProjectX.RequestCreator - creating request
10:28:03,095 [10] INFO   Jayway.ProjectX.Proxy - sending request
10:28:03,097 [10] WARN   Jayway.ProjectX.Proxy - could not reach host
10:28:03,907 [10] INFO   Jayway.Common.Cache - getting items from cache
10:28:03,910 [10] INFO   Jayway.ProjectX.Proxy - returning cache items
10:28:28,816 [10] INFO   Jayway.ProjectX.Service - returning 100 items

I made this happen by using a logFactory that I inject into each class, instead of a log. (I’m not using an IoC container, was overkill for this project). The web service class looks like this:

private readonly ILogFactory _logFactory;
private readonly ILog _log;
public WebService()
{
   _logFactory = new LogFactoryLog4Net();
   _log = _logFactory.Create(this);
}

whilst one of the classes begins with this:

private readonly ILog _log;

public Proxy(ILogFactory logFactory)
{
    _log = logFactory.Create(this);
}

Using this technique, it would be very easy to temporarily add an appender for just a part of your system – giving you awesome control of the logging output.

nhibernate

NHibernate also uses log4net – and since I don’t have one logger but one per class, I have to use the “root” logger directive. The root logger funnel everything sent to the log4net system. This caused me to get all the nhibernate debug info in my logs. This was not what I wanted.

Inverted filtering

To get the kind of filtering output I wanted I had to use two kinds of filters; the LoggerMatchFilter and the LevelRangeFilter. Filtering in general in log4net works so that if you hit a filter that matches, it breaks the filtering chain and returns. This took me a while to figure out, I thought it just acted as a filter that could be chained, so that I could specify more and more filters to get more and more fine-grained output. But, back to the code:

<filter type="log4net.Filter.LoggerMatchFilter">
  <loggerToMatch value="NHibernate" />
  <AcceptOnMatch value="false"/>
</filter>
<filter type="log4net.Filter.LevelRangeFilter">
  <levelMin value="INFO" />
</filter>
<filter type="log4net.Filter.DenyAllFilter" />

As you can see, I use the LoggerMatchFilter inverted. So, when it hits an item that matches “NHibernate” it will immediately reject it. If it does not match, it will continue down the chain and check the level. I figured this out by reading Matthew Daugherty’s log4net tutorial, highly recommended.

What you really want is to have the midlet write the log to your development PC instantaneously and free of charge, then you can log whatever you want to pinpoint your bug. This could be accomplished by logging over Bluetooth. Previously you had to write your own code to handle the logging and Bluetooth communication as well as a server to which the midlet connects and sends the log messages, but now there is a powerful logging framework for Java ME that offers this support out of the box. The framework is MicroLog and is open source under the Apache Software License, so it is free to use as you see fit. MicroLog can be configured with one or more appenders that takes care of the logging messages and sends them to the right destination and each appender can have its own formatter to format the messages appropriately. This is very similar to log4j, so if you have used log4j before, MicroLog is very easy to learn. If you are using Maven 2 you will be happy to know that MicroLog is built using Maven 2 and is available in a public repository.

Setting up MicroLog to use Bluetooth and log to your PC is simple. It only requires that you setup your Logger:

private final static Logger log = Logger.getLogger(TestMidlet.class);

and that you configure it to use a BluetoothSerialAppender, which is done like this:

log.addAppender(new BluetoothSerialAppender());

Now your midlet is all set to start logging over Bluetooth. For a full midlet example see the following code:

package se.jayway.me;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.CommandListener;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.TextBox;
import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;

import net.sf.microlog.Logger;
import net.sf.microlog.bluetooth.BluetoothSerialAppender;

public class TestMidlet extends MIDlet
{

	private final static Logger log = Logger.getLogger(TestMidlet.class);

	public TestMidlet()
	{
		configureMicroLog();
	}

	protected void destroyApp(boolean arg0) throws MIDletStateChangeException
	{
		log.info("Destroying application...");
	}

	protected void pauseApp()
	{
		log.info("Pausing application...");
	}

	protected void startApp() throws MIDletStateChangeException
	{
		log.info("Starting application...");
		final TextBox textBox = new TextBox("Text", "My text", 100, 0);
		textBox.addCommand(new Command("Log", Command.SCREEN, 0));
		textBox.setCommandListener(new CommandListener() {
			private int counter;

			public void commandAction(Command c, Displayable d)
			{
				log.debug("You clicked " + counter++);
				log.debug(textBox.getString());
			}
		});
		Display.getDisplay(this).setCurrent(textBox);
	}

	private void configureMicroLog()
	{
		log.addAppender(new BluetoothSerialAppender());
	}
}

Build and deploy this midlet to your Bluetooth enabled device, supporting JSR-82, the Bluetooth API and make sure that Bluetooth is turned on.

Next you need to get the Bluetooth server that will receive and print the logging messages to standard out. The server is also available in a public Maven repository. Just download the version that ends with -jar-with-dependencies.jar. This file contains all its dependencies. Now make sure that your Bluetooth unit is on and discoverable on your PC. Then start the server with the following command:

java -cp microlog-servers-1.1.0-SNAPSHOT-jar-with-dependencies.jar net.sf.microlog.server.btspp.MicrologBtsppServer

You might have to change the jar file name if it is not the same as the one you downloaded, then just replace it with the file name of your own microlog-server jar file.

The server starts up and registers a logging service with a unique UUID that the phone will try to locate and connect to. Now start the midlet and see how it will start logging over the Bluetooth connection.

The first phone I tested was a SonyEricsson C905 and it worked perfectly from the start. Then I tried to use a SonyEricsson P990i and for some reason it failed to locate the logging server with the unique UUID. I was unable to determine the reason why it failed to locate the service, so instead I added support to the BluetoothSerialAppender to specify the url of the Bluetooth logger server. Using this and setting the server url to my PC it connected flawlessly to it and started logging. So if you experience problems when your midlet connects to the PC or if you are using multiple logger servers within the Bluetooth range of your device try specifying the server url that the BluetoothSerialAppender should connect to. The url of the server is shown when starting the logger server. This url does however contain a channel that is not possible to determine through the used API's, but it does start on 1 and increases. For each session I always got the same channel and it was only the next day that it changed and I got channel 2 instead, so try with 1 to start with and if that does not work increase it by one and try again. It will most likely work first or second time.

Now you are free to log as much as you want and do not have to restrict your logging during the development phase of your project. Neither is there a reason for writing your own Bluetooth logger, just use MicroLog.