Instrumenting Java EE applications in WebLogic Server

In next few blog entries, I am going to write about class instrumentation feature in WebLogic Server. The instrumentation feature is part of Weblogic Diagnostics Framework (WLDF) and exists since WLS 9.0.

The Instrumentation feature enables you to modify the application classes on the fly and weave additional code to get additional information about your application behavior. The Instrumentation feature in WebLogic Server is designed to have visibility into application code at runtime specifically to diagnose performance impact. For example you could turn on instrumentation in production to find out how your servlet or EJB is performing. WLDF provides ability to turn on and off instrumentation conveniently.

The class instrumentation essentially involves modifying the class byte code at deployment time and injecting the additional code in the compiled class at well known places. WLDF identifies well known places in Java EE applications by named entities called Monitors. While a monitor essentially identifies a point of code entry in your java EE application, an ‘Action’ identifies what the code is going to look like.

For example Servlet_Around_Service is a monitor which identifies entry point in a servlet around servlet’s service method and TraceElapsedTimeAction is one of the actions WLDF provides which emits information about total elapsed time in a servlet’s service method.

The WLDF provides a rich set of monitor and action libraries so that all you have to do it to configure and use them in your application.

In this section, I am going to show you how you can quickly get started with the instrumentation and get the feel of it. In the next blog entry, I will explain the inner details of instrumentation feature in detail.

Enabling the Instrumentation:

The instrumentation is disabled by default. Enabling the Instrumentation feature requires you to create a WLDF System Module in your configuration. WLDF System Module is a server level resource and can be easily created using WebLogic Admin Console. Follow the following steps to create WLDF System Resource.

1) Browse to Diagnostics -> Diagnostic Module after login

2) Click on “Create a Diagnostics System Module”

3) provide the name of the module in the dialog box and click on finish

4) now click on the module you just created and browse to ‘instrumentation’ tab

5) click on ‘enabled’ flag and save your changes

6) Click on the module you created and browse to ‘Targets’ tab.

7) Select the server where you want the instrumentation to be enabled. If it is single server domain, you will only see on server there.

8) save your changes.

The changes you just made should modify your server configuration. You should see following entries in config.xml ( provided your server name is myserver and wldf module name is mywldf)

<wldf-system-resource>

    <name>mywldf</name>

    <target>myserver</target>

    <descriptor-file-name>diagnostics/mywldf.xml</descriptor-file-name>

    <description></description>

 </wldf-system-resource>

Please note that your changes also created a wldf system resource file name /diagnostics/mywldf.xml

Adding WLDF descriptor to your application

So for you have created artifacts to enable the instrumentation feature itself. Next we have to add the information on what to instrument in your application.

You need to create a wldf descriptor file and add that file to the meta-inf directory of your application. The name of the descriptor should be weblogic-diagnostics.xml. This file can be added either at ear level or module level.

For you to quickly experiment with the feature, create a file named weblogic-diagnostics.xml and add the following to the file.

<?xml version='1.0' encoding='UTF-8'?>

<wldf-resource xmlns="http://www.bea.com/ns/weblogic/weblogic-diagnostics"
 xmlns:sec="http://www.bea.com/ns/weblogic/90/security"
 xmlns:wls="http://www.bea.com/ns/weblogic/90/security/wls"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-diagnostics
 http://www.bea.com/ns/weblogic/weblogic-diagnostics/1.1/weblogic-diagnostics.xsd">

  <name>weblogic-diagnostics</name>

  <instrumentation>

    <enabled>true</enabled>

    <wldf-instrumentation-monitor>

      <name>Servlet_Around_Service</name>

      <enabled>true</enabled>

            <action>TraceElapsedTimeAction</action>
  

      </wldf-instrumentation-monitor>      

    </instrumentation> 

</wldf-resource> 

This descriptor adds the Servlet_Around_Service monitor. A monitor identifies a point in the code where specific action is inserted. The Servlet_Around_Service monitor weaves code around servlet’s service method. The woven code is identified by the action. In this example action specificed is TraceElapsedTimeAction. The TraceElapsedTimeAction indicates that instrumentation feature will generate events for every call to servlet’s service method about the total time spend in the service method. The time spend also include any downstream call to other subsystem like EJB, JDBC etc.

How to view WLDF data

The output of the instrumentation is the instrument events. The instrumentation events are persisted in the event log archive. You can view the even log by WebLogic Admin Console

1) Browse to diagnostics -> Log Files , Click on ‘Events Data Archive’ to view the instrumentation event logs.

Currently WebLogic Admin Console only shows events generated in last 5 minutes. However, all the events are archived.

In next blog entry, I will explain the internal details of WLDF Instrumentation feature.

The WLDF instrumentation for WLS 10.3 is documented in detail at

http://e-docs.bea.com/wls/docs103/wldf_configuring/config_instrumentation.html