Debugging Mediation

Message mediation mode is one of the operational modes of WSO2 ESB where ESB functions as an intermediate message router. When operating in this mode, it can filter, transform, drop or forward messages to an endpoint based on the given parameters. A unit of the mediation flow is a mediator. Sequences define the message mediation behavior of the ESB. A sequence is a series of mediators, where each mediator is a unit entity that can input a message, carry out a predefined processing task on the message, and output the message for further processing. 

What is debugging with respect to mediation

Debugging is where you want to know if these units, which function as separate entities are operating as intended, or if a combination of these units are operating as a whole as intended. WSO2  ESB packs the ESB Mediation debugger that enables you to debug the ESB message mediation flow in the server. Tooling support for the ESB Mediation debugger is provided by the WSO2 ESB Tooling Plugin.

Creating the ESB artifact

Follow the steps below to create a sample ESB artifact, to which you apply mediation.

1. Install the WSO2 ESB Tooling Plugin and run it. For instructions, see Installing WSO2 ESB Tooling.
   
2. Create the ESB artifact using the WSO2 ESB Tooling Plugin. For instructions, see Working with ESB Artifacts.
3. Deploy the artifact you created on WSO2 ESB. For instructions, go to Deploying the ESB Config project.

Enabling mediation debugging 

Follow the steps below to enable debugging with respect to mediation.

1. Click Run in the top menu of the WSO2 ESB Tooling Plugin, and then click Debug Configurations.
2. Double click ESB Mediation Debugger as shown below.
   
3. Enter the details to create a new configuration as shown in the example below. You need to define two port numbers and a hostname t o connect the ESB server with the WSO2 ESB Tooling Plugin in the mediation debug mode.
   
4. Execute the following commands to start WSO2 ESB server in the debug mode by passing a system variable at start up:    
   
   • On Windows: <ESB_HOME>\bin\wso2server.bat --run -Desb.debug=true
   • On Linux/Solaris: sh <ESB_HOME>/bin/wso2server.sh -Desb.debug=true

5. Click Debug in the WSO2 ESB Tooling Plugin when  the WSO2 ESB Console indicates the following.

   You have approximately a one-minute time span to connect the WSO2 ESB Tooling Plugin with the ESB server for the execution of the above created debug configuration. Otherwise, the ESB server will stop listening and start without connecting with the debugger tool.

   

6.   In the WSO2 ESB Tooling Plugin, right click and add breakpoints or skip points on the desired mediators to start debugging as shown in the example below. 

   

   
   

   You can add the following debugging options on the mediators using the right click context menu.

   • Toggle Breakpoint: Adds a breakpoint to the selected mediator
   • Toggle Skip Point: Adds a skip point to the selected mediator
   • Resend ESB Debug Points: If you re-start the ESB server, or if you re-deploy the proxy service after changing its Synapse configuration, you need to re-send the information on breakpoints to the WSO2 ESB server. This re-sends all registered debugging points to the ESB Server.   
   • Delete All ESB Debug Points: Deletes all registered debug points from the ESB Server and the WSO2 ESB Tooling Plugin

Information provided by the Debugger Tool

When your target artifact gets a request message and when the mediation flow reaches a mediator marked as a breakpoint, the message mediation process suspends at that point. A tool tip message of the suspended mediator displays the message envelope of the message payload at that point as shown in the example below. 

You can view the message payload at that point of the message flow also in the Message Envelope tab as shown below.

Also, you can view the message mediation properties in the Variables view as shown in the example below.

The Variable view contains properties of the following property scopes.

• Axis2-Client Scope Properties

• Axis2 Scope Properties

• Operation Scope Properties

• Synapse Scope Properties

• Transport Scope Properties

You can have a list of selected properties out of the above, in the properties table of the Message Envelope tab, and view information on the property keys and values of them as shown below.

Click Add Property, specify the context and name of the property, and then click OK, to add that propert to the properties table in the Message Envelope tab as shown below.

Changing the property values

There are three operations that you can perform on message mediation property values as described below.

Injecting new properties

Follow the steps below to inject new properties to the ESB server while debugging.

1. Right click on the Variable view, click Inject/Clear Property, and then click Inject Property as shown below.
   
