The mechanism for measuring message processing performance is disabled by default. When you enable it, you can use the MessagePerformanceUtils class to access the metrics from a message received by a client.

Enabling message processing metrics

You use two parameters in a channel definition to enable message processing metrics:

• <record-message-times>
• <record-message-sizes>

Set these parameters to true or false; the default value is false. You can set the parameters to different values to capture only one type of metric. For example, the following channel definition specifies to capture message timing information, but not message sizing information:

<channel-definition id="my-streaming-amf" 
    class="mx.messaging.channels.StreamingAMFChannel">
    <endpoint 
        url="http://{server.name}:{server.port}/{context.root}/messagebroker/streamingamf"             class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
    <properties>
        <record-message-times>true</record-message-times>
        <record-message-sizes>false</record-message-sizes>
    </properties>
</channel-definition>

Using the MessagePerformanceUtils class

The MessagePerformanceUtils class is a client-side class that you use to access the message processing metrics. You create an instance of the MessagePerformanceUtils class from a message pushed to the client by the server or from an acknowledge message.

The following example shows a message producer that uses the acknowledge message to display in a TextArea control the metrics for a message pushed to the server:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <mx:Script>
        <![CDATA[
        
            import mx.messaging.messages.AsyncMessage;
            import mx.messaging.messages.IMessage;
            import mx.messaging.events.MessageEvent;
            import mx.messaging.messages.MessagePerformanceUtils;
            
            // Event handler to send the message to the server.
            private function send():void
            {
                var message:IMessage = new AsyncMessage();
                message.body.chatMessage = msg.text;
                producer.send(message);
                msg.text = "";
            }
                            
            // Event handler to write metrics to the TextArea control.
            private function ackHandler(event:MessageEvent):void { 
                var mpiutil:MessagePerformanceUtils = 
                    new MessagePerformanceUtils(event.message);
                myTAAck.text = "totalTime = " + String(mpiutil.totalTime);
                myTAAck.text = myTAAck.text + "\n" + "messageSize= " + 
                    String(mpiutil.messageSize);
            }            
            
        ]]>
    </mx:Script>
        
    <mx:Producer id="producer" destination="chat" acknowledge="ackHandler(event)"/>
       
    <mx:Label text="Acknowledge metrics"/>
    <mx:TextArea id="myTAAck" width="100%" height="20%"/>
    
    <mx:Panel title="Chat" width="100%" height="100%">
        <mx:TextArea id="log" width="100%" height="100%"/>
        <mx:ControlBar>
             <mx:TextInput id="msg" width="100%" enter="send()"/>
             <mx:Button label="Send" click="send()"/> 
        </mx:ControlBar>
    </mx:Panel>
    
</mx:Application>

In this example, you write an event handler for the acknowledge event to display the metrics. The event handler extracts the metric information from the acknowledge message, and then displays the MessagePerformanceUtils.totalTime and MessagePerformanceUtils.messageSize metrics in a TextArea control.

You can also use the MessagePerformanceUtils.prettyPrint() method to display the metrics. The prettyPrint() method returns a formatted String that contains nonzero and non-null metrics. The following example modifies the event handler for the previous example to use the prettyPrint() method:

// Event handler to write metrics to the TextArea control.
private function ackHandler(event:MessageEvent):void { 
    var mpiutil:MessagePerformanceUtils = new MessagePerformanceUtils(event.message);
    myTAAck.text = mpiutil.prettyPrint();
} 

The following example shows the output from the prettyPrint() method that appears in the TextArea control:

Original message size(B): 509
Response message size(B): 562
Total time (s): 0.016
Network Roundtrip time (s): 0.016

