Implementing a custom logger with the Logging API -- Flex 2

If you write custom components or an ActionScript API, you can use the Logging API to access the trace system in the debugger version of Flash Player. You do this by defining your log target as a TraceTarget, and then calling methods on your logger when you log messages.

The following example extends a Button control. It writes log messages for the startup life cycle events, such as initialize and creationComplete, and the common UI events, such as click and mouseOver.

package { // The empty package.
    import mx.controls.Button;
    import flash.events.*;
    import mx.logging.*;
    import mx.logging.targets.*;
        
    public class MyCustomClass extends Button {

        private var myLogger:ILogger;

        public function MyCustomClass() {
            super();
            initListeners();
            initLogger();
        }
        private function initListeners():void {
            // Add event listeners life cycle events.
            addEventListener("preinitialize", logLifeCycleEvent);
            addEventListener("initialize", logLifeCycleEvent);
            addEventListener("creationComplete", logLifeCycleEvent);
            addEventListener("updateComplete", logLifeCycleEvent);
            
            // Add event listeners for other common events.
            addEventListener("click", logUIEvent);        
            addEventListener("mouseUp", logUIEvent);        
            addEventListener("mouseDown", logUIEvent);        
            addEventListener("mouseOver", logUIEvent);        
            addEventListener("mouseOut", logUIEvent);        
        }
        private function initLogger():void {
            myLogger = Log.getLogger("MyCustomClass");
        }

        private function logLifeCycleEvent(e:Event):void {
            if (Log.isInfo()) {
                myLogger.info(" STARTUP: " + e.target + ":" + e.type);
            }
        }

        private function logUIEvent(e:MouseEvent):void {
            if (Log.isDebug()) {
                myLogger.debug(" EVENT:   " + e.target + ":" + e.type);
            }
        }
    }
}

Within the application that uses MyCustomClass, define a TraceTarget, as the following example shows:

<mx:Application xmlns:mx=http://www.adobe.com/2006/mxml xmlns="*" >
    <mx:TraceTarget level="0" includeDate="true" includeTime="true"
        includeCategory="true" includeLevel="true">
        <mx:filters>
            <mx:Array>
                <mx:String>*</mx:String>
            </mx:Array>
        </mx:filters>
    </mx:TraceTarget>
    <MyCustomClass/>
</mx:Application>

After running this application, the flashlog.txt file looks similar to the following:

3/9/2006 18:58:05.042 [INFO] MyCustomClass STARTUP: Main_3.mcc:MyCustomClass:preinitialize
3/9/2006 18:58:05.487 [INFO] MyCustomClass STARTUP: Main_3.mcc:MyCustomClass:initialize
3/9/2006 18:58:05.557 [INFO] MyCustomClass STARTUP: Main_3.mcc:MyCustomClass:creationComplete
3/9/2006 18:58:05.567 [INFO] MyCustomClass STARTUP: Main_3.mcc:MyCustomClass:updateComplete
3/9/2006 18:58:05.577 [INFO] MyCustomClass STARTUP: Main_3.mcc:MyCustomClass:updateComplete
3/9/2006 18:58:05.577 [INFO] MyCustomClass STARTUP: Main_3.mcc:MyCustomClass:updateComplete
3/9/2006 18:58:06.849 [DEBUG] MyCustomClass EVENT:   Main_3.mcc:MyCustomClass:mouseOver
3/9/2006 18:58:07.109 [DEBUG] MyCustomClass EVENT:   Main_3.mcc:MyCustomClass:mouseDown
3/9/2006 18:58:07.340 [DEBUG] MyCustomClass EVENT:   Main_3.mcc:MyCustomClass:mouseUp
3/9/2006 18:58:07.360 [DEBUG] MyCustomClass EVENT:   Main_3.mcc:MyCustomClass:click
3/9/2006 18:58:07.610 [DEBUG] MyCustomClass EVENT:   Main_3.mcc:MyCustomClass:mouseOut

To log a message, you call the appropriate method of the ILogger interface. The ILogger interface defines a method for each log level: debug(), info(), warn(), error(), and fatal(). The logger logs messages from these calls if their levels are at or under the log target's logging level. If the target's logging level is set to all, the logger records messages when any of these methods are called.

To improve performance, a static method corresponding to each level exists on the Log class, which indicates if any targets are listening for a specific level. Before you log a message, you can use one of these methods in an if statement to avoid running the code. The previous example uses the Log.isDebug() and Log.isInfo() static methods to ensure that the messages are of level INFO or DEBUG before logging them.

The previous example logs messages dispatched from any category because the TraceTarget's filters property is set to the wildcard character (*). The framework code sets the category of the logger to the fully qualified class name of the class in which logging is being performed. This is by convention only; any String specified when calling Log.getLogger(x) is the category required in a filters property to receive the message.

When you set the filters property for logging within the Flex framework, you can restrict this to a certain package or packages, or to other classes. To restrict the logging to your custom class only, add the category specified when the logger was acquired ("MyCustomClass") to the filters Array, as the following example shows:

<mx:filters>
    <mx:Array>
        <mx:String>*</mx:String>
    </mx:Array>
</mx:filters>

In ActionScript, you can set the filters property by using the following syntax:

traceTarget.filters = ["p1.*", "p2.*", "otherPackage*"];

The Log.getLogger() method sets the category of the logger. You pass this method a String that defines the category.

The value of the category must fall within the definition of at least one of the filters for the log message to be logged. For example, if you set the filters property to something other than "*" and you use Log.getLogger("MyCustomClass"), the filter Array must include an entry that matches MyCustomClass, such as "MyCustomClass" or "My*".

You can include the logger's category in your log message, if you set the logger's includeCategory property to true.

You can also use the ILogger interface's log() method to log a message, and you can specify the logging level in that method. The following example logs messages that use the log level that is passed into the method:

private function logLifeCycleEvent(e:Event):void {
    dynamicLogger(LogEventLevel.INFO, e, "STARTUP");
}
private function logUIEvent(e:MouseEvent):void {
    dynamicLogger(LogEventLevel.DEBUG, e, "EVENT");
}
private function dynamicLogger(level:int, e:Event, prefix:String):void {
    var s:String = "__" + prefix + "__" + e.target + ":" + e.type;
    myLogger.log(level, s);
}

Comments

jeffcg said on Mar 15, 2007 at 8:06 AM :

In the following, shouldn't the * in the filters array be "MyCustomClass" instead? The example still shows "*".

"When you set the filters property for logging within the Flex framework, you can restrict this to a certain package or packages, or to other classes. To restrict the logging to your custom class only, add the category specified when the logger was acquired ("MyCustomClass") to the filters Array, as the following example shows:

<mx:filters>
<mx:Array>
<mx:String>*</mx:String>
</mx:Array>
</mx:filters>
"