You use the settings in the mm.cfg text file to configure the debugger version of Flash Player. These settings also affect logging of trace() output in AIR applications running in the ADL debugger. If this file does not exist, you can create it when you first configure the debugger version of Flash Player. The location of this file depends on your operating system.

The following table shows where to create the mm.cfg file for Flash Player 10.1 and later on several operating systems:

/home/username

The following table lists the properties that you can set in the mm.cfg file:

ErrorReportingEnable

MaxWarnings

PolicyFileLog

PolicyFileLogAppend

TraceOutputFileEnable

TraceOutputFileName

TraceOutputFileName=<fully qualified path/filename> 

The following sample mm.cfg file enables error reporting and trace logging:

 ErrorReportingEnable=1

Beginning with the Flash Player 9 Update, you cannot modify the log file location or name. The filename is flashlog.txt, and its location is hard-coded, depending on your operating system. The following table shows the flashlog.txt file location:

C:\Documents and Settings\username\Application Data\Macromedia\Flash Player\Logs

C:\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs

/Users/username/Library/Preferences/Macromedia/Flash Player/Logs/

/home/username/.macromedia/Flash_Player/Logs/

The default log file location changed between the initial Flash Player 9 release and the Flash Player 9 Update. In the initial Flash Player 9 release, the default location was the same directory as the mm.cfg file and you could update the log file location and name through the TraceOutputFileName property.

To determine which version of Flash Player you are currently using—the standard version or the debugger version—you can use the Capabilities class. This class contains information about Flash Player and the system that it is currently operating on. To determine if you are using the debugger version of Flash Player, you can use the isDebugger property of that class. This property returns a Boolean value: the value is true if the current player is the debugger version of Flash Player and false if it is not.

The following example uses the playerType, version, and isDebugger properties of the Capabilities class to display information about the Player:

<?xml version="1.0"?> 
<!-- logging/CheckDebugger.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        import flash.system.Capabilities; 
 
        private function reportVersion():String { 
            if (Capabilities.isDebugger) { 
                return "Debugger version of Flash Player"; 
            } else { 
                return "Flash Player"; 
            } 
        } 
        private function reportType():String { 
            return Capabilities.playerType + " (" + Capabilities.version + ")"; 
        } 
        ]]> 
    </fx:Script> 
    
    <s:Label text="{reportVersion()}"/> 
    <s:Label text="{reportType()}"/> 
 
</s:Application>

Other properties of the Capabilities class include hasPrinting, os, and language.

To record messages on the client, you must use the debugger version of Flash Player. You must also set TraceOutputFileEnable to 1 in your mm.cfg file. For more information on editing the mm.cfg file, see Editing the mm.cfg file.

The debugger version of Flash Player sends output from the trace() method to the flashlog.txt file. The location of this file is determined by the operating system. For more information, see Log file location.

You can suppress trace output by setting the omit-trace-statements compiler argument to true.

You can use the debugger version of Flash Player to capture output from the global trace() method and write that output to the client log file. You can use trace() statements in any ActionScript or MXML file in your application. Because it is a global function, you are not required to import any ActionScript classes packages to use the trace() method.

Only debug SWF files will write out trace() statements. To create a debug SWF file, set the debug compiler argument to true.

The following example defines a function that logs the various stages of the Button control's startup life cycle:

<?xml version="1.0"?> 
<!-- logging/ButtonLifeCycle.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <fx:Script> 
        <![CDATA[ 
        private function traceEvent(event:Event):void { 
            trace(event.currentTarget + ":" + event.type); 
        } 
        ]]> 
    </fx:Script> 
 
    <s:Button id="b1" label="Click Me" 
        preinitialize="traceEvent(event)" 
        initialize="traceEvent(event)" 
        creationComplete="traceEvent(event)" 
        updateComplete="traceEvent(event)" 
    /> 
 
</s:Application>

