Using a Custom Log4net Appender with SmartInspect

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

Introduction
Requirements
Appenders
Closing Words

Introduction

This article explains how to integrate SmartInspect with the popular .NET logging framework log4net by writing a custom log4net appender. If you're an experienced log4net 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 log4net appenders and shows you in detail how to integrate log4net 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 log4net, 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 log4net 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 log4net 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 log4net, 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 log4net is that you can plugin your own appenders, thus extending the built-in capabilities of log4net 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 .NET itself, you need a recent build of log4net (I've used log4net 1.2.10), 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 log4net package which can be found on the SmartInspect resources page:

Appenders

The SmartInspect for log4net 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 log4net 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 log4net compatibility layer and your SmartInspect loggers. You get the best of both worlds. You can reuse your existing log4net statements and slowly migrate to (or try out) 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 log4net 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 Gurock.SmartInspect.dll 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 Gurock.SmartInspect.Log4net.dll .NET assembly which in turn includes the SiAutoAppender. This appender receives the log events from the log4net 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:

using System;
using System.IO;
using log4net;
using log4net.Config;
using Gurock.SmartInspect;

public class SiAutoExample 
{
	public static void Main(string[] args) 
	{
		XmlConfigurator.Configure(new FileInfo("SiAuto.config"));
		SiAuto.Si.Enabled = true; // Usual SiAuto configuration
		ILog log = LogManager.GetLogger("log4net Test");
		log.Info("Info");	
	}
}

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

<log4net>
	<appender name="S" type="Gurock.SmartInspect.Log4net.SiAutoAppender">
		<layout type="log4net.Layout.SimpleLayout" />
	</appender>
	<root>
		<level value="DEBUG" />
		<appender-ref ref="S" />
	</root>
</log4net>

We merely associate a SiAutoAppender with the root logger of log4net. That's it, no more configuration needed and all your log4net 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 log4net documentation about layouters for more information.

SmartInspectAppender

The SmartInspectAppender is also included in the Gurock.SmartInspect.Log4net assembly. Like the SiAutoAppender, it receives logging events from log4net 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:

using System;
using System.IO;
using log4net;
using log4net.Config;

public class SiAutoExample 
{
	public static void Main(string[] args) 
	{
		XmlConfigurator.Configure(new FileInfo("SmartInspect.config"));
		ILog log = LogManager.GetLogger("log4net Test");
		log.Info("Info");	
	}
}

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

<log4net>
	<appender name="S" type="Gurock.SmartInspect.Log4net.SmartInspectAppender">
		<layout type="log4net.Layout.SimpleLayout" />
		<connections value="pipe()" />
		<appName value="Test Application" />
	</appender>
	<root>
		<level value="DEBUG" />
		<appender-ref ref="S" />
	</root>
</log4net>

This time we are specifying the SmartInspectAppender and configure a connection string and the application name in log4net'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 log4net 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 log4net with SmartInspect, feel free to contact me at tg@gurock.com.

« Return to overview