ELF = Electrotank Logging Framework

     Debugging applications in Flash has always been tricky. One of the first projects I had to opportunity to work on when I started with Electrotank was to develop a reliable and lightweight logging framework. For this framework, we had several requirements:

1. Must be flexible. We needed to be able to render log messages to any number of different sources. 
2. Must be very lightweight. While always making attempts to better optimize our games, we couldn't have a logging framework that would weigh things down.
3. Must be customizable. Should be able to adjust log levels and renderers globally and/or by class instance.

ELF (Electrotank Logging Framework) is very simple to use for basic logging purposes. To create a log, you instantiate it using the Logger.getLogger() method. All Loggers implement the ILogger interface. 

import com.electrotank.logging.*; 
var logger:ILogger = Logger.getLogger("com.electrotank.Game");

To log a message, you would then call the appropriate method to the log severity (debug,info,status,error,fatal):

logger.debug("This is a debug message"); 
logger.info("This is an info message."); 

... and so on ...

For the sake of keeping overhead to a minimum, an optional second parameter is available to all log calls (debug(),info(),etc....). This parameter, an Array, will allow you to specify values to be inserted into your log message in the event the log is run. For example, if you were tracking the x and y positions of a MovieClip. you might normally log:

logger.debug("x="+myMC.x+",y="+myMC.y);

The problem with this is that, regardless of your severity threshold, the expense of the string concatenation will be there. However, you can achieve the same thing using the optional second parameter:

logger.debug("x=$0,y=$1",[myMC.x,myMC.y]); 

Aside from being easier to read and easier to write, this method will also save the concatenation for only if the log passes the threshold and actually logs. This works similar to a printf() method in that the wildcard ("$") is followed by the index of the array value to merge. This allows you to move values around easily.

The log message will be rendered to the registered log renderers. To configue the Logger globally, you can call the Logger.configure() static method. This method requires an instance of Configuration. With the Configuration class, you can configure the default severity threshold and the default renderers.

var config:IConfiguration = new Configuration();
config.setDefaultThreshold(LogSeverity.FATAL); 
config.setDefaultRenderers([new TraceRenderer()]); 

Without further configuration, the initial threshold is set to LogSeverity.DEBUG and the initial renderers are TraceConfiguration and LocalConnectionRenderer.

 

Renderers are the means by which the logger will display the log messages. A TraceRenderer instance will display the message by a Flash trace() call. A TextFieldRenderer will render the messages to a TextField of your choosing. The LocalConnectionRenderer will render the messages to a LocalConnection instance. These renderers can be configured individually by their instance level configure method. With these configurations, you can choose a different form of formatting for the LogMessage. The default is SimpleFormatter. All formatters must implement the IFormatter interface.

var config:IConfigration = new TraceConfiguration();
config.setFormatter(new CustomFormatter());

var traceRenderer:ILogRenderer = new TraceRenderer();
traceRenderer.configure(config);

This gives a lot of flexibility to how you want to receive the log messages and makes adapting the framework to different environments (Flex, CS3) easy.

 

We've begun using ELF heavily in several large  projects currently underway and I've found it to be a huge time saver. This version is currently AS3 only. I have an AS2 version, but I kind of left it behind and continued development in AS3. If I get the chance, I'll try and bring the AS2 version back up to speed. Until then, you can download ELF from the link below. 

Download ELF