JonnyReeves.co.uk » logging

Logging in ActionScript 3

Jonny — Mon, 22 Feb 2010 20:27:36 +0000

Logging is a fundamental part of any mid to large scale application, your application needs to be able to talk to other developers and Q&A engineers to help diagnose problems and gain insight into what’s going on under the hood. Jesse Warden recently wrote an excellent article on logging, however, my own implementation of logging AS3 apps differs so much that I thought it warranted a blog post.

The Problems

One of the most important things in OOP is to ensure that you avoid tight coupling; Jesse’s approach of using a static logger leaves your code scattered with a dependency on it.

Another point that Jesse makes is how important it is to include the name of the enclosing class when writing a log message,

… all log messages start with “ClassName::methodName” where ClassName is the name of the class you are in, and methodName is the current method the log message is in. It seems a major pain at first, but I guarantee you when you start removing them 2 months later, you know EXACTLY where to find it vs. that one trace that stays there for weeks because no one found where the bastard is.

I couldn’t agree more with this, having come from working on a massive application with thousands of log messages, not knowing where a message was originating from would have been a nightmare. However, Jesse’s approach is very manual and relies on your entire team being disciplined; not to mention the fact that as soon as you start refactoring that “ClassName::methodName” identifier is quickly going to get out of sync.

A Commons Solution

I feel that there is a simple solution to both the above problems in the form of the AS3 Commons Logging Framework. The framework provides an abstraction of logging which means your code is not dependant on any one implementation, plus it has the added benefit of automatically adding the name of the Class when writing a log message; winner!

Usage is pretty straight forward, but requires a little more setup than Jesse’s static helper approach; first of all your request a static ILogger instance from the LoggerFactory at the top of your class and then you are free to use it throughout the Class to write log messages, for example:

package uk.co.jonnyreeves
{
public class MyClass
{
// Request an ILogger instance for this Class.
public static const LOGGER : ILogger = LogFactory.getClassLogger(MyClass);

public function MyClass()
{
// Write a log message using the Logger instance.
LOGGER.info("Created instance of MyClass");
}
}
}

Using the TraceLogger implementation which the AS3 Commons Logger will default to, you would receive the following in your Flash TraceLog:

Sun Feb 21 10:33:29 GMT+0000 2010 [INFO]  uk.co.jonnyreeves.MyClass - Created instance of MyClass

The beauty of this approach is that the actual implementation of the ILogger interface is left to the LoggerFactory which means it can be switched at runtime. Another neat benfit is that the name of the Logger is taken from the encolosing Class which created it (via LoggerFactory.getClassLogger()). This mean that is you rename the Class as part of a refactoring effort, all the log messages contained in said class will automatically update.

Getting More Specific

So I’ve mentioned that your can decide the ILogger implementation at runtime, let’s see an example of that in action. My current Logging implementation of choice is the excellent DeMonsters Monster Debugger which reminds me a lot of the AS2 classic, LumnicBox in that it allows you to fully inspect the Object Graph at run time.

The first thing we need is to create an implementation of LogFactory which will return our ILogger instances upon request:

package uk.co.jonnyreeves.logging.util.monsterdebugger
{
import nl.demonsters.debugger.MonsterDebugger;

import org.as3commons.logging.ILogger;
import org.as3commons.logging.ILoggerFactory;

/**
* Provides a bridge between the AS3Commons Logging Framework and MonsterDebugger.
*
* @author John Reeves
*/
public class MonsterDebuggerLoggerFactory implements ILoggerFactory
{

/**
* Initialises MonsterDebugger
*
* @param target The Base Object you wisht to start graphing from (usually you will supply the
* Display Root DisplayObject).
*
* @param clearConsole Clears MonsterDebugger’s Trace Console when the initial connection is made.
*/
public function MonsterDebuggerLoggerFactory(target : Object, clearConsole : Boolean = true)
{
new MonsterDebugger(target);
if (clearConsole)
{
MonsterDebugger.clearTraces();
}
}

/**
* Factory Method, used to return an instance of ILogger to the AS3Commons Logging Framework.
*/
public function getLogger(name : String) : ILogger
{
return new MonsterDebuggerLogger(name);
}
}
}

Now all that’s left to do is to create the MonsterDebuggerLogger implementation of the ILogger interface; this will re-write all the LOGGER.info(), etc calls through to MonsterDebugger.

