Debuging & troubleshooting WSO2 ESB

ddI am asked this question almost always I do a ESB demonstration, hence thought of documenting the answer for a wider audience.

WSO2 ESB is a mediation & an orchestration engine for enterprise integrations, you can read more about the product at WSO2 docs.

Building a mediation or a orchestration with multiple external services sometimes can become a tedious task. You will have to transform, clone and create messages to send to multiple external endpoints. You will have to handle the responses and sometime handle the communications reliably with patterns like store and forward etc. In such scenarios being able to debug the message flow, understand the messages going out and coming in from the and to the ESB runtime will come very handy.

There are couple of out of the box capabilities exposed from the ESB to help the developer. Namely the LogMediator which is the simplest, you can also use the TCPMonitor to understand the messages in wire and if the communication is over SSL you can use ESB wire log dump capability.

With the log mediator you can inspect the message at each mediation stage, which is much like we used to debug php scripts back in the day with alot of <?php echo “{statement}”; ?> statmenets

The wire logging capability thats built into the ESB provide you all the information about messages coming into the runtime and going out from the runtime.

<?xml version="1.0" encoding="UTF-8"?>
<sequence name="test_seq" xmlns="">
<log level="full">
<property name="initial message" value="###### INNITIAL MESSAGE #####"/>
<payloadFactory media-type="json">
<log level="full">
<property name="message b4 send" value="###### MESSAGE B4 RESPONSE #####"/>

You can enable wire logs by editing the (in repository/conf) file or through ESB Management console
#if callout mediator is used

More information about wire logs can be found at following post –

Finally if you want to put break points and understand what really happens to the message, you can debug with ESB source. For ESB 4.9.0 its as follows for any later or any upcoming releases the source link will change.

[1] Download the mediation engine source from

[wso2 specific mediators]

[2] Build the source
[3] Open it in Eclipse as a maven project
[4] Setup Eclipse with remote debug

[5] Start the ESB in debug mode

sh wso2esb-4.9.0/bin/ -debug 8000

[6] Put a break point at one the mediators, you have in the sequence (for me its the log mediator, just to test like follows)

[6] Deploy the sequence you are trying out and send a message, that should hit the breakpoint in eclipse

[NEWS] We are also working on a graphical ESB debugging tool for WSO2 ESB 5. So folks the future is bright stay tuned 🙂

Happy debugging !!!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s