Writing a Custom Log4j Appender for SmartInspect

If you also develop for .NET, you may find the log4net equivalent of this article interesting as well.

Introduction
Requirements
Appenders
Closing Words

Introduction

This article explains how to integrate SmartInspect with the Java logging framework log4j by writing a custom log4j appender. If you're an experienced log4j user, you probably know about appenders (and custom appenders) and might already guess in what direction this article is going. If not, don't worry, this article explains everything you need to know about log4j appenders and shows you in detail how to integrate log4j with SmartInspect and how to reuse your existing logging infrastructure and logging calls with SmartInspect.

In case you are new to SmartInspect: SmartInspect is, like log4j, a full logging framework on its own. It has quite a few unique features such as a graphical viewer application for log analysis and a log server, but SmartInspect is still basically just a logging framework. If you are thinking about using SmartInspect in one of your projects to benefit from its unique features but already have large parts of your application instrumented with log4j statements, then this article is for you.

Chances are that you prefer to keep your existing log statements in place and do not want to replace all of them with the SmartInspect equivalents. I will show you how to do exactly this. I will explain how to redirect log4j statements to SmartInspect to benefit from its graphical viewer application and advanced capabilities, and will describe the different available options to integrate both tools and get the most out of it.

So, what is an appender and why do we need a custom one?

In the terminology of log4j, appenders are responsible for handling the output and transport of logging data ('output destinations'). There are appenders for writing log data to files, for logging over the network or to write the logging output to the terminal, just to name a few. One nice aspect of log4j is that you can plugin your own appenders, thus extending the built-in capabilities of log4j and integrating it with other tools. And that's exactly what we are going to do in this article.

Requirements

The requirements are simple. Besides Java itself of course (any version from 1.4 and up is working), you need a recent build of log4j (I've used log4j 1.2.15), a recent version of SmartInspect (the integration also works with the full version, of course, but the trial version is sufficient) and the SmartInspect for log4j package which can be found on the SmartInspect resources page:

Appenders

The SmartInspect for log4j adapter comes with two different appenders. Why two? The first appender, called SiAutoAppender, integrates nicely with the standard SmartInspect logging objects which are part of the static SiAuto class. This appender is perfect if you plan to leverage your existing log4j log statements but at the same time intend to benefit from some of the additional features or logging methods of the SmartInspect logging library. You can share the same connections and use the same log files with the log4j compatibility layer and your SmartInspect loggers. You get the best of both worlds. You can reuse your existing log4j statements and slowly migrate to (or try) SmartInspect without the need for rewriting your existing logging code.

The second appender, called SmartInspectAppender, on the other hand is the perfect choice if you just want to redirect your log4j log statements to a SmartInspect Console (the powerful viewer application of SmartInspect) or a SmartInspect log file and do not care about or do not plan to use any classes or features of the SmartInspect.jar library. This brings the power of the SmartInspect Console to your logging layer even if you do not plan to use the SmartInspect library directly yourself.

Choose whatever approach fits best. The following sections show you how both techniques work.

SiAutoAppender

The adapter contains the com.gurock.smartinspect.log4j package which in turn includes the SiAutoAppender. This appender receives the log events from the log4j loggers, converts them to logging objects the SmartInspect library understands and then redirects them to the static SiAuto.si object. This is of course done in a very optimized way, so that it's suitable for high-performance applications. The log packets are sent to the output destinations configured in the SiAuto.si object (with a SmartInspect connection string). This appender also respects the enabled and log level properties of your SmartInspect configuration.

A basic example with this appender looks as follows:

import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;
import com.gurock.smartinspect.SiAuto;

public class SiAutoExample 
{
	public static void main(String[] args) 
	{
		PropertyConfigurator.configure("SiAuto.ini");
		SiAuto.si.setEnabled(true); // Usual SiAuto configuration
		Logger logger = Logger.getLogger("Log4j Test");
		logger.info("Info");
	}
}

Note how we configure the SiAuto.si as usual and just plugin our custom log4j appender through the configuration file (with the PropertyConfigurator.configure call). A typical configuration file for this scenario may look as follows:

log4j.rootLogger=DEBUG, S
log4j.appender.S=com.gurock.smartinspect.log4j.SiAutoAppender
log4j.appender.S.layout=org.apache.log4j.SimpleLayout

We merely associate a SiAutoAppender with the root logger of log4j. That's it, no more configuration needed and all your log4j calls are automatically redirected to the SiAuto.si object which in turn can send the data to a SmartInspect Console (the default behavior) or store it in a SmartInspect log file. Applying a layout as in the last line of the above code is possible but an optional step. The layout influences the representation of the log message, please see the log4j documentation about layouters for more information.

SmartInspectAppender

The SmartInspectAppender is also included in the com.gurock.smartinspect.log4j package. Like the SiAutoAppender, it receives logging events from log4j loggers and converts them to SmartInspect logging objects. What's different with this appender is that it does not redirect the objects to the static SiAuto.si object but can be used independently from SiAuto. So, instead of configuring the SiAuto.si object, you pass your SmartInspect configuration properties such as the connection string and application name directly to the appender.

A basic example with this appender demonstrates this:

import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;

public class SmartInspectExample 
{
	public static void main(String[] args) 
	{
		PropertyConfigurator.configure("SmartInspect.ini");
		Logger logger = Logger.getLogger("Log4j Test");
		logger.info("Info");
	}
}

This looks similar, except that the SiAuto.si configuration is missing. The real difference lies in the underlying configuration file:

log4j.rootLogger=DEBUG, S
log4j.appender.S=com.gurock.smartinspect.log4j.SmartInspectAppender
log4j.appender.S.appName = Test Application
log4j.appender.S.connections = pipe()
log4j.appender.S.layout=org.apache.log4j.SimpleLayout

This time we are specifying the SmartInspectAppender and configure a connection string and the application name in log4j's configuration file. The connection string is a standard SmartInspect connection string and specifies the output destinations for the SmartInspect library. You have the choice between log files (text files for end-users, binary log files for analysis in the Console), named pipes for local live logging and TCP/IP for live logging over the network (more information about connection strings can be found in the SmartInspect manual after installing the trial version). You can even specify multiple output destinations by separating with commas (e.g., log files and live logging at the same time). The application name, on the other hand, is used to distinguish the log entries from multiple applications in the Console, to setup filters and automated views.

Closing Words

The log4j adapter package (including more detailed examples) can be downloaded from the SmartInspect resources page. If you have any questions about this article and on integrating log4j with SmartInspect, feel free to contact me at tg@gurock.com.

« Return to overview