Introduction

The IBM® Autonomic Computing Toolkit consists of a number of interlocking components that can be mixed and matched to build advanced autonomic computing systems. But, the components are not a closed system. The components are built on open standards and are designed to be easily modified and extended with third-party solutions that, in turn, can be embedded in other solutions. It is this very openness that gives the IBM Autonomic Computing Toolkit its flexibility.

This article describes a joint work effort undertaken at the IBM Innovation Center for Business Partners at San Mateo, California, between IBM and Singlestep Technologies, Inc., a Seattle-based Independent Software Vendor, to demonstrate the ease with which the Autonomic Computing Toolkit components can be extended and embedded in other systems.

The The Problem Determination Scenario (PDS) is a basic self-managing autonomic computing system that illustrates how components from the IBM Autonomic Computing Toolkit can be used to detect, diagnose, and repair the failure of a standard Java 2 Platform, Enterprise Edition (J2EE) application without human intervention.

The heart of the system consists of an instance of the Autonomic Management Engine (AME) that continuously monitors event information from the application. The Integrated Solutions Console (ISC) introduces a failure in the application by stopping the Cloudscape™ database from which the WebSphere® application server is fetching HTML pages. This causes the WebSphere application server to log an error, which is transformed into a Common Base Event format by the Generic Log Adapter (GLA) and then detected by the AME monitor engine.

To work with this situation, the AME relies on a decision algorithm within its resource model to stop and restart the WebSphere application server and the Cloudscape database. But, what if the decision algorithm needs to be modified after the autonomic computing system has been installed? In this situation, an external policy-based decision engine with policies that can easily be modified by business people can lend considerable flexibility to the system.

Singlestep Technologies has created a comprehensive policy engine, Policyscape, within their product, Unity. This article demonstrates how the capabilities of Policyscape can be integrated with the AME resource model by sending Unity an event from within the decision algorithm, which extends the AME functionality. Figure 1 illustrates the completed system architecture, integrating business and programmer level functionality.

This article shows a way to create a framework within the AME resource model decision algorithm for formatting events and sending those events over a TCP connection to a Unity Connector object. Although this does not represent a complete solution, it serves as a starting point for integrating Unity into the context of a resource model. It also explains several fundamentally important aspects of AME that can be applied to resource models in general, including:

• Opening and modifying the existing AME resource model
• Adding a custom Java class to the resource model
• Packaging and deploying the modified AME resource model

This article describes the Unity architecture and Policyscape and the methods by which policy-based actions are performed. It also demonstrates the following:

• Creating a properly formed Unity event using the Unity Event Java Developer's Toolkit (Unity Event JDTK)
• Sending the event to Unity
• Processing the event in the Policyscape

Back to top

Unity Architecture

The Unity application receives events from a wide variety of event data sources through interfaces called Connectors. Each Connector is designed to communicate with a specific data silo through its native means of communication. In this article's example, the Problem Determination Scenario resource model sends events to Unity through a configurable TCP port. Valid events are normalized as they are received, written to the Unity SQL database, then passed to Policyscape for evaluation. Figure 2 shows the Unity server interface and a variety of the available Connectors.

Unity and the Visual Network Object System

Unity is designed to run in a Visual Network Object System (VNOS) environment and relies on the library of VNOS objects for its functionality. Figure 3 shows the library of VNOS Widgets, while Figure 4 shows the library of VNOS Controls. VNOS, unlike other object-oriented programming languages, is a drag-and-drop, click-and-connect programming environment for describing and controlling the flow of information through any system.

The Unity Policyscape

The Unity Policyscape is a subscription policy engine for implementing rules-based policy directives. A variety of actions can be performed from the Policyscape because it uses VNOS as its programming language. Policies are portable, allowing a policy to be used again and again, easily modified using the Policy editor included with Unity, and human readable. In this article's example, a policy determines the nature of an event received from the AME, then runs external command-line batch files to correct the problem. Figure 5 shows the basic Policyscape for this article. The Scenario1 Policy subscribes to the events from the resource model in the Problem Determination Scenario.

The Unity Event Java Developer's Toolkit