2. Enter the details about the property you prefer to add as shown in the example below.
   
3. Click OK.

Clearing a property

Follow the steps below to clear an existing property from the ESB server.

1. Right click on the Variable view, click Inject/Clear Property, and then click Clear Property as shown below.
   
2. Enter the details about the property you want to clear as shown in the example below.
   
3. Click OK.

Modifying a property

Click on the value section of the preferred property and change the value in the Variable view as shown in the example below, to modify it.

Viewing wire logs

While debugging a Synapse flow, you can view the the actual HTTP messages at the entry point of the ESB via wire logs. For example, you can view wire logs of the incoming flow and the final response of a proxy service. Also, you can view wire logs for points, where it goes out from the ESB. For example, you can see the outgoing and incoming wire logs for specific mediators (i.e. Call mediator, Send mediator etc.). Wire logs are useful to troubleshoot unexpected issues, which occurr while integrating miscallaneous systems. You can use wire logs to verify whether the message payload is properly going out from the server, whether the HTTP headers such as the content-type is properly set in the outgoing message etc. 

The passthrough HTTP transport is the main transport, which handles HTTP/HTTPS messages in WSO2 ESB. Un-comment the following entry in the <ESB_HOME/repository/conf/log4j.properties file to enable wire logs for the passthrough HTTP transport: log4j.logger.org.apache.synapse.transport.http.wire=DEBUG

Following is a sample wirelog.

