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.
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
}
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). |
There are two ways to configure the logging framework: Parsley XML and programmatic configuration.
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 15.2 Logging Configuration for Flash for details.
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.
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.