Month: August 2016

How To Debug WSO2 ESB in Different Tenants

How To Debug WSO2 ESB in Different Tenants


WSO2 Enterprise Service Bus is a lightweight, high performance, and comprehensive ESB. 100% open source, the WSO2 ESB effectively addresses integration standards and supports all integration patterns, enabling interoperability among various heterogeneous systems and business applications.

And now it also contains message mediation debugging support with the release version 5.0.0. In this post I will deploy a simple proxy on WSO2 ESB and debug the message mediation flow.


First we need to have the mediation debugger supported ESB distribution. WSO2 ESB 5.0.0 is the distribution packed with mediation debugger. You can download RC2 pack from here.

And also we need to have a debugger supported Developer Studio ESB Tool. You can follow this article to install the WSO2 Developer Studio ESB Tool 5.0.0

If you have never tried the wso2 mediation debugger before follow previous post to understand the basics to use debugger.



The goal of multitenancy is to maximize resource sharing by allowing multiple organizations (tenants) to log in and use a single sever/cluster at the same time, in a tenant-isolated manner. That is, each user is given the experience of using his/her own server, rather than a shared environment. Multitenancy ensures optimal performance of the system’s resources such as memory and hardware and also secures each tenant’s personal data.

You can register tenant domains using the Management Console of WSO2 products.

Please follow following two articles to know more about WSO2 tenant architecture and how to use it.

  1. WSO2 Multi tenant Architecture
  2. Managing tenants in WSO2 products

How To Debug Tenants

If you have followed my previous post you know that first we need to start the esb in debug mode. For that we need  to use command -Desb.debug=true. Now we have changed this and you need to use -Desb.debug=$tenantDomain.

So for example if you need to debug the super tenant (It is the default one. If you have no idea about a tenant, that means you are working as super tenant 🙂 ) you can use the command -Desb.debug=super or -Desb.debug=true.

  • Start Debugger in super tenant : -Desb.debug=super

Since the esb server will start in the super tenant mode, the server starting will be suspend till you connect the ESB Tool with server on two ports. So what you need to understand is to connect the server with tool to enable debugging you need to start the server in that specific tenant mode. If you are trying to debug a tenant which is not the super tenant, you may not get the server listening state as it for super tenant. That is because the lazy loading behavior of the wso2 tenants.

[Note-Lazy loading is a design pattern used specifically in cloud deployments to prolong the initialization of an object or artifact until it is requested by a tenant or an internal process.]

Lazy loading of tenants is a feature that is built into all WSO2 products, which ensures that in an environment with multiple tenants, all tenants are not loaded at the time the server starts. Instead, they are loaded only when a request is made to a particular tenant.

So server will start listening to connect with tool when the first request is made for that specific tenant. Lets say you have defined a tenant domain as “”. You need to start the server as Server will start normally in the super tenant mode. Then send a request to proxy/inbound/API in the domain as “http://%5Byour-ip:port%5D/t/”. Then the server will start to listen in the two ports to connect with ESB tool to debug.

  • Start in tenant domain

Let’s do a simple scenario to do this. First we need to create a tenant domain. Start esb server and go to configure section in the management console.


You will see Multi-tenancy section at the bottom. Click on Add new Tenant.


Configure the required fields. And sign in to esb server using entered username and password.

  • User name  :
  • Password    : ******       🙂

Then deploy your artifacts to this tenant. And you will get endpoint urls for your tenant domain

I have created very basic artifact API to test this scenario.


To deploy it to tenant add the started server as a remote server and use tenant credentials.


Then add the capp to server and deploy it.


Now shutdown the server and start it with command sh wso2server


So the server will start in the super tenant mode. Now send a request to our deployed API in the tenant.


Now you will observe that the server starting to listen on two ports to connect with ESB tool.


Now connect with server form the ESB tool.


Then resend/send breakpoints to server.


And send the request again. ESB will suspend on the breakpoint.


What if you do not want to wait to connect the tool when the first request comes. You need to do it in the server start up. Can you do it???

Of course you can. 🙂

What you need to do is disable the Lazy loading of the server and enable the Eager Loading.

How can you do it?

Go to [ESB_HOME]/repository/conf/ and open the carbon xml file. Go to Tenent/LoadingPolicy configuration and comment the LazyLoading policy and uncomment the EagerLoading policy to start all tenants or just



Now the server will suspend and listen on ports to connect with ESB tool debugger at the server startup.

So I now you can debug different tenants too… Happy debugging!!! 🙂