Flex Logging API (mx.logging)

Flex defines a robust logging API in the mx.logging packages.

The primary elements of Flex's Logging framework:

Loggers - sends information to a target for a category of log messages
Targets - responsible for formatting and general output of log data
Levels - represents the importance of a log message

Log Levels (defined in the LogEventLevel class):

FATAL - designates events that are very harmful and will eventually lead to application failure
ERROR - designates error events that might still allow the application to continue running
WARN - designates events that could be harmful to the application operation
INFO - designates informational messages that highlight the progress of the application at coarse-grained level
DEBUG - designates informational level messages that are fine grained and most helpful when debugging an application
ALL - intended to force a target to process all messages

The Log (mx.logging.Log) and its static methods are where to start with logging.

Log (mx.logging.Log)

The Log class contains several static method for managing an application's logging setup.

Commonly useful (static) Log functions:

getLogger( category:String ):ILogger - returns the logger associated with the specified category
addTarget( target:ILoggingTarget ):void - allows the specified target to begin receiving notification of log events
removeTarget( target:ILoggingTarget ):void - removes the specified target so it will no longer receive log event notifications
isDebug():Boolean, isError():Boolean, isFatal():Boolean, isInfo():Boolean, isWarn():Boolean - tests whether a log event with a certain level will be handled by a target

The following example shows an example of adding a log target and getting a logger.

   import mx.logging.*;
   import mx.logging.targets.*;
   
   public function init():void
   {
      // add a target for receiving the log messages
      Log.addTarget( new TraceTarget() );
      
      // create a logger
      var logger:ILogger = Log.getLogger( "test" );
   }

Logger (mx.logging.ILogger)

A Logger is an object for sending a category of log messages to. Logger instances are retrieved from the Log class via its static getLogger() function, passing a category string argument.

A logger instance will implement the mx.logging.ILogger interface.

Commonly useful Logger functions:

log( level:int, message:String, ... rest ):void - logs a message with a specified log level
- level:int - the log level
- message:String - the log message
- ... rest - message substitution parameters (see note below)
debug( message:String, ... rest ), error(), fatal(), info(), warn() - level specific log functions
- message:String - the log message
- ... rest - message substitution parameters (see note below)

Note that all of ILogger's methods take optional ... rest arguments, which are turned into an array, for message substitution parameters. These are additional parameters that can be substituted in the message parameter at each "{x}" location, where x is an integer (zero based) index value into the Array of values specified.

The code below shows how to get a logger instance and send it messages of various log levels.

   // create/get a logger
   var logger:ILogger = Log.getLogger( "test" );
   
   // log a message with a level of INFO
   logger.log( LogEventLevel.INFO, "This is a test log message." );
   
   // log a message with a level of ERROR
   logger.error( "This is an error message." );
   
   // log a message with a level of DEBUG (ends with "A, B, C")
   logger.debug( "This is an debug message: {0}, {1}, {2}", "A", "B", "C" );

Note that any number of calls to Log.getLogger() with the same category will return the same logger instance.

Logging Targets (mx.logging.ILoggingTarget)

A Logging Target receives log events and is responsible for formatting and general output of log data. A target is used by adding calling Log.addTarget() with an instance.

Flex includes only a couple of pre-defined logging targets in the mx.logging.targets package. The most easily useful is the TraceTarget class, which will simply output log messages using the Flash's trace() function.

   // add a target to the logging framework
   Log.addTarget( new TraceTarget() );

Remember you must launch your application in Debug mode to see the trace() output produced by TraceTarget.

Flex Logging API (mx.logging)

Log (mx.logging.Log)

Logger (mx.logging.ILogger)

Logging Targets (mx.logging.ILoggingTarget)

Related Links: