LiveCycle® Data Services Developer's Guide

Administering Data Services Applications > Logging > Client-side logging and debugging

Client-side logging and debugging

Often, you use the trace() method when you debug applications to write a checkpoint message on the client, which signals that your application reached a specific line of code, or to output the value of a variable.

The debugger version of Flash Player has two primary methods of writing messages that use trace():

• The global trace() method. The global trace() method prints Strings to a specified output log file. For more information, see Using the global trace() method.
• Logging API. The Logging API provides a layer of functionality on top of the trace() method that you can use with your custom classes or with the data service APIs. For more information, see Using the Logging API.

Subtopics

Configuring the debugger version of Flash Player to record trace() output

To record messages on the client, you must use the debugger version of Flash Player.

The debugger version of Flash Player sends output from the trace() method to the flashlog.txt file. The default location of this file is the same directory as the mm.cfg file. You can customize the location of this file by using the TraceOutputFileName property in the mm.cfg file. You must also set TraceOutputFileEnable to 1 in your mm.cfg file.

For more information, see Configuring the debugger version of Flash Player.

Using the global trace() method

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.

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 -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script><![CDATA[
        private function traceEvent(event:Event):void {
            trace(event.currentTarget + ":" + event.type);
        }
    ]]></mx:Script>

    <mx:Button id="b1" label="Click Me"
        preinitialize="traceEvent(event)"
        initialize="traceEvent(event)" 
        creationComplete="traceEvent(event)"
        updateComplete="traceEvent(event)"
    />

</mx: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(...) 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.

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:

LiveCycle 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:

• 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:

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

LiveCycle Data Services ES 2.5

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

Current page: http://livedocs.adobe.com/livecycle/es/sdkHelp/programmer/lcds/logging_4.html

Add Comment