20 Logging for Flash Applications

The logging framework allows to log custom messages from application code and use the configuration options to filter log output based on logger names and log levels. It was first developed in AS2 and used in inhouse projects for more than three years until we ported it to AS3 and included it in the public Spicelib release.

It is currently maintained primarily for use in Flash Applications. The Flex SDK has its own Logging API which you can use when building Flex Applications.

20.1 Adding log statements to application code

Usually you would just create a constant that holds the logger for your particular class:

private static const log : Logger = LogContext.getLogger(MyClass);

You can just pass a Class instance to the getLogger method. In this case the fully qualified class name would be used as the name for the logger. Of course you could use any name you want (specified as a String) or create more that one logger for a class, but using the class name is the most common usage. The static getLogger method of the LogContext class uses the default LogFactory under the hood. This is not required but it makes sure that your application logs use the same configuration and appenders than the internal logs of all Spicefactory projects. Alternatively you could also instantiate and use a custom LogFactory and configure it separately.

You could then use that Logger instance anywhere in the class:

public function loadProject (id:String) : void {
    log.info("Start loading project with id {0}", id);
    // do something
}

20.2 Log levels

Log levels offer a way to organize log statements into a hierarchy of different severities. The logging configuration (explained in the next section) allows to filter the log output based on Logger names and levels. The framework supports the following log levels (semantics borrowed from log4j and other existing frameworks):

FATAL Very severe error events that will presumably lead the application to abort.
ERROR Error events that might still allow the application to continue running.
WARN Potentially harmful situations.
INFO Informational messages that highlight the progress of the application at coarse-grained level.
DEBUG Fine-grained informational events that are most useful to debug an application.
TRACE Very fine-grained information (represents the lowest rank of all levels).

20.3 Configuration

There are two ways to configure the logging framework: Parsley XML and programmatic configuration.

20.3.3 Using Parsley XML Tags

If you are using Parsley anyway, using its XML configuration is probably the most convenient way. You can maintain different configuration files for each developer of the project and change it frequently without recompiling. See 13.2 Logging Configuration for Flash in the Parsley Manual for details.

20.3.4 Programmatic Configuration

If you don't use Parsley for application configuration it is recommended to configure logging programmatically since you would pull in the whole Parsley library otherwise. An example setup could look like this:

var factory:FlashLogFactory = new DefaultLogFactory();

factory.setRootLogLevel(LogLevel.WARN);
factory.addLogLevel("com.mycompany.mypackage.controller", LogLevel.DEBUG);
factory.addLogLevel("com.mycompany.mypackage.services", LogLevel.DEBUG);

var traceApp:Appender = new TraceAppender();
traceApp.threshold = LogLevel.TRACE;
factory.addAppender(traceApp);

LogContext.factory = factory;

This block should execute once on application startup.

20.4 Customizing the Logging Framework

The most common use case for customizing the logging framework would be to implement your own Appender. This might be necessary if you have some special requirements like the need to send log statements over a socket connection for example. Implementing the Appender interface is quite straightforward. You can look at the source of Spicelibs existing two implementations.

If you need even more flexibility you could also develop your own implementations of the Logger and LogFactory interfaces, but that might be a rather rare scenario.

In the future we might add more Appender implementations to Spicelib like a FileAppender for AIR applications or even might look into integrating with the Flex Logging Framework.