Getting to Know Gibraltar – Swapping Trace For Log

You’ll recall from the last post that we have the following code:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Diagnostics;

namespace GibraltarGettingStartedApp
{
    class Program
    {
        static int Main(string[] args)
        {
            Trace.WriteLine("About to Blow up...");
            int zero = 0;
            try { return 1 / zero; }
            catch (DivideByZeroException e)
            {
                Trace.WriteLine("Error: " + e.Message);
            }
            Trace.Close();
            return 0;
        }
    }
}

Showing us that we can get Gibraltar working with the Trace code that we already had in our code base. That’s a huge advantage if you are already using the Trace functionality in your code.

However, as you start working with Gibraltar, you’ll find that it supports it’s own logging API that offers several distinct advantages over Trace.WriteLine. There may come a time when you wish to take advantage of our better API. If so, you’ll want to swap out all of your Trace commands or, if you have a very large application, you may decide just to swap out the calls in a particular area. In this post, we are going to examine how easy it is to do that.

In turns out all that’s required is to replace the calls to Trace with calls to Gibraltar’s Log class. There is no need to touch the Gibraltar “plumbing code” at all.

Doing that, it looks like we’ve hit our first little wrinkle. While Log does have it’s own versions of Trace’s TraceInformation, TraceWarning and TraceError, there’s no direct analogue for Trace.Writeline. We used WriteLine because we wanted to do the simplest thing that worked. This means instead of just replacing Trace with Log, we can take this opportunity to move to a more rich method. Also, as there is no analogue for Trace.Close, so we’ll change our code to use Log.EndSession. Having made these changes, our code now looks like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Diagnostics;
using Gibraltar.Agent;

namespace GibraltarGettingStartedApp
{
    class Program
    {
        static int Main(string[] args)
        {
            Log.Verbose("About to blow up...");
            int zero = 0;
            try { return 1 / zero; }
            catch (DivideByZeroException e)
            {
                Log.Verbose("Error: " + e.Message);
            }
            Log.EndSession();
            return 0;
        }
    }
}

And as we can see, from Gibraltar Analyst, everything still works as expected:

So, we have successfully swapped out Trace for Log and not broken anything, great!

However, now that we’ve made the swap over to Log, we can take advantage of it’s overloaded methods to provide more information. Instead of just passing a string to Trace.TraceVerbose, when we are using Log, we can pass the exception too, which allows Analyst to capture it:

Of course, once we have successfully moved from Trace to Log we can take advantage of the richer API available with Log. Sticking with the example of logging information we can change our code to capture Category and caption along with our message:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Diagnostics;
using Gibraltar.Agent;

namespace GibraltarGettingStartedApp
{
    class Program
    {
        static int Main(string[] args)
        {
            Log.Verbose("Examples",
                "About to Blow up...",
                "Additional details can be provided for each log message");

            int zero = 0;
            try { return 1 / zero; }
            catch (DivideByZeroException e)
            {
                Log.Verbose(e,
                    "Examples",
                    "Error: " + e.Message,
                    "Exception type: {0}",
                    e.GetType().Name);
            }
            Log.EndSession();
            return 0;
        }
    }
}

And, as you can see, Analyst has recorded the category:

And the caption:

And the formatted description:

I mentioned that the Gibraltar API had a couple of advantages over the Trace API, we won’t go into them in detail here but one of them, which I think is very cool, is that the API will fail safe with regard to the format string. If you pass too many objects with regard to placeholders, like so…

using System;
using System.Collections.Generic;
using System.Linq;
using System.Diagnostics;
using Gibraltar.Agent;

namespace GibraltarGettingStartedApp
{
    class Program
    {
        static int Main(string[] args)
        {
            Log.Verbose("Examples",
                "About to Blow up...",
                "Additional details can be provided for each log message");

            int zero = 0;
            try { return 1 / zero; }
            catch (DivideByZeroException e)
            {
                Log.Verbose(e,
                    "Examples",
                    "Error: " + e.Message,
                    "Exception type: {0}",
                    e.GetType().Name,
                    "This shouldn't be here!",
                    "Nor should this!");
            }
            Log.EndSession();
            return 0;
        }
    }
}

Then Gibraltar won’t throw an exception, but will in fact continue to work as expected, matching the first object to the placeholder and ignoring the rest. Neat, eh?

If you make the inverse mistake, having too many placeholders, then Gibraltar will still work, but will record that error too, like so:

You should also check out these methods: Log.Critical, Log.Error, Log.Warning and Log.Information or see the complete API for the Log class.

Well let’s end this post here. Today we’ve looked at preparing our code to swap from Trace to Log, we’ve swapped to Log, using the analogue of the Trace methods, and then we’ve improved our logging by using the richer API available to us when we use Log.

Next time we’ll look at swapping out Log for a third party logging solution. Until then… happy coding!