A message consumer can write an event handler for the message event to display metrics, as the following example shows:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    creationComplete="consumer.subscribe();">
    
    <mx:Script>
        <![CDATA[
        
            import mx.messaging.messages.AsyncMessage;
            import mx.messaging.messages.IMessage;
            import mx.messaging.events.MessageEvent;
            import mx.messaging.messages.MessagePerformanceUtils;
            
            // Event handler to send the message to the server.
            private function send():void
            {
                var message:IMessage = new AsyncMessage();
                message.body.chatMessage = msg.text;
                producer.send(message);
                msg.text = "";
            }
                            
            // Event handler to write metrics to the TextArea control.
            private function ackHandler(event:MessageEvent):void { 
                var mpiutil:MessagePerformanceUtils = 
                    new MessagePerformanceUtils(event.message);
                myTAAck.text = mpiutil.prettyPrint();
            }            
            
            // Event handler to write metrics to the TextArea control for the message consumer.
            private function messageHandler(event:MessageEvent):void {
                var mpiutil:MessagePerformanceUtils = 
                    new MessagePerformanceUtils(event.message);
                myTAMess.text = mpiutil.prettyPrint();
                
            }            
        ]]>
    </mx:Script>
        
    <mx:Producer id="producer" destination="chat" acknowledge="ackHandler(event)"/>
    <mx:Consumer id="consumer" destination="chat" message="messageHandler(event)"/>
    
    <mx:Label text="ack metrics"/>
    <mx:TextArea id="myTAAck" width="100%" height="20%" text="ack"/>    
    
    <mx:Label text="receive metrics"/>
    <mx:TextArea id="myTAMess" width="100%" height="20%" text="rec"/>
    
    <mx:Panel title="Chat" width="100%" height="100%">
        <mx:TextArea id="log" width="100%" height="100%"/>
        <mx:ControlBar>
             <mx:TextInput id="msg" width="100%" enter="send()"/>
             <mx:Button label="Send" click="send()"/> 
        </mx:ControlBar>
    </mx:Panel>
    
</mx:Application>

In this example, you use the prettyPrint() method to write the metrics for the received message to a TextArea control. The following example shows this output:

Response message size(B): 560
PUSHED MESSAGE INFORMATION:
Total push time (s): 0.016
Push one way time (s): 0.016
Originating Message size (B): 509

You can gather metrics for HTTPService and WebService tags when they use the Proxy Service, as defined by setting the useProxy property to true for the HTTPService and WebService tags. The following example gathers metrics for an HTTPService tag:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" backgroundColor="#FFFFFF">
    
    <mx:Script>
        <![CDATA[
        
            import mx.messaging.events.MessageEvent;
            import mx.messaging.messages.MessagePerformanceUtils;
                        
            // Event handler to write metrics to the TextArea control for the message consumer.
            private function messageHandler(event:MessageEvent):void {
                var mpiutil:MessagePerformanceUtils = 
                    new MessagePerformanceUtils(event.message);
                myTAMess.text = mpiutil.prettyPrint();                
            }            
        ]]>
    </mx:Script>

    <mx:Label text="Message metrics"/>
    <mx:TextArea id="myTAMess" width="100%" height="20%"/>    
    
    <mx:HTTPService id="srv" destination="catalog" 
        useProxy="true" 
        result="messageHandler(event);"/>

    <mx:DataGrid dataProvider="{srv.lastResult.catalog.product}" 
        width="100%" height="100%"/> 
    
    <mx:Button label="Get Data" click="srv.send()"/>    
</mx:Application>

When using LiveCycle Data Services ES Data Management Service, you can use event handlers on the DataService class to handle metrics, as the following example shows:

<mx:Script>
    <![CDATA[

     import mx.messaging.events.MessageEvent;
     import mx.messaging.messages.MessagePerformanceUtils;
    
     // Event handler to write metrics to the TextArea control.
     private function messageHandler(event:MessageEvent):void {
         var mpiutil:MessagePerformanceUtils = new MessagePerformanceUtils(event.message);
         myTAMess.text = mpiutil.prettyPrint(); 
     } 
    ]]>
</mx:Script>

<mx:DataService id="ds" destination="inventory" result="messageHandler(event);"/>

<mx:Label text="receive metrics"/>
<mx:TextArea id="myTAMess" width="100%" height="20%" text="rec"/>

<mx:Button label="Get Data" click="ds.fill(products)"/>     

Using the server-side classes to gather metrics

For managed endpoints, you can access the total number of bytes serialized and deserialized by using the following methods of the flex.management.runtime.messaging.endpoints.EndpointControlMBean interface:

• getBytesDeserialized()

  Returns the total number of bytes deserialized by this endpoint during its lifetime.

• getBytesSerialized()

  Returns the total number of bytes serialized by this endpoint during its lifetime.

The flex.management.runtime.messaging.endpoints.EndpointControlMBean class implements these methods.

Writing messaging metrics to the log files

You can write messaging metrics to the client-side log file if you enable the metrics. To enable the metrics, set the <record-message-times> or <record-mssage-sizes> parameter to true, and the client-side log level to DEBUG. Messages are written to the log when a client receives an acknowledgment for a pushed message, or a client receives a pushed message from the server. The metric information appears immediately following the debug information for the received message.

The following example initializes logging and sets the log level to DEBUG:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    creationComplete="consumer.subscribe();initLogging();">
    
    <mx:Script>
        <![CDATA[
        
            import mx.messaging.messages.AsyncMessage;
            import mx.messaging.messages.IMessage;
            import mx.messaging.events.MessageEvent;
            import mx.messaging.messages.MessagePerformanceUtils;
            import mx.controls.Alert;
            import mx.collections.ArrayCollection;
            import mx.logging.targets.*;
            import mx.logging.*;            
            
            // Event handler to send the message to the server.
            private function send():void
            {
                var message:IMessage = new AsyncMessage();
                message.body.chatMessage = msg.text;
                producer.send(message);
                msg.text = "";
            }
                            
            // Event handler to write metrics to the TextArea control.
            private function ackHandler(event:MessageEvent):void { 
                var mpiutil:MessagePerformanceUtils = 
                    new MessagePerformanceUtils(event.message);
                myTAAck.text = mpiutil.prettyPrint();
            }            
            
            // Event handler to write metrics to the TextArea control for the message consumer.
            private function messageHandler(event:MessageEvent):void {
                var mpiutil:MessagePerformanceUtils = 
                    new MessagePerformanceUtils(event.message);
                myTAMess.text = mpiutil.prettyPrint();                
            }
            
            // Initialize logging and set the log level to DEBUG.
            private function initLogging():void {
                // Create a target.
                var logTarget:TraceTarget = new TraceTarget();

                // Log all log levels.
                logTarget.level = LogEventLevel.DEBUG;

                // Add date, time, category, and log level to the output.
                logTarget.includeDate = true;
                logTarget.includeTime = true;
                logTarget.includeCategory = true;
                logTarget.includeLevel = true;
    
                // Begin logging.
                Log.addTarget(logTarget);
            }            
        ]]>
    </mx:Script>
        
    <mx:Producer id="producer" destination="chat" acknowledge="ackHandler(event)"/>
    <mx:Consumer id="consumer" destination="chat" message="messageHandler(event)"/>
    
    <mx:Label text="ack metrics"/>
    <mx:TextArea id="myTAAck" width="100%" height="20%" text="ack"/>    
    
    <mx:Label text="receive metrics"/>
    <mx:TextArea id="myTAMess" width="100%" height="20%" text="rec"/>
    
    <mx:Panel title="Chat" width="100%" height="100%">
        <mx:TextArea id="log" width="100%" height="100%"/>
        <mx:ControlBar>
             <mx:TextInput id="msg" width="100%" enter="send()"/>
             <mx:Button label="Send" click="send()"/> 
        </mx:ControlBar>
    </mx:Panel>
</mx:Application>

For more information on logging, see Building and Deploying Adobe Flex 3 Applications.

By default, on Microsoft Windows the log file is written to the file C:\Documents and Settings\USERNAME\Application Data\Macromedia\Flash Player\Logs\flashlog.txt. The following excerpt is from the log file for the message "My test message":

2/14/2008 11:20:18.806 [DEBUG] mx.messaging.Channel 'my-rtmp' channel got connect attempt status. (Object)#0
  code = "NetConnection.Connect.Success"
  description = "Connection succeeded."
  details = (null)
  DSMessagingVersion = 1
  id = "D46A822C-962B-4651-6F2A-DCB41130C4CF"
  level = "status"
  objectEncoding = 3