package uk.co.jonnyreeves.logging.util.monsterdebugger
{
import org.as3commons.logging.util.MessageUtil;
import nl.demonsters.debugger.MonsterDebugger;

import org.as3commons.logging.LogLevel;
import org.as3commons.logging.impl.AbstractLogger;

/**
* Provides a bridge between the AS3 Commons Logging implementation and Monster Debugger; it’s not perfect but it
* works for the most part.
*
* The Target of the log message will always be the name of the logger.
*
* The Object of the log message will vary depending on the parameters passed. If the message string is empty
* then the params Array will be logged. If the message string is not empty, the params Array will be used to
* tokenise the message string.
*
* Usage:
*    LOGGER.debug("Hello World"); // Outputs message: "(String) Hello World"
*    LOGGER.debug("Hello {0} {1}, "Jonny", "Reeves"); // Outputs message: "(String) Hello Jonny Reeves"
*    LOGGER.debug("", [ 1, 2, 3 ]); // Outputs message: "(Array)…" (which can then be inspected)
*
* Incorrect usage:
*    LOGGER.debug("Some Array", [1, 2, 3]); // Outputs message: "(String) Some Array" (which can’t be inspected)
*
* @author John Reeves
*/
public class MonsterDebuggerLogger extends AbstractLogger
{
public var level : int = LogLevel.DEBUG;

public function MonsterDebuggerLogger(name : String)
{
super(name);
}

override protected function log(level : uint, message : String, params : Array) : void
{
if (level >= this.level)
{
var target : Object = name;
var object : Object = getLogObject(message, params);
var colour : uint = getLogMessageColour(level);
MonsterDebugger.trace(target, object, colour);
}
}

private function getLogObject(message : String, params : Array) : Object
{
if (message == "")
{
// If the user only supplied a single param to log, we remove the params array which is enclosing it.
return (params.length == 1) ? params.pop() : params;
}
else
{
return MessageUtil.toString(message, params);
}
}

private function getLogMessageColour(level : int) : uint
{
var colour : int;
switch (level)
{
case LogLevel.FATAL:
case LogLevel.ERROR:
colour = MonsterDebugger.COLOR_ERROR;
break;

case LogLevel.WARN:
colour = MonsterDebugger.COLOR_WARNING;
break;

default:
colour = MonsterDebugger.COLOR_NORMAL;
break;
}
return colour;
}

override public function get debugEnabled() : Boolean
{
return LogLevel.DEBUG >= level;
}

override public function get errorEnabled() : Boolean
{
return LogLevel.ERROR >= level;
}

override public function get infoEnabled() : Boolean
{
return LogLevel.INFO >= level;
}

override public function get warnEnabled() : Boolean
{
return LogLevel.WARN >= level;
}

override public function get fatalEnabled() : Boolean
{
return LogLevel.FATAL >= level;
}
}
}

The code here is fairly self documenting with the protected log() method proxying all the logging requests through to MonsterDebugger. Because the creators of the AS3Commons Logging Project specified the message param to have a datatype of String, we are forced to do a little bit of a workaround when we want to dump Objects out to the MonsterDebugger console. There is an open ticket on the AS3Commons project page should you wish to request a change.

The last piece of the puzzle is to swap the AS3Commons LoggingFactory implementation, this is very straight forward and requires a single line of code during your application’s startup routine (preferably before any logging takes place).

package
{
import uk.co.jonnyreeves.logging.util.MonsterDebuggerLoggerFactory
import flash.display.Sprite;

/**
* Application Entry Point.
* @author John Reeves
*/
public class MyApp extends Sprite
{
public function MyApp()
{
LoggerFactory.loggerFactory = new MonsterDebuggerLoggerFactory(this);
}
}
}

Once this is done you are free to start using the LoggingFactory as per the example further up the page. Your log messages should now show up in the MonsterDebugger logging console.

The State of Logging in ActionScript 3

Jonny — Sun, 19 Oct 2008 11:14:45 +0000

I’ve been looking at Logging Frameworks in ActionScript 3 over the past few days and I’m afraid that I’m slightly at a loss as for which approach is the best to take. There are a few Logging Frameworks out there, but Adobe has kindly supplied an intrinic Logging Framework, however, it’s not without it’s shortcomings.