Included with this article is the Unity Event Java Developer's Toolkit. The JDTK contains a Java Archive (JAR) file containing Unity event classes. The example uses the com.singlestep.unity.Event() class to create an event and the com.singlestep.unity.EventHandler() class to send the event to Unity via TCP. This article does not deal with Unity event exception handling, but the JDTK fully supports exception handling.

Listing 1 shows a properly formatted Unity event sent using the JDTK from within the Problem Determination Scenario resource model and represents one of the main goals of this article.

<event
	OriginatingID="AMERM",
	UnityEventID="",
	UnityOriginator="AME",
	EventCategory="UPDOWN",
	UnityEventCategory="NetworkEvent",
	PhysicalSource="cloudscape",
	OriginatingTime="09/01/2004 18:40:10",
	Message="CONM7007I",
	Severity="1",
	Priority="1",
	Assignee="AME",
	Count="",
	Description="CONM7007I: Mapping the following SQLException, with ErrorCode -4499
		and SQLState [null];, to a 
		StaleConnectionException:com.ibm.db2.jcc.c.DisconnectException:
		A communication error has been detected. Communication protocol being 
		used: {0}.
		Communication API being used: {1}. Location where the error was 
		detected: {2}. 
		Communication function detecting the error",
	State="Down",
	Status="",
	Path="Java Unity SDK!",
	GenericKey=""
/>

Back to top

Problem Determination Scenario Overview

In order to understand the Unity Policy discussed later in this article, you must have a fundamental knowledge of the basic inner workings of the Problem Determination Scenario. Although it is set up and initiated through the Integrated Solutions Console, the Problem Determination Scenario is actually controlled with a variety of command-line batch files residing in the PDScenario directory ([Drive]:\Program Files\IBM\AutonomicComputingToolkit\PDScenario) that the ISC executes. The main batch files and their functions are listed in Table 1. The highlighted batch files are the actions issued by the AME (and in this prototype also by the Unity Policy) in response to events detected in the CBE.

Figure 6 illustrates the process of introducing, then correcting the problem.

Note that stopPDApp.bat, startPDApp.bat, and startNetworkServer.bat are the batch files used by the AME to restart the Cloudscape database and restore the J2EE Web application. As this process occurs, the pdstatus.txt file, located in the PDScenario directory, tracks the progress. The ISC reads pdstatus.txt file and displays the corresponding messages as shown in Figure 7.

Back to top

Modifying the existing Problem Determination Scenario resource model

You can modify the Problem Determination Scenario resource model using the Tivoli Monitoring Resource Model Builder (see Resources for more information). The RMB must be properly installed before you can perform the following steps. Modifying the Problem Determination Scenario resource model involves:

• Unpacking and deploying the Unity Event JDTK
• Unpacking and importing the existing Problem Determination Scenario resource model into the Resource Model Builder
• Updating the resource model source code
• Repackaging and redeploying the resource model
• Restarting the Problem Determination Scenario

Unpacking and deploying the Unity Event JDTK

1. Download the included UnityJDTK.zip file to a temporary directory.
2. Unzip the file into a directory called [Drive]:\Singlestep\UnityJDTK.
3. This directory includes the User's Guide in a .pdf format, a doc folder, and the UnitySDK.jar file.
4. Copy the UnitySDK.jar file to the AME/lib folder ([Drive]:Program Files\IBM\AutonomicComputingToolkit\AME\lib).

Unpacking the existing Problem Determination Scenario resource model

1. Unzip the CanonicalSituationMonitor.zip file in the PDSCenario directory into a directory called [drive]:\PDSRM.
2. Rename the CanonicalSituationMonitor.zip file in the PDScenario directory to CanonicalSituationMonitor_old.zip.
3. Start the Tivoli Monitoring Resource Model Builder.
4. Select File > Import.... The Import window opens.
5. Choose Existing Project into Workspace and select Next.
   
   Figure 8. The Import window
   
   
6. In the next window select Browse... to locate the Problem Determination Scenario resource model project file. Resource models files have the extension .jrm. Navigate to and select [drive]:\PDSRM\Canonical.
   
   Figure 9. The Browse for Folder window
   
   
7. Select OK to close the Browse for Folder window.
8. Select Finishto complete the import.

Updating the resource model source code

