Building and Deploying Flex 2 Applications > Building Flex Applications > Logging > Client-side logging and debugging > Using the Logging API

Using the Logging API

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 two log targets: TraceTarget and MiniDebugTarget. The most commonly used log target is TraceTarget. 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:


Sample relationship between a logger, log target, and a destination

Flex Data Services uses the Logging API for diagnostic and error reporting. For more information, see Using the Logging API with data services.

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:

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.

March 5, 2007: Change LogLevelEvent to LogEventLevel.

The levels of logging messages are defined as constants of the LogLevelEvent 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.

Subtopics

Using the Logging API with data services
Implementing a custom logger with the Logging API

Flex 2

 

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flex/2/docs/00001533.html