The biggest problem that I’ve come up against is that there is no easy way to set the Category for the Log. The Flex Logging Framework allows you to set the category of the log when you retrieve the ILogger instance. This can in turn be used by the Log Filtering system to specify which categories you would like to log. Ideally you set the category String to be the name of the Class you are currently Logging, however, due to the rather shaky reflection tools available, there’s no easy way to automatically get the name of the current Class. To compound the problem even further, getQualifiedClassName returns illegal characters (The semi-colon separating the Package and the Class Name) and Flex Logging Framework will throw and Illegal Arguments error if you try and use it as the category name. So, in order to have automatic categories generated, we have to do a bit of a curly shuffle with a StackTrace and a Helper Method

package uk.co.jonnyreeves.logging
{
import mx.logging.ILogger;
import mx.logging.ILoggingTarget;
import mx.logging.Log;
import flash.utils.getQualifiedClassName;

/**
* Flex Logger Helper, automatically returns the Category Name when used inside
* a Class.
*
* @author jonny reeves
*/
public class Logger
{
/**
* Returns an instance of Flex Logger with the correct category name for the calling Class
*
* @return ILogger instance with the correct category set for the calling Class.
*/
public static function getLogger() : ILogger
{
var category : String = "";
category = getCallerFromStackTrace();
return Log.getLogger(category);
}

/**
* Triggers a StackTrace and extracts the calling method from it, neat.
*/
private static function getCallerFromStackTrace() : String
{
var callerMethod : String = "";
var nullArray : Array;

// Pop a StackTrace by creating a RunTime error.
try
{
nullArray.push("whoops");
}
catch (e : Error)
{
var stackTrace : String = new Error().getStackTrace();
}

// Extract the ClassName from the StackTrack
if (stackTrace != null)
{
var parts : Array = new Array();
stackTrace.split("\n").join("");
parts = stackTrace.split(" at ");
if (parts[3] != null)
{
// Handle Both Class Init and internal method cases
if (parts[3].indexOf("$cinit") != -1)
{
callerMethod = parts[3].split("$cinit")[0];
}
else
{
callerMethod = parts[3].split("/")[0];
}
}
}

return getCategoryNameFor(callerMethod);
}

/**
* Helper method which takes an ActionScript 3 Formatted Class Name
* and replaces the semi-colons seperating the package and Class name
* with a Single Period for use as teh Flex Logging Category name
*
* @param qualifiedClassName
* @return String Legal Flex Logging Category String
*/
private static function getCategoryNameFor(qualifiedClassName : String) : String
{
return qualifiedClassName.indexOf("::") > -1 ? qualifiedClassName.split("::").join(".") : qualifiedClassName;
}
}
}

This can now be used inside any Class you wish to Log by delcaring a private, static instance of ILogger, for example:

package uk.co.jonnyreeves.logging
{
public class LoggingExample
{
/**
* Instance of the Flex Logging Framework via the Logger Helper Class which will
* automatically set the Category name to uk.co.jonnyreeves.logging.LoggingExample
*/
private static var Logger : ILogger = Logger.getLogger();

/**
* You can now log away, don’t forget to initialise your Flex Logger Instance (Log) first
* by setting the Target Publisher (not shown).
*/
public function LoggingExample()
{
Logger.info("Hello World!");
}
}
}

Although this is helpful it still does not address a couple of other fundamental issues:

The output from the Flex Logging Framework does not include the enclosing method or line number from which the error was triggered (although this information can extracted from a StackTrace and automatically appended to the Logged Message by the Publisher).
The Flex Logging Framework does not intelligently handle datatypes – unfortunately we can only passing String’s to Flex Logger – however, we can get around this by making use of 3rd Party Consoles such as Thunderbolt (which also, helpfully includes a LoggingTarget).
Although the Flex Logging Framework allows you to supply a custom Filters Array (and this can even be updated at runtime), it does not appear to include a simple way to configure this via an external XML configuration file. However, I’m fairly confident that I can roll my own (just a shame that I have to!)

I’m going to be working on the three points above over the next few days and see if I can come up with a solution which stays as faithful to the intrinsic Logging framework as possible but allows the flexibility of some of the other Loggers out there (Luminic Box, XRay, etc).