1. In the Resource Model Builder, expand the Canonical project folder.
2. Expand the Canonical.jrm node.
3. Double-click the Source node to display the resource model JavaScript source code.
   
   Figure 10. The Resource Model Builder source code
   
   
4. Locate the // GLOBAL CONSTANTS section near the top of the source code and add the function to import the Unity Classes Package as shown in Listing 2.
   
   Listing 2. Adding the Unity event class package
   

   // GLOBAL CONSTANTS importPackage(Packages.com.singlestep.unity); //import Unity Event classes

   
   
   This locates the .jar file that corresponds to the com.singlestep.unity namespace and imports all of the subclasses in the archive into the current namespace.

5. Further along in the code (approximately Row 290), locate the //Stop the WebSphere Application section. This is the section of the resource model decision algorithm that corrects the detected fault. At this point in the decision algorithm it has been determined that the Cloudscape database has failed. The resource model stops the WebSphere application, but further processing is handled by Unity, based on the contents of the event sent using the sendUnityEvent() function.

   Add the necessary code and comment the necessary lines shown in bold in Listing 3.
   
   Listing 3. Inserting the sendUnityEvent() function in the decision algorithm
   

   //Stop the WebSphere Application shellRc = Svc.ShellCmd(stopScript); str_Result = Svc.GetShellStdOut(); str_Err = Svc.GetShellStdErr(); Svc.Trace(TRACE_FINEST,TRACE_SOURCE + "===> Call to: " + stopScript + " " + str_Cell + " " + str_Node + " " + str_Server + " " + str_sourceComponentId_application); Svc.Trace(TRACE_FINEST, TRACE_SOURCE + "===> Returned result from stopApp = " + str_Result); Svc.Trace(TRACE_FINEST, TRACE_SOURCE + "===> Returned Err from stopApp = " + str_Err); //send Unity event sendUnityEvent(str_msg,str_msgId); //Restart CloudScape //Svc.DetachedShellCmd(StartNetworkServer); Svc.Trace(TRACE_FINEST, TRACE_SOURCE + "===> Call to:" + StartNetworkServer); // Start the WebSphere Application //shellRc = Svc.DetachedShellCmd(startScript);

   
   