2/14/2008 11:20:18.837 [INFO] mx.messaging.Channel 'my-rtmp' channel is connected.
2/14/2008 11:20:18.837 [DEBUG] mx.messaging.Channel 'my-rtmp' channel sending message:
(mx.messaging.messages::CommandMessage)
  body=(Object)#0
  clientId=(null)
  correlationId=""
  destination="chat"
  headers=(Object)#0
  messageId="E2F6B35E-42CD-F088-4B7A-18BF1515F142"
  operation="subscribe"
  timeToLive=0
  timestamp=0
2/14/2008 11:20:18.868 [INFO] mx.messaging.Consumer 'consumer' consumer connected.
2/14/2008 11:20:18.868 [INFO] mx.messaging.Consumer 'consumer' consumer acknowledge for subscribe. Client id 'D46A82C3-F419-0EBF-E2C8-330F83036D38' new timestamp 1203006018867
2/14/2008 11:20:18.884 [INFO] mx.messaging.Consumer 'consumer' consumer acknowledge of 'E2F6B35E-42CD-F088-4B7A-18BF1515F142'.
2/14/2008 11:20:18.884 [DEBUG] mx.messaging.Consumer Original message size(B): 626
Response message size(B): 562

2/14/2008 11:20:25.446 [INFO] mx.messaging.Producer 'producer' producer sending message 'CF89F532-A13D-888D-D929-18BF2EE61945'
2/14/2008 11:20:25.462 [INFO] mx.messaging.Producer 'producer' producer connected.
2/14/2008 11:20:25.477 [DEBUG] mx.messaging.Channel 'my-rtmp' channel sending message:
(mx.messaging.messages::AsyncMessage)#0
  body = (Object)#1
    chatMessage = "My test message"
  clientId = (null)
  correlationId = ""
  destination = "chat"
  headers = (Object)#2
  messageId = "CF89F532-A13D-888D-D929-18BF2EE61945"
  timestamp = 0
  timeToLive = 0
2/14/2008 11:20:25.571 [DEBUG] mx.messaging.Channel 'my-rtmp' channel got message
(mx.messaging.messages::AsyncMessageExt)#0
  body = (Object)#1
    chatMessage = "My test message"
  clientId = "D46A82C3-F419-0EBF-E2C8-330F83036D38"
  correlationId = ""
  destination = "chat"
  headers = (Object)#2
    DSMPIO = (mx.messaging.messages::MessagePerformanceInfo)#3
      infoType = "OUT"
      messageSize = 575
      overheadTime = 0
      pushedFlag = true
      receiveTime = 1203006025556
      recordMessageSizes = false
      recordMessageTimes = false
      sendTime = 1203006025556
      serverPostAdapterExternalTime = 0
      serverPostAdapterTime = 0
      serverPreAdapterExternalTime = 0
      serverPreAdapterTime = 0
      serverPrePushTime = 0
    DSMPIP = (mx.messaging.messages::MessagePerformanceInfo)#4
      infoType = (null)
      messageSize = 506
      overheadTime = 0
      pushedFlag = false
      receiveTime = 1203006025556
      recordMessageSizes = true
      recordMessageTimes = true
      sendTime = 1203006025556
      serverPostAdapterExternalTime = 1203006025556
      serverPostAdapterTime = 1203006025556
      serverPreAdapterExternalTime = 0
      serverPreAdapterTime = 1203006025556
      serverPrePushTime = 1203006025556
  messageId = "CF89F532-A13D-888D-D929-18BF2EE61945"
  timestamp = 1203006025556
  timeToLive = 0

2/14/2008 11:20:25.696 [DEBUG] mx.messaging.Channel Response message size(B): 575
PUSHED MESSAGE INFORMATION:
Originating Message size (B): 506

2/14/2008 11:20:25.712 [INFO] mx.messaging.Producer 'producer' producer acknowledge of 'CF89F532-A13D-888D-D929-18BF2EE61945'.
2/14/2008 11:20:25.712 [DEBUG] mx.messaging.Producer Original message size(B): 506
Response message size(B): 562
Total time (s): 0.156
Network Roundtrip time (s): 0.156