JMX client to monitor Carbon Servers

Recently we were doing some load testing against Carbon servers. Soon we realized that there was no easy way to get average memory usage and CPU utilization. (apart from taking jconsole screenshots). End of the day we automated the whole testing process. Below is the JMX client [1] that we used to get details out from the remote running Carbon Server.

It dumps the details to a CSV file. Later you can process the CSV s in batch mode.

[1]https://gist.github.com/4143374

Webinar: Artifact Synchronization Between Cluster Nodes

Recently I did a webinar on the topic of "Deployment Sysnchronizer" : the sync-up mechanism we use to synchronize artifacts and meta data in our Carbon product clusters.

WSO2 Dep Sync for Artifact Synchronization of Cluster Nodes from WSO2

Running WSO2 Carbon as a web-app - Apache Tomcat

As I have explained in one of my previous posts, WSO2 Carbon has undergone some major architectural changes from its 3.x.x version to version 4. One of our main goals during those changes was to make Carbon running in a pure-OSGi container instead of running it in a bridged mode. At some point we were considering to drop off the web-app mode deployment, altogether from the C4 release on-wards.  However, thanks to sound architectural decisions that we have made in the past, we realized that it is possible to support web-app mode deployment of WSO2 Carbon without major hassles.

Why Web-app mode deployment?

More often than not, large organizations have their middle-ware platform/part of it,  in place. Not only they have application-servers/ESBs/etc ,but also they may already have built monitoring mechanisms/billing systems based on the existing echo system (Normally internal policies/politics within the organization plays a major role too ;) ). If somebody wants to make use of a WSO2 product within such restrictive environments, the web-app mode deployment of WSO2 Carbon comes to the rescue.

Having said that we strongly recommend running WSO2 Carbon servers in standalone mode.

Pre-requisites

Download Apache Tomcat 7.0
Download WSO2 Carbon 4.x.x

Steps to deploy

Creating the war file
 Extract the product zip directory to the local file-system. From here onwards I'm referring the root of the extracted product directory as $CARBON_HOME.

Under the directory $CARBON_HOME/webapp-mode there is a directory called WEB-INF. As the name suggests, this is the Carbon bare bones web-app. Move it in to a directory with a preferred name. and put the whole directory structure in to the 'webapps' directory of Apache-Tomcat. My preferred directory name is 'crbn'  - please note that, the name of this directory will get picked as the context root of our web-app by Tomcat.

Now the  directory structure is similar to,


crbn/
└── WEB-INF
    ├── eclipse
    │   └── launch.ini
    ├── lib
    │   └── org.wso2.carbon.bridge-4.0.0.jar
    └── web.xml


Configuring the Carbon repository

• Create a directory named "carbon_repo" in a preferred location. For me its located in '/home/pradeep/carbon_repo'. Copy the 'repository' directory found under $CARBON_HOME to the newly created 'carbon_repo' directory.

       From here on-wards of this blog post, I'm referring the directory location of   'carbon_repo' as $CARBON_REPO

        Now the directory structure would look like,

         

        carbon_repo/

                          └── repository

                                        ├── components

                                        ├── conf

                                        ├── data

                                        ├── database

                                        ├── deployment

                                        ├── logs

                                        ├── README.txt

                                        ├── resources

                                        └── tenants

• Replace the DB file location found in '$CARBON_REPO/repository/conf/datasources/master-datasources.xml' with the new path.

         The new master-datasource.xml DB location entry looks like,

• Remove all the tomcat related jars from the '$CARBON_REPO/repository/components/plugins' directory.  The jars represent the embedded version of tomcat. Since our intention is to run carbon under provided servlet container, we no longer need theses jars. The list of jars include,

           org.wso2.carbon.tomcat_4.x.x.jar 

           org.wso2.carbon.tomcat.ext_4.x.x.jar

           org.wso2.carbon.tomcat.fragment.dummy_4.x.x.jar

           org.wso2.carbon.tomcat.patch_4.x.x.jar 

           tomcat_7.0.28.wso2v1.jar

• copy the jars found under $CARBON_HOME/webapp-mode/bundles to '$CARBON_REPO/repository/components/plugins'  directory. namely,

          org.wso2.carbon.http.bridge-4.x.x.jar 

          org.wso2.carbon.servletbridge-4.x.x.jar

       

          and add the following two entries to the 'bundles.info' located under    '$CARBON_REPO/repository/components/configuration/org.eclipse.equinox.simpleconfigurator' directory.

org.wso2.carbon.http.bridge,4.x.x,plugins/org.wso2.carbon.http.bridge-4.x.x.jar,4,true

org.wso2.carbon.servletbridge,4.x.x,plugins/org.wso2.carbon.servletbridge-4.x.x.jar,4,true

Configure Tomcat connectors
To enable https connector in Apache-tomcat edit, $CATALINA_HOME/conf/server.xml


Configure Axis2 transports

Configure '$CARBON_REPO/repository/conf/axis2.xml with the updated transport pors.

Configure webContextRoot and backendServerURL in carbon.xml

Update the fields to,

respectively in the '$CARBON_REPO/repository/conf/carbon.xml'