[2013-09-22 19:47:57,797] DEBUG - wire >> "POST /services/StockQuoteProxy HTTP/1.1[\r][\n]"
[2013-09-22 19:47:57,798] DEBUG - wire >> "Content-Type: text/xml; charset=UTF-8[\r][\n]"
[2013-09-22 19:47:57,798] DEBUG - wire >> "SOAPAction: "urn:getQuote"[\r][\n]"
[2013-09-22 19:47:57,799] DEBUG - wire >> "User-Agent: Axis2[\r][\n]"
[2013-09-22 19:47:57,799] DEBUG - wire >> "Host: localhost:8280[\r][\n]"
[2013-09-22 19:47:57,799] DEBUG - wire >> "Transfer-Encoding: chunked[\r][\n]"
[2013-09-22 19:47:57,800] DEBUG - wire >> "[\r][\n]"
[2013-09-22 19:47:57,800] DEBUG - wire >> "215[\r][\n]"
[2013-09-22 19:47:57,800] DEBUG - wire >> "http://localhost:8280/services/StockQuoteProxyurn:uuid:9e1b0def-a24b-4fa2-8016-86cf3b458f67urn:getQuoteIBM[\r][\n]"
[2013-09-22 19:47:57,801] DEBUG - wire >> "0[\r][\n]"
[2013-09-22 19:47:57,801] DEBUG - wire >> "[\r][\n]"
[2013-09-22 19:47:57,846]  INFO - TimeoutHandler This engine will expire all callbacks after : 120 seconds, irrespective of the timeout action, after the specified or optional timeout
[2013-09-22 19:47:57,867] DEBUG - wire << "POST /services/SimpleStockQuoteService HTTP/1.1[\r][\n]"
[2013-09-22 19:47:57,867] DEBUG - wire << "Content-Type: text/xml; charset=UTF-8[\r][\n]"
[2013-09-22 19:47:57,867] DEBUG - wire << "SOAPAction: "urn:getQuote"[\r][\n]"
[2013-09-22 19:47:57,867] DEBUG - wire << "Transfer-Encoding: chunked[\r][\n]"
[2013-09-22 19:47:57,868] DEBUG - wire << "Host: localhost:9000[\r][\n]"
[2013-09-22 19:47:57,868] DEBUG - wire << "Connection: Keep-Alive[\r][\n]"
[2013-09-22 19:47:57,868] DEBUG - wire << "User-Agent: Synapse-PT-HttpComponents-NIO[\r][\n]"
[2013-09-22 19:47:57,868] DEBUG - wire << "[\r][\n]"
[2013-09-22 19:47:57,868] DEBUG - wire << "215[\r][\n]"
[2013-09-22 19:47:57,868] DEBUG - wire << "http://localhost:8280/services/StockQuoteProxyurn:uuid:9e1b0def-a24b-4fa2-8016-86cf3b458f67urn:getQuoteIBM[\r][\n]"
[2013-09-22 19:47:57,868] DEBUG - wire << "0[\r][\n]"
[2013-09-22 19:47:57,869] DEBUG - wire << "[\r][\n]"
[2013-09-22 19:47:58,002] DEBUG - wire >> "HTTP/1.1 200 OK[\r][\n]"
[2013-09-22 19:47:58,002] DEBUG - wire >> "Content-Type: text/xml; charset=UTF-8[\r][\n]"
[2013-09-22 19:47:58,002] DEBUG - wire >> "Date: Sun, 22 Sep 2013 14:17:57 GMT[\r][\n]"
[2013-09-22 19:47:58,002] DEBUG - wire >> "Transfer-Encoding: chunked[\r][\n]"
[2013-09-22 19:47:58,002] DEBUG - wire >> "Connection: Keep-Alive[\r][\n]"
[2013-09-22 19:47:58,002] DEBUG - wire >> "[\r][\n]"
[2013-09-22 19:47:58,014] DEBUG - wire << "HTTP/1.1 200 OK[\r][\n]"
[2013-09-22 19:47:58,015] DEBUG - wire << "Content-Type: text/xml; charset=UTF-8[\r][\n]"
[2013-09-22 19:47:58,015] DEBUG - wire << "Date: Sun, 22 Sep 2013 14:17:58 GMT[\r][\n]"
[2013-09-22 19:47:58,015] DEBUG - wire << "Server: WSO2-PassThrough-HTTP[\r][\n]"
[2013-09-22 19:47:58,016] DEBUG - wire << "Transfer-Encoding: chunked[\r][\n]"
[2013-09-22 19:47:58,016] DEBUG - wire << "[\r][\n]"
[2013-09-22 19:47:58,016] DEBUG - wire >> "4d8[\r][\n]"
[2013-09-22 19:47:58,017] DEBUG - wire >> "urn:getQuoteResponseurn:uuid:9e1b0def-a24b-4fa2-8016-86cf3b458f673.827143922330303-8.819296796724336-170.50810412063595170.73218944560944Sun Sep 22 19:47:57 IST 2013-170.472077024782785.562077973231586E7IBM Company178.0616712932281324.9438904049222641.9564266653777567195.61908401976004IBM6216[\r][\n]"
[2013-09-22 19:47:58,017] DEBUG - wire >> "0[\r][\n]"
[2013-09-22 19:47:58,018] DEBUG - wire >> "[\r][\n]"
[2013-09-22 19:47:58,021] DEBUG - wire << "4d8[\r][\n]"
[2013-09-22 19:47:58,022] DEBUG - wire << "urn:getQuoteResponseurn:uuid:9e1b0def-a24b-4fa2-8016-86cf3b458f673.827143922330303-8.819296796724336-170.50810412063595170.73218944560944Sun Sep 22 19:47:57 IST 2013-170.472077024782785.562077973231586E7IBM Company178.0616712932281324.9438904049222641.9564266653777567195.61908401976004IBM6216[\r][\n]"
[2013-09-22 19:47:58,022] DEBUG - wire << "0[\r][\n]"
[2013-09-22 19:47:58,022] DEBUG - wire << "[\r][\n]

• DEBUG - wire >>    - This represents a message, which is coming into WSO2 ESB from the wire
• DEBUG - wire <<    - This represents a message, which goes to the wire from WSO2 ESB

Viewing wire logs of a specific mediator

You need to put a debug point to the mediator, to view wire logs of it. When debugging is finished (or while debugging), right click on the mediator, and click Show WireLogs, to view wire logs for a specific mediator.

Viewing wire logs while debugging

If you view wire logs while debugging, you view only the wire logs of mediators, whose execution is already completed as shown in the example below.

Viewing wire logs of a mediator after debugging execution of it

When you view wire logs of a mediator (e.g. send mediator) after debugging, you can view the request and response wire logs as shown in the example below.

Viewing wire logs of a proxy service after debugging 

If you view wire logs of a proxy service after debugging finished, you view the request wire log and final response wire log of that proxy as shown in the example below.