The following example shows the output of this simple application:

 TraceLifecycle_3.b1:Button:preinitialize 
 TraceLifecycle_3.b1:Button:initialize 
 TraceLifecycle_3.b1:Button:creationComplete 
 TraceLifecycle_3.b1:Button:updateComplete 
 TraceLifecycle_3.b1:Button:updateComplete 
 TraceLifecycle_3.b1:Button:updateComplete

Messages that you log by using the trace() method should be Strings. If the output is not a String, use the String(...) conversion function, or use the object's toString() method, if one is available, before you call the trace() method.

To enable tracing, you must configure the debugger version of Flash Player as described in Configuring the debugger version of Flash Player to record trace() output.

The logging API lets an application capture and write messages to a target's configured output. Typically the output is equivalent to the global trace() method, but it can be anything that an active target supports.

The logging API consists of the following parts:

Logger

The logger provides an interface for sending a message to an active target. Loggers implement the ILogger interface and call methods on the Log class. The two classes of information used to filter a message are category and level. Each logger operates under a category. A category is a string used to filter all messages sent from that logger. For example, a logger can be acquired with the category "orange". Any message sent using the "orange" logger only reaches those targets that are listening for the "orange" category. In contrast to the category that is applied to all messages sent with a logger, the level provides additional filtering on a per-message basis. For example, to indicate that an error occurred within the "orange" subsystem, you can use the error level when logging the message. The supported levels are defined by the LogEventLevel class. The Flex framework classes that use the logging API set the category to the fully qualified class name as a convention.

Log target

The log target defines where log messages are written. Flex predefines a single log target: TraceTarget, which is the most commonly used log target. This log target connects the logging API to the trace system so that log messages are sent to the same location as the output of the trace() method. For more information on the trace() method, see Using the global trace() method.

You can also write your own custom log target. For more information, see Implementing a custom logger with the logging API.

Destination

The destination is where the log message is written. Typically, this is a file, but it can also be a console or something else, such as an in-memory object. The default destination for TraceTarget is the flashlog.txt file. You configure this destination on the client.

The following example shows a sample relationship between a logger, a log target, and a destination:

You can also use the logging API to send messages from custom code you write. You can do this when you create a set of custom APIs or components or when you extend the Flex framework classes and you want users to be able to customize their logging. For more information, see Implementing a custom logger with the logging API.

The following packages within the Flex framework are the only ones that use the logging API:

• mx.rpc.*

• mx.messaging.*

• mx.data.*

To configure client-side logging in MXML or ActionScript, create a TraceTarget object to log messages. The TraceTarget object logs messages to the same location as the output of the trace() statements. You can also use the TraceTarget to specify which classes to log messages for, and what level of messages to log.

The levels of logging messages are defined as constants of the LogEventLevel class. The following table lists the log level constants and their numeric equivalents, and describes each message level:

Logging level constant (int)	Description
ALL (0)	Designates that messages of all logging levels should be logged.
DEBUG (2)	Logs internal Flex activities. This is most useful when debugging an application. Select the DEBUG logging level to include DEBUG, INFO, WARN, ERROR, and FATAL messages in your log files.
INFO (4)	Logs general information. Select the INFO logging level to include INFO, WARN, ERROR, and FATAL messages in your log files.
WARN (6)	Logs a message when the application encounters a problem. These problems do not cause the application to stop running, but could lead to further errors. Select the WARN logging level to include WARN, ERROR, and FATAL messages in your log files.
ERROR (8)	Logs a message when a critical service is not available or a situation has occurred that restricts the use of the application. Select the ERROR logging level to include ERROR and FATAL messages in your log files.
FATAL (1000)	Logs a message when an event occurs that results in the failure of the application. Select the FATAL logging level to include only FATAL messages in your log files.

The log level lets you restrict the amount of messages sent to any running targets. Whatever log level you specify, all "lower" levels of messages are written to the log. For example, if you set the log level to DEBUG, all log levels are included. If you set the log level to WARNING, only WARNING, ERROR, and FATAL messages are logged. If you set the log level to the lowest level of message, FATAL, only FATAL messages are logged.