Endorsing JVM provided classes

Like any other complex java program, Carbon makes use of endorsed libraries for XML parsing/APIs/etc. To endorse libs,
create a directory named 'endorsed' in $TOMCAT_HOME .  Move all the jar files found under  $CARBON_HOME/lib/endorsed to newly created $TOMCAT_HOME/endorsed directory.

Starting the server and accessing the management console

set the CARBON_HOME system property to the created 'carbon_repo' directory,

export CARBON_HOME=/home/pradeep/carbon_repo

start Tomcat server, using,

./bin/catalina.sh run

access the carbon management console using,

https://10.100.2.1:8443/crbn/carbon


Please Note

WSO2 Carbon is a fully fledged server runtime. This blog post is for get it working with Apache Tomcat servlet container. The steps depend on the application server.

WSO2 Carbon 4.0 Architecture - My Notes

With the 4.0 release of WSO2 Carbon  we have changed the internal architecture of the platform in a significant way. In the pre Carbon 4 era, WSO2 carbon used to get deployed as a web-app on apache-tomcat servlet container under the hood. The hight level architecture looked like,

 As shown in the above diagram Carbon framework get deployed as just another web-app in Apache tomcat server. Hence, in the in the Carbon 3.2.0 architecture there were two Carbon environments,

1. The OSGi environment - the area where coloured in light blue
2. The Non OSGi environment - rest of the area

The requests were routed to the OSGi environment using the bridge-servlet mechanism.(read the equinox getting started guides for more details)

However with this approach there was a noticeable disadvantage:

JAR duplication -  Carbon based products like WSO2 Applicaton Server allows users to deploy web-applications. To share some of the core APIs with the third-party web-apps we had to move them-out/duplicate from the Carbon OSGi environment. (Eg: Carbon Context API).


The Solution : Make Tomcat a bundle and move it in to the OSGi environment

In the new architecture we run our application within a pure OSGi environment. There is no bridging between environments. One of the reasons that blocked us from moving to this clear architectural model was the unavailability of tomcat as a bundle. We created a OSGi bundle version of embedded tomcat, which is somewhat similar to existing OSGified jetty servlet container.


Some of the pros of the above approach includes:

1. There is no jar duplication. Hence almost all the carbon related jars resides in $CARBON_HOME/repository/components/plugins directory
2.Now the all the Carbon libs are visible to the third-party web-apps. This is one of reasons why we are going to support native support for CXF web-apps.
3. Now carbon can be deployed in any OSGi framework/platform with minimal set of modifications - its a set of bundles.


However a techy user still can deploy Carbon as a web-app in another servlet container like Apache-tomcat standalone server, JBoss, IBM WAS, etc. :)
The documentation will follow.

Debugging your OSGi Application using OSGi console commands

This blog post is mainly targeted at the WSO2 Carbon developers who make use of OSGi console to debug their bundles/components during the runtime. I'm here assuming that you have the basic shell which you would find in equinox environment.
You can start any of the WSO2 server products (that is based on Carbon) with OSGi console enabled, by passing the system property 'osgiConsole' during the startup. To do so, start the carbon server with,
./wso2server.sh -DosgiConsole
After full server startup pressing enter in the command shell will give you the OSGi shell command prompt, which looks like;
osgi>

After that you can valid OSGi command using this shell. Let us explore some of those,
The below commands will help you while debugging bundles in 'Module Layer':

Command	Use-Case
install file:/<filePath of bundle jar>	Install bundle jar in to runtime
ss	To simply list down the bundles along with the life-cycle state we can use this command.
start <bundleId found using ‘ss’ command>	starting the bundle given by bundle ID.
b <bundleId>	Prints all the details attached with bundle including  importing packages, exporting packages, etc.
diag <bundleId>	If the bundle is still in installed state we can use this command to find the missing constraints which are stopping bundle going in to next lifecycle stage
p <packageName>	List all the bundles that import/export the given package name within the runtime.
stop <bundleId>	stopping the bundle given by bundle ID
uninstall <bundleId>	uninstalling the bundle

To debug OSGi services(Service Components) layer you can use the following commands.

Command	Use-Case
ls	list down all the service components found in this runtime along with their component ID and life-cycle status
enable <componentID>	enabling service components
comp <componentID>	Use this command to find unsatisfied services of the given component, which prevent it from going it to satisfied state.
ls  -c <bundleID>	same as the above command, but you can retrieve the information on your service components using the bundle ID instead of component ID
services	list down all the services in the runtime including services provided by the system bundle. You can use simple filters to narrow down your list. eg: To find out the bundles/serviceComponents that expose the OSGi service ‘ org.foo.bar’ you can use the command: >services (objectclass=org.foo.bar)    or >services (objectclass=*foo.bar)
disable <componentID>	disabling component  given by the component ID

You don’t have to memorize these commands; all the commands along with their documentation can be found using the OSGi console command ‘help’. This is just a quick reference guide. You can extend the available set of commands by writing your own command provider. Hope this helps.

Revert not-commited local changes of a file in Git

git checkout  'file-name'

just a small note