6. At the end of the original source code, add the code shown in Listing 4. This code adds a function that creates a valid Unity event, then sends the event to the Unity server over TCP port 1929. This port is configurable and must match exactly the TCP port configured in the Connector in Unity. Connector configuration is detailed later in this article.
   
   Listing 4. sendUnityEvent() function
   

   function sendUnityEvent(eventDesc,msgId) { //create Event and set properties //create date var now = new Date(); var event1 = new Event(); event1.setOriginatingId("AMERM"); event1.setUnityOriginator("AME"); event1.setEventCategory("UPDOWN"); event1.setUnityEventCategory("NetworkEvent"); event1.setOriginatingTime(now); event1.setPhysicalSource("cloudscape"); event1.setDescription(eventDesc); event1.setSeverity(1); event1.setPriority(1); event1.setAssignee("AME"); event1.setState("Down"); event1.setMessage(msgId); //open connection and send event var eh = new EventHandler("localhost", 1929); eh.connect(); eh.send(event1); eh.disconnect(); }

   
   

Repackaging and redeploying the resource model

1. When your modifications are complete, select File > Save Canonical.jrm.
2. Select ITM > Generate Package > TAME (zip).
3. At the Export ITM Package window, browse to the PDScenario directory. Enter the file name CanonicalSituationMonitor and click Save.

Restarting the Problem Determination Scenario

1. If the ISC is open and the scenario is running, select Close Scenario from the Problem Determination Scenario Control Panel.
2. Delete the logs directory from the PDScenario directory.
3. If the ISC is open, select Setup Scenario from the Problem Determination Scenario Control panel.
4. Otherwise, from the desktop, select Start > Programs > IBM Autonomic Computing Toolkit > Problem Determination Scenario > Start PDScenario Servers.
5. After the PDScenario servers start, from the desktop, select Start > Programs > IBM Autonomic Computing Toolkit >Problem Determination Scenario > Launch Web Console.
6. Log into the Web console and expand Autonomic Computing Scenarios > Problem Determination Scenario > Scenario Control.
7. Select Setup Scenario from the Problem Determination Scenario Control panel. If, after several minutes, the hyperlinks in the control panel to Induce Condition and Close Scenario are not activated, there was most likely a problem starting the resource model.
8. Open the msg.log file in the PDScenario\logs directory in a text editor or text file viewer. The last line should read rm-type = CanonicalSituationMonitor; rm-context = has been started successfully. If not, your resource model did not start. The trace.log file in the same directory contains the necessary debug messages to begin troubleshooting your resource model.

Back to top

Unity Connector Configuration

The following section is for information only and describes the Unity environment and policies that add policy-based actions to the Problem Determination Scenario. The components in this section are not available for download and are specific to this article; however, you can get more information at the Singlestep Technologies Web site (see Resources for more information).

Configuring the TCP Port

As described earlier, events are sent from the resource model to Unity over TCP port 1929. This port is configurable on the Unity AME TCP Event Connector as shown in Figure 11 below.

When activated, the Connector listens on port 1929 and receives only valid Unity events from the resource model.

Back to top

Unity policy

The event is parsed into the Unity SQL database and then passed to the Policyscape. Figure 12 shows a valid event as it is received into the Policy.

Note that the DeviceName is cloudscape and the State is Down. These two fields are used in the Policy Input section (see Figure 13) to filter incoming events.

Figure 13 is the top-level code view of the Policy. As events are accepted into the Policy, the threshold is checked, and the batch files to start Cloudscape and the Problem Determination Web application are executed from the command tool objects. Figure 14 is a detailed look at the command tool object used to start the Cloudscape database server by executing startNetworkServer.bat.

The final aspect of the Policy is the configurable threshold checker. In the configuration in Figure 15, if three events are received within five minutes, an e-mail is automatically generated and sent to one or more configurable e-mail addresses. This subroutine uses a variety of VNOS widgets to perform a relatively complicated task.

Back to top

Conclusion

Introducing the condition from the ISC sends an event to Unity for processing in the Policyscape engine. This step adds a new dimension to the Problem Determination Scenario: a function that sends an e-mail when a threshold has been reached. The updated Problem Determination Scenario is shown in Figure 16.

In this article, we've touched on the tasks necessary to integrate a third-party application into the context of a resource model. We've covered some fundamental aspects of AME resource models, and we've explained how we used the combined strengths of the Problem Determination Scenarion and the Autonomic Management Engine (from the IBM Autunomic Computing Toolkit) and the Unity policy engine, Policyscape, to create a threshhold checking solution. You can use this example in your own environment to add a custom class to an existing resource model, and to use that class to extend the functions of the resource model.

Back to top

Download

Information about download methods

Resources

• Calling Java classes from AME (developerWorks, June 2004) discusses the implementation of a custom class within an AME resource model.
  
  
• You can modify the Problem Determination Scenario resource model using the IBM Tivoli Monitoring Resource Model Builder (RMB).
  
  
• Create a simple resource model for processing Common Base Events from a file (developerWorks, June 2004) describes how to build a resource model from scratch
  
  
• The Problem Determination Log/Trace Scenario Guide details the installation, configuration, and overall functionality of the Problem Determination Scenario.
  
  
• A Practical Guide to the IBM Autonomic Computing Toolkit, an IBM Redbook provides information related to using the IBM Autonomic Computing Toolkit.
  
  

About the authors

Lennart Frantzell is a Senior Technology Consultant for autonomic computing at the IBM Innovation Center for Business Partners in San Mateo, California. He has a background in artificial intelligence, object-oriented programming, networking, and J2EE systems. His dream is to replace mankind with autonomic computer systems. He can be reached at alf@us.ibm.com.

Ron Allen has been a developer and solutions architect since 1999. He has a technical background in teaching, aerospace, and geographic information systems. Currently with Singlestep Technologies, Ron is the senior technical consultant for the Singlestep/IBM Joint Development Project, specializing in autonomic solutions readiness and deployment. As a Technical Product Manager, he focuses on the product requirements for future releases of Singlestep's flagship product suite, Unity. He can be reached at ron.allen@singlestep.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Unity Architecture
• Problem Determination Scenario Overview
• Modifying the existing Problem Determination Scenario resource model
• Unity Connector Configuration
• Unity policy
• Conclusion
• Download
• Resources
• About the authors
• Comments