WSO2 Enterprise Integrator 3 min

WSO2TORIAL Setting up debugging on WSO2 ESB 5.0.0

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
Virtual Machine WSO2 Training Yenlo

The new version of the WSO2 supports debugging and tracing of artifacts like proxies and APIs. This is done using the WSO2 Developer Studio (now called ESB Tooling) running on top of Eclipse.

The new ESB

In the latest version of the WSO2 ESB there is now a new setup available. This is an analytics component (DAS) we also see with the API Manager and the Identity Server. It’s a regular and full fledged Data Analytics Server with a purposeful dashboard for that specific product.

Next to the analytics there is a long awaited debugging capability which has been added to ESB v5. This tutorial covers using the debugger with the new release of the WSO2 Enterprise Service Bus. 

In order to use all of the functionality of the WSO2 ESB 5.0.0 we need to set up the three elements:

  1. WSO2 ESB 5.0.0
  2. WSO2 ESB – Analytics
  3. WSO2 ESB – Tooling

 We already wrote about installing the analytics in a previous blog.

We use a virtual machine which Yenlo uses for its WSO2 training courses to install ESB Tooling. This makes it simple to create a test environment. This is a SUSE SLES 12 SP1 environment. For Windows the actions are more or less the same.

Virtual Machine WSO2 Training Yenlo.png

If you already have downloaded the three files from the WSO2 website unpack them somewhere, for instance on the desktop.

If you are installing WSO2 for the first time, please read our blog on what you need to do (e.g. install Java) before continuing. 

Unpack WSO2 ESB analytics and ESB tooling.png

And unpack (right-click -> Extract here) on the desktop.

Extracting the files from WSO2esb 5.0.0.png

ESB 5.0.0 - ESB anaylics 5.0.0 - eclipse.png

You will end up with three directories.


 There are three aspects important when working with debugging:

  1. The WSO2 server needs to be restarted in debug mode (-Desb.debug)
  2. Within one minute you need to start the debugging session, otherwise the ESB will leave debugging mode (this is a parameter you can set to never leave debugging mode).
  3. You need to set breakpoints in the proxies, api’s or sequences.

Setting up Eclipse

We will create a special configuration that will allow debugging based on server startup from Eclipse.

This is done by entering an additional command to the default server startup. This command (see bullet point 1) is added to the debug configurations under the Run option in the menu bar in Eclipse. Please be aware that you create a “Generic Server” type as this allows you to alter the Program arguments as you can see in the below screenshot. In these Program arguments you need to specify the special JVM setting “-Desb.debug” which will prepare the ESB instance to allow debugging of the mediation flow.

Debug Developer Studio Dashboard Eclipse.png

Debug Configurations WSO2 ESB 5.0.0.png

After setting up the server instance configuration, you need create a debug configuration. Right-click on the ESB Mediation Debugger (You see this above the server configuration in the above screenshot) and create a new configuration.

Debug Configurations ESB 5.0.0. -2 .png

Now you can create a default ESB 5.0.0 (Carbon 4.4.0) server on the server tab. Follow the steps and enter the required information to create the server. In case you get an error on a missing classpath, point the CARBON_HOME to the directory where your ESB is installed.

Now you can start the server. Since we added the -Desb.debug to the startup parameters you don’t need to start it in debug mode, but it does not hurt to do so.

Within a minute you need to start the debug configuration as follows:

Debug configuration.png

Debug mode ESB 5.0.0.png

The ESB is now in debug mode.

Setting debugpoints

In order to show the debugging we create a simple proxy calling the echo endpoint (AAR service on the ESB). This is a simple pass-through proxy with two log mediators. Note that the endpoint name is more or less irrelevant here (it was created when the proxy was made and can have any name). We will not go in detail on the how and why of this proxy since this will be covered in the subsequent labs.

Proxy echo endpoint esb 5.0.0.png

Debug Developer Studio Dashboard Eclipse-2.png

You use the icons on the top of the window to step to the next breakpoint just as you use for debugging regular java applications.

Debugging the ESB is something that will make your life easier and something to try out yourself. So grab a copy of the WSO2 ESB and get going.

Happy Debugging!!

Thanks to Thijs Volders for his contribution to this blog.

Read also our other WSO2 tutorials and blogs, written by our WSO2 Gurus. In case you need WSO2 support, contact the Yenlo WSO2 Guru team to get WSO2 Development Support or WSO2 Operational Support. Of course we do deliver excellent WSO2 training services as well, based on reallife WSO2 tutorials.



Full API lifecycle Management Selection Guide

Get it now
What's on our menu