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

(Migrated from Rob Woollen's blog on dev2dev with his permission. This entry was originally posted on August 01, 2005 01:47 PM)

Application libraries are a new feature in WLS 9 and one which I helped design and implement so I thought it a natural choice for a blog entry. The product documentation gives extensive information about libraries and specifics on their usage. The purpose of this blog is not to replace product documentation but to highlight new features and to give you insight not only in how the feature works but why we made certain design choices.

Like many of the best features, application libraries were developed directly from customer feedback that delivering applications as a single EAR file was too limiting. Applications often contained components deliverd from different organizations and shared common services. Delivering these components together as a single build proved difficult to manage and upgrade. Developers had no idea how many groups were using a specific version of their components, and it was difficult to tease apart shared services from custom application code.

Application libraries bring ideas like shared libraries or DLLs to the J2EE world. They allow an application to be composed of core application code "linked" with libraries of separately packaged J2EE components. Libraries allow each organization to manage their own deliverable and packaging without requiring a single unified EAR.

For instance, an online banking application might be composed of a security framework, data access code, and presentation logic. To keep things simple, let's say the security code is delivered by a separate organization (obviously security is very important in banking) and the other components are specific to this application. The security developers now merely deliver their components as a standard J2EE EAR file. The online banking application adds an entry to their weblogic-application.xml to express a dependency on the security library, and the WebLogic Server treats these 2 separate files as if they were a single merged EAR file. Since they are separate files on disk, it is much easier for the production team to upgrade the security library or determine who is using a particular version of the library. (We'll discuss a lot more detail here in parts II and III of this series.)

Application libraries are an extremely powerful and useful feature, and I'll cover them in detail over several blog entries. For those of you that want to read ahead, I'd suggest the product documentation or even downloading WLS 9 and trying out libraries.

In Part II, I'll give more details about library semantics, their relation to J2EE Optional Packages, and using library-based applications on older WLS releases or other J2EE servers.

In Part III, I'll cover deploying libraries, versioning, and upgrading library applications with zero downtime.

