WebLogic Portal Analytics API

Tuesday, April 01, 2008

Aqualogic Analytics provides a great way to for administrators to collect, view and report on metrics with regards to WebLogic Portal usage, now the API it uses to collect these metrics from WLP has been made public in 10.2. Here is an example of how to use this new API to create a very basic view of aggregated analytics suitable for non-production use.

WebLogic Portal has supported the collection of analytics for a few versions now through the Aqualogic Analytics product. A new feature in 10.2 though is that the way these analytics are collected are now exposed through a public API in the com.bea.netuix.servlets.controls.analytics package. While this has just been documented, the APIs are available in earlier versions of WLP 10 as well.

While someone could go hog wild and provide the equivalent functionality of the Aqualogic Analytics package, there are a host of other useful functions that can be driven off of these metrics. For example, the metrics could be used to monitor SLAs and trigger a warning if a specific portlet's response times starts to exceed agreed upon SLAs. Another use case would be to provide debug information at development time to allow developers to get an idea of the relative performance level of a portal and its associated portlets.

It is this latter example that we will build here. The example is a simple shared library that you can plug into a WebLogic Portal application to collect analytics on the Portals in your application. Here is a screenshot of the application, click on the image to see it full-size.

NOTE - this is only an example, it is not BEA supported code and should not be deployed into production environments. In other words, don't blame me if you try to use this in production and find issues <g>.

To use the analytics package, we first need to create a class that implements the AnalyticEventHandler interface. This is a simple class that defines a handful of methods, here is an example implementation.

public class AnalyticsHandler implements AnalyticEventHandler {

    public AnalyticsHandler() {
    }

    public void init() {
    }

    public void dispose() {
        AnalyticsManager.clear();
    }

    public void log(AnalyticEvent event) {
        AnalyticsManager.logEvent(event);
    }
}

The handler has three methods. The first method, init, is called once to initialize the handler and enables the handler to acquire any resources it may need. The second method, dispose, is called to allow the handler to dispose of any resources it has acquired.

The final method is called whenever an analytic event occurs that the handler may wish to aggregate or collect. This method is called often and as a result when implementing the handler it is very important to ensure that this method is well optimized so has not to impact the performance of the Portal. In our example above we delegate the handling of the AnalyticEvent to another class, for the purposes of this explanation I'm not going to get into the details of aggregating the statistics but you can view the source code attached to this entry for details if you wish.

The AnalyticEvent class contains a variety of information including the times for various lifecycle phases of the portlet. The lifecycle phases are pretty clear, the only confusing aspect is that there does not appear to be a phase for handlepostback but in fact handlepostback corresponds to the loadstate lifecycle so it is present. While not covered in the javadoc, the times returned by the methods in this class are in nano-seconds.

To install our handler, we need to add a file called com.bea.netuix.servlets.controls.analytics.AnalyticEventHandler in the classpath in the path META-INF\services. This file contains a single entry which is the class of the handler, for example:

com.bea.ps.portal.analytics.AnalyticsHandler

Now that our handler is installed we are ready to start getting some analytics. I have attached a pre-built library, bea-ps-analytics-1.0.0.war, that you can use to try this out. After downloading the library, add it as a shared library to your application. To do this in a development environment, go to Windows|Preferences in Workshop and expand the WebLogic node. There should be a secondary node called J2EE Libraries, click on this and add the bea-ps-analytics-1.0.0.war file.

Next in your portal WAR project, expand the WebLogic Deployment Descriptor node and right click the J2EE Libraries node. From the popup menu select the Add option and add the bea-ps-analytics library to the application. One caveat here, this will change your weblogic.xml file so make sure not to check this file into your SCM otherwise you may end up with a dependency on this library in production which you do not want to do.

Now that the library has been added, start your server and go to the URL http://localhost:7001/{portalApp}/analytics/index.jsp where you replace the {portalApp} token with the context root of your portal application. You should now see the analytics screen, click the Enable button to turn on the analytics. Open a new browser to your portal and start clicking around, come back to the analytics screen and click the Refresh button. You should see the various metrics displayed for the time you clicked around.

That about covers it, I have attached the source code to this entry for readers that may be interested in how this works in more detail. Please do remember that this is unsupported code and is not intended for use in production environments.

Shared Library: bea-ps-analytics-1.0.0.war

Source Code: bea-ps-analytics-1.0.0.zip

Posted by Gerald Nunn at 1:35 PM | Categories: WebLogic | | | Permalink