(Migrated from Rob Woollen's blog on dev2dev with his permission. This entry was originally posted on August 08, 2005 11:29 AM)

Designing large software features like application libraries is always an interesting challenge. While it wasn't initially a stated goal, in retrospect the design was heavily influenced by a desire to minimize the implementation work. I'm certainly not trying to imply the development team was lazy, but minimizing new concepts became the best means to achieve our main design goals:

1. Address customer use cases, specifically separately packaged code libraries potentially shared between many applications and versioned independently.
2. Make it easily possible to port library-based applications to earlier WLS releases or other J2EE servers.
3. Ensure libraries are easily understood and require limited change to existing applications.
4. Provide equivalent deployment, versioning, and management functionality as non-library applications.

I'd really like to emphasize the second point here. While libraries are an innovative feature only in our application server, they aren't meant to lock developers into 9.0. The design strives to make it easy and natural to port library-based applications to older WLS releases or other J2EE servers which don't support this concept.

With those goals in mind, the design that evolved was simply that library applications have the same semantics as if they were deployed together as a single EAR file. Internally the server runs through a series of steps as applications are deployed on the target server. During an early stage in deployment, it establishes which modules are in an application and instantiates containers for each. These might be ejb or web modules declared directly in the application.xml, or they may be imported from a library. The only real difference is the path on disk to the module.

The vital piece to understand is that libraries only change the path where classes and resources are loaded. After the container is created, all semantic behavior is exactly as if everything was within a single EAR file. The classloading, management, console pages etc are all the same. Libraries are merely a packaging concept.

Libraries can be either java classes, a single component (eg a war or ejb-jar), or an EAR file with 1 or more components. In the java class case, the server just adds the jar file to the application's classloader. The single component case is essentially adding a new module entry to the application.xml with a different relative path to the ejb-jar or webapp.

EAR libraries are a slightly more complicated case since the library has its own application.xml and weblogic-application.xml. The server handles this by merging the library's application.xml with the application.xml in the application. The merge is relatively straightforward, but it should be noted that the application's descriptor takes precedence on any conflict. For instance, if you had the same ejb module (same uri) in both the library and the application, the application's version would be used. (I included this information for completeness, but I would recommend that applications not override library modules. If this is necessary, I would suggest repackaging the library as needed.)

Another main design issue was the semantics when multiple applications reference the same library. One option is to have a single library instance shared by all referencing applications. This has some classloader advantages, but it makes redeploying the applications and libraries significantly more complicated. The design instead favored the simpler and more flexible approach where each application included its own library component copy. This approach's advantages may become clearer in the next blog entry which discusses versioning, upgrades, and how to undeploy a library.

WLS 9 includes a tool weblogic.appmerge (run java weblogic.appmerge to see usage) which given an application and 1 or more libraries produces a single, merged EAR file. The tool's merge process shares the same code with the server, but instead of merging data structures in memory, it writes the output to disk. The appmerge tool can be used to debug or better understand how libraries work, but it also allows porting to other servers or older WLS releases.

I hope this blog entry provided further insight into Application Libraries. In my next entry, I'll cover how libraries are versioned, deployed/undeployed, and zero downtime library upgrades. Please post a comment if there's anything that is unclear or suggestions on further topics.

(Migrated from Rob Woollen's blog on dev2dev with his permission. This entry was originally posted on August 22, 2005 02:40 PM)

Library Deployment / Undeployment

Application libraries use the same deployment and distribution machinery as "regular" applications so users are not forced to learn a new set of commands. A library is deployed with either the WebLogic Administration Console, the weblogic.Deployer command-line, the wldeploy ant task, WLST scripting, or the programmatic deployment APIs. Library deployment distributes the files to the target servers and registers itself with the target server's library manager. When an application references a library, the library manager is consulted to ensure the library exists and the correct version is "linked" with the application.

After library deployment, one or more applications may be deployed which reference the library. As was discussed earlier in this series, each referencing application imports its own library copy. The purpose of libraries is to change the packaging of J2EE applications not their semantics.

Libraries may also be undeployed to unregister them and remove their files. Undeploying the library is only possible if there are no deployed applications current referencing it. An attempt to undeploy a library which is still being used will be refused with an error message instructing the user which applications are still referencing it.

Versioning Use Cases

The product documentation provides a lot of background on libraries and their versoning support. Instead of duplicating that effort here, I thought I'd cover a few common use cases, and how they can be solved with library versioning along with some examples.

A library may include a standard java manifest file which supplies version information. The product documentation covers this topic in depth, but the main idea is each manifest may optionally include a specification-version and an implementation-version.

An application includes a library with an entry in its weblogic-application.xml. The entry may optionally specify a specification-version and implementation-version. If a version is not specified, the server defaults to using the latest deployed library version. When a version is specified it indicates the app wants that version or later. The exact-match flag indicates that a later version is not acceptable and only the exact specified version will be used.

The rules are relatively straightforward, but some quick examples will probably help.

Examples

Deployed Libraries

Assume the server currently has 2 versions of the DAO-LIB library deployed:

Note for convenvience, I will abbreviate spec-version of x and impl-version of y as (x/y).

Application library References

Now consider which library is used when applications are deployed with the following DAO-LIB references:

Version Recommendations

It is good practice for each library to include a specification-version and implementation-version. Both versions should be decimals or dewey decimals (eg major.minor.patch) rather than arbitray strings (this makes them comparable.) The specification-version should change when any of the interfaces or conventions change incompatability (basically anytime a referencing application would have to change or recompile.) The implementation-version can be a build number.

Most referencing applications should specify a specification-version and exact-match=true but not specify an implementation-version. This allows the admin to use a newer library build with the latest bug fixes without updating all the referencing application EARs.

Use Cases

1. Integrating Library Bug Fixes

In this scenario the admin receives a new, compatible version of the library with some bug fixes. The library would have changed its implementation-version but not its specification-version. The new library build can be deployed to the server. The application should have specified only a spec-version in its descriptor and when it is redeployed it will automatically pick up the latest library with the bug fixes.

2. Multiple applications using different library versions

In this scenario there are multiple, incompatabile versions of the library being used by different applications. This might occur if an application has not been tested, certified, or updated with the latest library, but another application requires new library functionality. This can be accomplished by deploying the incompatabile libraries with different specification-versions. The referencing applications should specify their required version and set exact-match. This ensures each application will in parallel find their appropriate library version.

3. Zero downtime upgrade of library applications

Application upgrade without downtime is worthy of its own future blog entry. The product documentation covers the background information on this topic. In the library scenario, the first step would be to deploy the new library version. Since libraries only distribute code and register themselves, this won't interrupt any existing applications. Next, the new application can be deployed alongside the existing application version. If the library has changed as well, the updated application can specify exactly what version of the library it requires.

I hope these blog entries have shown you the flexiblity that libraries now offer in WLS 9. There are many more innovative features in WLS 9 that I'll try to cover in the next few weeks.