Document Number SC30-4083-02
| Note |
|---|
|
Before using this information and the product it supports, read the general information in Appendix C, Notices. |
Second Edition (August 2004)
This edition applies to Release 2 of the Autonomic Computing Toolkit and to all subsequent releases and modifications until otherwise indicated in new drafts.
(C) Copyright International Business Machines Corporation 2004. All rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Appendix A. Understanding Common Base Events Specification V1.0.1
Appendix B. Getting help, service, and information
The Autonomic Computing Toolkit Developer's Guide is intended as a technical guide to assist programmers in using the technologies included in the Autonomic Computing Toolkit to develop autonomic solutions. This guide provides the foundational techniques that can be combined in many different ways to achieve different solutions addressing a variety of applications.
The concepts used in this guide build on autonomic computing architectural concepts, and it is recommended that anyone intending to implement autonomic solutions first read the Autonomic Computing Toolkit User's Guide. It offers a solid foundation for comprehending and exploiting the concepts used in this guide.
After reading this guide, you should be able to combine the technologies in the Autonomic Computing Toolkit with your existing products in order to create useful autonomic solutions.
This guide is a part of a step-wise flow from basic information all the way to creating your own autonomic solutions. The following list summarizes the learning flow:
There is an appendix that provides detailed reference information for several of the technologies in this guide.
This guide is for software developers using the Autonomic Computing Toolkit. Expected users of this Autonomic Computing Toolkit are developers who are interested in developing solutions using the content of the Autonomic Computing Toolkit.
The latest softcopy versions of documentation are available on the autonomic computing developerWorks Web site at:
www.ibm.com/developerworks/autonomic/
The autonomic computing library consists of the following documents:
The HTML version of this document and other related publications is accessibility-enabled for use with the IBM Home Page Reader.
For the latest news and tips on general autonomic computing topics, go to the autonomic computing Web site at:
You can also download the Autonomic Computing Toolkit, documentation, and access additional information from the developerWorks Web site at:
www.ibm.com/developerworks/autonomic/
Here you will find information about general autonomic computing concepts, an overview of the Autonomic Computing Toolkit, and most importantly, articles, and tutorials that show you how to apply the tools from the Autonomic Computing Toolkit in real-life situations. After you decide which pieces of the Autonomic Computing Toolkit you need, you can easily download the code right from this Web site.
Your feedback is important to help us provide the highest quality information. If you have any comments about this guide, you can submit them on the IBM autonomic computing Web site at:
www.ibm.com/developerworks/autonomic/
As outlined in the Autonomic Computing Toolkit User's Guide, the autonomic computing reference architecture defines the concept of an autonomic manager communicating with one or more managed resource touchpoints through a manageability interface organized into sensor and effector operations. Figure 1 shows the autonomic computing reference architecture.
Figure 1. Autonomic computing reference architecture
This chapter shows how to use classes provided in the Autonomic Computing Toolkit to implement the manageability interface. It examines how to initialize that communication and how to use the various interaction styles that implement the sensor and effector operations. The topics in this chapter are the key concepts that will allow the autonomic managers and managed resource touchpoints detailed in Autonomic managers and Managed resource touchpoints to combine to form the autonomic solutions examined in Sample autonomic solutions and Custom autonomic solutions.
Autonomic managers and managed resource touchpoints communicate through sensor and effector operations. To create autonomic solutions, architectural concepts such as sensor and effector operations must ultimately be translated into a set of classes that represent their functionality.
Sensor and effector operations are organized into interaction styles, which are, in turn, programmatically implemented. In the Autonomic Computing Toolkit, Java(TM) classes are used to implement the interaction styles.
In the simplest terms, sensor operations are typically used to transmit events or properties to an autonomic manager, whereas effector operations are typically used to cause some sort of change in a managed resource, such as altering state data or setting property values.
Sensor and effector operations are organized into a set of interaction styles that formalize and define how an autonomic manager and its managed resources interact. Sensor and effector operations each can have two interaction styles, as illustrated in Figure 2.
Typical uses for these interaction styles are:
These interaction styles are differentiated by whether the autonomic manager or the managed resource makes contact first. In the cases of the sensor receive-notification and the effector call-out-request, the managed resource makes contact first.
This release of the Autonomic Computing Toolkit deals mainly with the receive-notification style of interaction, in which a managed resource touchpoint asynchronously sends Common Base Events to an autonomic manager. The retrieve-state interaction style is also illustrated in the solution install and deployment technologies-based autonomic solutions.
The Autonomic Computing Toolkit provides implementation classes for the receive-notification interaction style, as well as other interfaces necessary for initiating contact between autonomic managers and their managed resources. The technologies in the Autonomic Computing Toolkit use Java(TM) technology for this purpose, although any programming language could be used.
These implementation classes are included in a .jar file named amtapi.jar, which can be found in the Problem Determination scenario bundle. To use the classes in an autonomic solution, the amtapi.jar file must be placed in the Java classpath at build time.
The classes provided in amtapi.jar represent the most contemporary autonomic interaction implementations. For historical reasons, some of the autonomic solution scenarios in the Autonomic Computing Toolkit do not use these classes, although they still do conform to the autonomic reference architecture and use the sensor and effector interaction styles described earlier.
It is strongly recommended that any new custom solutions you create use these implementation classes.
To encapsulate the functionality required for interaction style implementation, two special classes are included in amtapi.jar. These classes are com.ibm.autonomic.resource.ManagedResourceTouchpoint and com.ibm.autonomic.manager.AutonomicManagerTouchpointSupport. Their relationship is shown in Figure 3.
Figure 3. Implementation classes
These two classes are responsible for initializing interactions, exposing the interfaces that support interaction style functionality, and translating the interaction style interface invocations into meaningful actions within an autonomic manager or managed resources. These functions are discussed in more detail in the following sections of this chapter.
The responsibilities of the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes are as follows:
The implementations of these classes in the Autonomic Computing Toolkit provide a basic implementation for each of the functions just listed. The Problem Determination scenario included in the Autonomic Computing Toolkit provides PDAutonomicManagerTouchpointSupport and PDManagedResourceTouchpoint classes that extend the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes, respectively.
For convenience in the following discussion, these two special classes will collectively be referred to as the implementation classes. Source code for these classes is included in the amtapi.jar file and it is recommended that you refer to these for the following discussion.
Before autonomic managers and managed resource touchpoints can start interacting, the implementation classes must be instantiated. The autonomic manager must then find its managed resources and assign itself as their manager. These operations are described next.
Each of the implementation classes is provided with a Java main method so that they can be instantiated directly (for testing purposes). However, the most common way that these classes will be created by instantiation during autonomic manager startup, in the case of the AutonomicManagerTouchpointSupport class, or during startup of the resources that comprise a managed resource, in the case of the ManagedResourceTouchpoint class.
The only requirement for creating the implementation classes is that each one's start() method be invoked immediately after instantiation. The start() methods perform, among other duties, housekeeping functions and publication of the classes to the RMI registry.
Each of the implementation classes publish themselves in the RMI registry of the machine where they are instantiated. Because Release 1 of the Autonomic Computing Toolkit supports only single-machine autonomic solutions, there is only one host machine and therefore, a single RMI registry. The classes both publish to the RMI registry on localhost. Both classes extend the Java UnicastRemoteObject to facilitate publication in an RMI registry.
To publish itself to the RMI registry, the ManagedResourceTouchpoint class invokes its publish() method from within its start() method. A portion of the publish() method is shown in the following code sample:
protected void publish(ManagedResourceTouchpoint res,
String resourceURL)
throws RemoteException
{
if (System.getSecurityManager()
== null)
{
System.setSecurityManager(new RMISecurityManager
());
}
try
{
Naming.rebind(resourceURL, res);
}
.
.
.
Notice that the method sets a security manager if one is not present (required by RMI) and then binds the ManagedResourceTouchpoint (passed as an argument) into the RMI registry using the URL string (also passed as an argument). The start() method invokes this method as follows:
publish(this, "//localhost/ManagedResourceTouchpoint");
Note that the class passes its own instance as the ManagedResourceTouchpoint instance and a fixed URL string as the binding URL. This is the default behavior for the class. It is expected that custom solutions that extend this class will provide their own URL strings.
The AutonomicManagerTouchpointSupport class uses a similar method to publish itself in the RMI registry.
Because the autonomic manager must make first contact with its managed resource touchpoints, it is important that the ManagedResourceTouchpoint class be instantiated first so that it will be available in the RMI registry when the AutonomicManagerTouchpointSupport class is created.
After the autonomic manager and managed resource touchpoints have been published, the autonomic manager can look up its managed resource touchpoints and assign itself as their manager. To do this, the autonomic manager resolves each associated touchpoint from the RMI registry and then invokes the assignManager() method on each of those touchpoints, specifying itself as the autonomic manager to be assigned. The managed resource touchpoint then uses this supplied address for subsequent invocations of its autonomic manager's interface.
To accomplish this binding, the autonomic manager must be supplied with a list of the addresses of its managed resource touchpoints. In the Autonomic Computing Toolkit examples, this is accomplished by using constant addresses in the autonomic manager's startup routines, or by retrieving a list of the addresses from a data repository (other methods, such as performing searches within a machine or network, or querying another autonomic manager for a list, could also be used). The autonomic manager then uses the specified addresses to obtain pointers to each managed resource touchpoint.
A portion of the AutonomicManagerTouchpointSupport class start() method is shown in the following code sample. This part of the method resolves the touchpoints and invokes their assignManager() methods.
.
.
.
// resolve all resource touchpoints
ManagedResourceTouchpoint resolvedTP =
resolveTouchpoint
("//localhost/ManagedResourceTouchpoint");
// add resolved touchpoint to touchpoint list
resourceTouchpoints.add(resolvedTP);
// loop and assign self as manager for all resolved touchpoints
Iterator i = resourceTouchpoints.iterator();
while (i.hasNext()
)
{
// get the next touchpoint in the list
ManagedResourceTouchpoint mrtp =
(ManagedResourceTouchpoint)i.next();
// assign self as manager
mrtp.assignManager(this);
}
.
.
.
To look up its touchpoints, the method invokes a protected method within the AutonomicManagerTouchpointSupport class that simply performs an RMI naming lookup, using the URL passed as an argument, and returns the corresponding touchpoint instance from the RMI registry. The method then places this resolved touchpoint into a list contained in the AutonomicManagerTouchpointSupport class that tracks the touchpoints that the autonomic manager is responsible for. The method then loops through this list and invokes the assignManager() method of each resolved touchpoint, specifiying itself as the touchpoint's autonomic manager.
At this point, the implementation classes are now instantiated, published in the RMI registry, and can contact each other to invoke interaction style interfaces. Before the interaction styles can be used, though, the interfaces must be exposed and implemented, as described in the following sections.
In Release 1 of the Autonomic Computing Toolkit, only one interaction style interface is exposed: the sendEvent() interface that is used for the receive-notification interaction style, exposed by the AutonomicManagerTouchpointSupport class.
The receive-notification interaction style is exposed by autonomic managers. It is used to asynchronously send event data to an autonomic manager for processing. The sendEvent() operation, exposed by an autonomic manager, is used to implement this interaction style, as detailed in the following sections.
The sendEvent() operation allows a Common Base Event to be asynchronously sent to an autonomic manager for processing. This operation is exposed by an autonomic manager; therefore, a managed resource touchpoint uses its reference to its autonomic manager (set in the assignManager() invocation) to invoke the sendEvent() method. The ManagedResourceTouchpoint class provides a public method, called sendEventToManager(), to allow managed resources to send Common Base Events to their autonomic managers.
The following example shows code from the ManagedResourceTouchpoint class.
public boolean
sendEventToManager(ICommonBaseEvent cbe)
throws RemoteException
{
if (autoManager != null)
{
// invoke sendEvent to send the CBE to the autonomic manager
autoManager.sendEvent(cbe);
return true;
}
else
{
return false;
}
}
Notice that the Common Base Event is passed to the method as an ICommonBaseEvent interface object, as defined in the Hyades project (see Working with Common Base Events) and that the touchpoint invokes the sendEvent() method with a variable that contains a reference to its autonomic manager. This reference was set when the touchpoint's assignManager() method was invoked.
The default implementation of the sendEvent() method in the AutonomicManagerTouchpointSupport class returns a message that indicates that the method is not implemented. Custom implementations of this class might override the behavior of sendEvent() method to provide the correct behavior for this method. See A level 4 autonomic solution (adaptive): The Problem Determination scenario for an example.
The sendEvent() method uses a Common Base Event to send event information to an autonomic manager. There are two ways to generate Common Base Events using component provided in the Autonomic Computing Toolkit. The first method is to use the GLA to translate existing log file events into Common Base Events (see GLA-enabled touchpoints). The second method is to directly create Common Base Events using the classes included in the hlevents.jar file as described in Custom touchpoints.
Detailed description of Common Base Events can be found in Appendix A, Understanding Common Base Events Specification V1.0.1.
Custom autonomic solutions can extend the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes and provide their own implementations of the class methods. This is especially true for the interfaces that implement interaction styles.
Interaction style interfaces must be customized so that the methods translate the required autonomic functionality into the actions that must be performed on an underlying system for the required behavior to occur. For example, the default behavior of the sendEvent() method, used for the receive-notification interaction style, is to return a message indicating that the method is unimplemented. In order for this method to be handled properly in a custom implementation, this method must be overridden and updated to include actions that are meaningful to the autonomic manager for that implementation, such as updating the method to allow the autonomic manager to consume the Common Base Event.
See A level 4 autonomic solution (adaptive): The Problem Determination scenario for an example of this customization.
The Autonomic Computing Toolkit contains several sample implementations of the autonomic manager architecture concept. These autonomic manager implementations are intended to assist the developer in understanding the functions of an autonomic manager and demonstrate their use as part of an autonomic solution.
The autonomic manager implementations included in the Autonomic
Computing Toolkit demonstrate how varying levels of autonomic maturity can be
achieved. Table 1 shows the autonomic maturity levels for autonomic manager
implementations included in the Autonomic Computing Toolkit. See the
Autonomic Computing Toolkit User's Guide for a description of
autonomic maturity levels.
Table 1. Autonomic manager implementations and maturity levels
| Level 2 (managed) | Level 3 (predictive) | Level 4 (adaptive) |
|---|---|---|
| Log and Trace Analyzer tool | Solution install and deployment technologies | Autonomic Management Engine |
Level 2 autonomic managers enable autonomic solutions that collect information from disparate systems and display that information on a common console. IT staff can then manually take any necessary corrective action.
The Log and Trace Analyzer (LTA) tool, included in the Generic Log Adapter and Log and Trace bundle of the Autonomic Computing Toolkit, is an example of a level 2 autonomic manager. The LTA is an Eclipse-based tool that enables viewing, analysis, and correlation of log files generated by different products.
The LTA acts as an autonomic manager when configured to receive Common Base Events. It performs the monitor and analyze parts of the control loop. A managed resource touchpoint passes Common Base Events to the LTA, allowing the autonomic manager to monitor, analyze, and correlate this data, in some cases in real time. Real-time monitoring of situations occurring in the IT environment and analysis of those situations in real-time allows possible courses of action and problem resolutions to be generated and for IT personnel to execute them more quickly.
In this example, the autonomic manager and the touchpoint use a single interaction style, namely receive-notification. Common Base Events flow asynchronously from the touchpoint to the autonomic manager.
Level 3 autonomic managers add predictive aspects to an autonomic solution. A level 3 autonomic manager can make use of the analysis of available knowledge and recommend appropriate actions to administrators.
The Solution Installation and Deployment dependency checker and change manager, demonstrated in the Autonomic Computing Toolkit, are examples of a level 3 autonomic manager. The dependency checker acts as an autonomic manager, managing the solution installation process. During this process, the dependency checker looks ahead to determine whether or not dependencies, such as prerequisites and corequisites, are met prior to installing the software. The change manager knows how to deploy the software to a given target set (defined via touchpoints) coordinating the change management operations across hosting environment. This predictive aspect of this autonomic manager allows appropriate actions to be taken by IT personnel when dependencies are not met and increases the likelihood of a successful installation.
The Solution Installation and Deployment dependency checker and change manager interact with Solution Installation and Deployment touchpoints and run time to manage the software installation process and can use the interaction styles described earlier.
A level 4 autonomic manager is able to receive event data from a managed resource, correlate that data, decide on an appropriate corrective action, and instruct the managed resource to perform that action.
The Autonomic Management Engine provides level 4 autonomic manager functionality in the Autonomic Computing Toolkit. The key to understanding how AME functions as an autonomic manager is to understand the concept of a resource model.
For general information on resource model contents and creation, and for general information about AME, see the Autonomic Management Engine Developer's Guide included in the Autonomic Management Engine bundle of the Autonomic Computing Toolkit.
AME uses the receive-notification interaction style to consume Common Base Events. In programming terms, this means that AME has been provided with a sendEvent() interface (which can be invoked from a managed resource touchpoint) and that it has been modified to consume the Common Base Events that are passed in through this interface. The component within AME that is responsible for monitoring for incoming Common Base Events is called a resource model. Figure 4 shows a block diagram of a resource model and its interfaces.
Figure 4. Resource model and interfaces
As shown in Figure 4, the Common Base Events sent to the sendEvent() interface are actually placed in a data repository until they are consumed by the monitoring activities of AME.
Resource models actually consist of a bundle of objects that are used to describe the object being monitored, make decisions about its state, and perform actions based on event input. Resource model bundles are generated when they are exported from the Resource Model Builder (RMB), the tool used to build resource models. RMB is included in the Autonomic Computing Toolkit.
AME uses an information model standard called CIM-M12 to model resources to be monitored. Common Information Model (CIM) classes, represented by Model Object Format (MOF) files, define the format of data objects that are to be monitored. M12 Java providers invoke classes that assist in translating monitored objects into CIM classes.
When AME is running, it periodically checks its defined data sources for the presence of objects described by its defined MOF files. If any are found, AME uses the definitions in the MOF file to create instances of the CIM classes described by the MOF file. These instances are then passed to a special JavaScript(TM) function called VisitTree. Within this function, the CIM class instances can be parsed and used to determine information about a monitored system. If required, script files can then be invoked to perform corrective action on a managed system.
The CanonicalSituationMonitor resource model contains elements that allow AME to consume Common Base Events and act upon their contents. Two important objects in the CanonicalSituationMonitor resource model and the functions they provide are:
Each of these objects are described in more detail in the following sections. You can follow along by examining the resource model in RMB as described in Resource model basics.
The CSF class is accessed through the CIM Classes tab of the resource model. This CIM class definition tells AME where to look for Common Base Event instances and how to translate them to CSF class instances.
In the Class properties section of the CSF class, the Common Base Event is defined to be stored in three variables: an integer offset, a file name string, and a situation string. The integer offset defines a separation between each Common Base Event, the file name string defines a common header, and the situation string contains the remainder of the Common Base Event. Hence, all properties of a Common Base Event can be accessed by obtaining and parsing the situation string portion of a CSF class instance that represents a Common Base Event. More than one Common Base Event can exist in the data repository and a separate CSF class instance will be created for each one.
After the Common Base Events have been converted to CSF class instances, these instances are passed to VisitTree, the special JavaScript decision function described previously. To see this function, select the Source tab of the resource model and scroll down until you see the VisitTree function.
A special variable, SVC, is passed to VisitTree. It is essentially an array of the CIM class instances that have been detected in this monitoring cycle. In this case, these will all be CSF class instances representing Common Base Events.
The VisitTree function first determines how many instances of the CSF class are stored in the SVC array. It then enters a loop to process each instance. Within this loop, the situation string is obtained from the CSF class (representing the situation information of a Common Base Event) and then other local functions are used to extract the Common Base Event parameters. The rest of the loop contains the logic to examine these parameters and respond to their contents by invoking actions through the SVC.ShellCmd function call that drives corrective actions down to the managed resource.
Finally, the export facility of the RMB is invoked to generate the CanonicalSituationMonitor resource model bundle. This resource model is now ready for deployment on an AME system. See the AME 1.0 Developer's Guide, included in the Autonomic Management Engine bundle of the Autonomic Computing Toolkit, for information on deploying resource models on an AME system.
This guide details the resource model that has been created to allow AME to consume Common Base Events, the CanonicalSituationMonitor resource model. This resource model is in the Problem Determination scenario bundle. You can examine it using the RMB as follows:
Managed resource touchpoints represent the interface of a managed resource that can be invoked by an autonomic manager to perform sensor and effector operations. The Autonomic Computing Toolkit contains several sample managed resource touchpoint implementations. Unlike autonomic managers, managed resource touchpoints are not classified according to the autonomic maturity level they enable, because the maturity level of an autonomic solution is really determined by the actions of the autonomic manager. In all maturity levels, managed resource touchpoints perform essentially the same functions: they use the sensor and effector interaction styles to send information to, and receive information and commands from, an autonomic manager. In fact, one of the touchpoint implementations listed in the following sections, GLA-enabled touchpoints, is used with two different autonomic managers to implement autonomic solutions of two different maturity levels: a level 2 solution with the LTA and a level 4 solution with AME.
The managed resource touchpoint implementations provided in the Autonomic Computing Toolkit are as follows:
The GLA converts existing log messages of several formats to the Common Base Events format that can be consumed by various autonomic manager implementations.
A fully implemented GLA-enabled touchpoint consists of three parts:
These parts are described in more detail in the following sections.
A GLA adapter file is created using the Adapter Rule Editor tool, which is included in the Autonomic Computing Toolkit. The Adapter Rule Editor is an Eclipse-based tool that provides a development environment that allows you to specify which log file entries to translate to Common Base Events as well as how to perform the transformation. The Adapter Rule Editor also allows you to specify a Common Base Event output handler in the form of a GLA outputter, described in the following sections.
The output of the Adapter Rule Editor is a GLA adapter file that guides the transformation of log entries to Common Base Events and specifies how to handle them.
A GLA outputter class is invoked by the GLA run time when a Common Base Event has been generated from log file entries. This class must extend the org.eclipse.hyades.logging.adapter.impl.ProcessUnit class and must implement the org.eclipse.hyades.logging.adapter.IOutputter interface. This ensures that the methods necessary to handle Common Base Events are available for the GLA to invoke.
The method that receives the converted Common Base Events is called processEventItems() and it receives an array of Java objects, each object being a Common Base Event object. The Common Base Event objects are instances of the ICommonBaseEvent class from Hyades. The Common Base Event array is then passed to a custom handler within the outputter class for further processing.
An example of a custom outputter is the ReceiveNotificationOutputter class found in the Problem Determination scenario (see A custom outputter).
Because Solution Installation and Deployment technologies deal with installing software packages, touchpoints are associated with hosting environments. The Autonomic Computing Toolkit demonstrates operating system Solution Installation and Deployment touchpoints.
Operating system Solution Installation and Deployment touchpoints implement Solution Installation and Deployment technology-specific sensor and effector interfaces. These touchpoints provide a mechanism for obtaining machine-specific information, such as installed software and current hardware configuration. The operating system touchpoint is intended for use by the Solution Installation and Deployment dependency checker autonomic manager.
In addition to the example managed resource touchpoints introduced in previous sections, you can also create custom touchpoint implementations. Although these touchpoints can be created using completely new code, the most convenient way to implement them is by using the manageability interface implementation through extension of the ManagedResourceTouchpoint class. Using this class as a parent for a touchpoint implementation provides the touchpoint class with default behaviors required for managed resource touchpoints. These behaviors are:
You can then override any methods that require custom implementations to conform to the managed resource environment.
An example of developing a custom managed resource touchpoint can be found in Creating the managed resource touchpoint class.
Autonomic solutions combine an autonomic manager implementation with one or
more managed resource touchpoint implementations to achieve desired behaviors
in a system. The autonomic managers and managed resource touchpoints
included in the Autonomic Computing Toolkit work together in different
combinations as outlined in Table 2. The autonomic managers are listed in the top row and
the managed resource touchpoints are listed in the first column.
Table 2. Autonomic manager/touchpoint combinations in the Autonomic Computing Toolkit
| Autonomic manager touchpoint | LTA | Solution Installation and Deployment dependency checker | AME |
|---|---|---|---|
| GLA | Level 2 (managed) | -- | Level 4 (adaptive) |
| Solution Installation and Deployment touchpoints | -- | Level 3 (predictive) | -- |
The maturity level of the overall solution is determined by the capabilities of the autonomic manager that manages the solution. Some managed resource touchpoints, such as the GLA, can be used in multiple solutions.
The autonomic managers interact with their managed resource touchpoints using the sensor and effector interaction styles of the autonomic computing architecture, described earlier. Also, you can use certain tools to customize the behaviors of autonomic managers or managed resource touchpoints. The autonomic solutions presented in this chapter, labeled by their autonomic maturity level, list these interaction styles and customization tools for each solution.
With the exception of the LTA scenario, all of the autonomic solutions presented in this chapter already exist in the Autonomic Computing Toolkit as scenario bundles (see the Autonomic Computing Toolkit User's Guide for a description of these bundles). The customization sections within each solution explain the modifications that have already been performed for each solution, so you do not have to perform all of these steps to run the solution. For information on customizing the Autonomic Computing Toolkit technologies to create custom autonomic solutions, see Custom autonomic solutions.
This section describes the LTA.
A level 2 autonomic solution is demonstrated using the LTA acting as an autonomic manager in combination with the GLA acting as an enabler for a managed resource touchpoint. The LTA consumes log file information that the GLA has transformed into the Common Base Event data format for consistent analysis.
To customize a touchpoint to interact with the LTA, an adapter file must first be created. The CBELogOutputter included in the GLA provides the capability of passing Common Base Events to the autonomic manager using the following steps:
The LTA interacts with the touchpoint to provide problem determination capabilities. It monitors multiple heterogeneous product log files to isolate application problems occurring in a system.
The LTA must be configured to receive Common Base Events from the touchpoint. This is accomplished by identifying the machines and CBELogOutputter agent names you want to monitor, then attaching the LTA to the running GLA process.
To attach to a running GLA, perform the following steps:
You can also create your own symptom database to be used by the analysis engine provided with the LTA. See the online help of the LTA for details on how to create a symptom database.
For more information on GLA rules,, download A guide for enabling a generic log adapter rule for the Log and Trace Analyzer, available at the following Web site under Documents:
The LTA allows you to customize your autonomic manager functionality by letting you create your own analysis and correlation engine. Under the Eclipse framework, you can create your own analysis engine and correlation engine plug-ins.
By monitoring the different log files generated by the GLA, the LTA provides a managed level of autonomic maturity to your environment.
For more details, select Help -> Help Contents -> Log and Trace Analyzer.
This section describes the Solution Installation and Deployment scenarios.
To create this level 3 autonomic solution, the Solution Installation and Deployment dependency checker, acting as the autonomic manager, can be used with its touchpoints and run time provided in the Autonomic Computing Toolkit. Two variants of the same scenario that illustrate such a level 3 autonomic solution--each using a different installer (InstallShield for IBM Solution [ISSI] or InstallAnywhere by Zero G) --are detailed in separate documentation provided with the Autonomic Computing Toolkit. In this release, these two scenarios have been combined with a third scenario into a new book that is titled Solution Installation and Deployment Scenario Guide.
A Solution Installation and Deployment touchpoint is used in conjunction with the hosting environment in which the software will be installed. The Autonomic Computing Toolkit demonstrates operating system Solution Installation and Deployment touchpoints. The touchpoint must itself be installed, configured, and registered.
The Solution Installation and Deployment dependency checker and change manager interact with the solution module and the Solution Installation and Deployment touchpoints and run time to manage the software installation process. It evaluates checks and dependencies of the software that is to be installed as well as dependencies of currently installed software that might be affected by the new installation.
The interactions between the Solution Installation and Deployment dependency checker autonomic manager, and the Solution Installation and Deployment touchpoint is driven in large part by the data associated with the installation process, namely the solution modules and solution module descriptors. These data elements defined and describe the software package to be installed, including its structure, installable units, dependencies, checks, and properties. This information is used by the Solution Installation and Deployment autonomic manager to interact with the Solution Installation and Deployment touchpoints.
To customize the operation of the Solution installation and deployment packaging and installation, an IBM partner solution is required, such as Install Shield’s ISSI or ZeroG’s InstallAnywhere.
See the Solution Installation and Deployment Scenario Guide for information about running this solution.
This section describes the Problem Determination scenario.
The Problem Determination scenario included in the Autonomic Computing Toolkit represents a level 4 autonomic solution. This scenario combines AME, described in Autonomic managers, with a managed resource touchpoint enabled by the GLA, introduced in Managed resource touchpoints. The resulting autonomic solution is a self-healing system that uses an intelligent control loop to collect system information through Common Base Events, analyze them, plan appropriate responses, and then make necessary adjustments to resolve problems. The managed resource consists of WebSphere(R) Application Server executing a Web application that depends on data from an IBM DB2(R) Cloudscape(TM) database.
Two steps are required to customize the GLA touchpoint: defining log entries and defining a custom outputter. These operations are detailed in following sections. A custom adapter file, called PDContextScenario.adapter, contains these changes and can be found in the PDScenario/bin/Adapter subdirectory of the Problem Determination scenario bundle. This adapter file can be opened and examined using the Adapter Rule Editor included with the GLA and LTA bundle.
To alert the autonomic manager to certain error situations, certain error entries from the WebSphere Application Server and Cloudscape logs must be translated into Common Base Events and sent to the autonomic manager. To accomplish this translation, the Adapter Rule Editor has been used to monitor for and translate the following errors:
The definitions in the PDContextScenario.adapter file instruct the GLA how to translate these log entries into Common Base Events.
The custom outputter created for this scenario can be found in the mi_api.jar file. Its name is com.ibm.etools.logging.adapter.outputters.ReceiveNotificationOutputter. This class is defined as the outputter class in the PDContextScenario.adapter file. This means that when the GLA wants to output some Common Base Events that it has created, it will invoke this outputter class.
The ReceiveNotificationOutputter class implements the IOutputter interface of the GLA. This means that it implements a special method called processEventItems(Object[] msgs). The Object array passed to this method is actually an array of Common Base Event objects.
In the ReceiveNotificationOutputter class, this method invokes a private method that passes each Common Base Event to a customized implementation of the ManagedResourceTouchpoint class (see PDAutonomicManagerTouchpointSupport). The customized ManagedResourceTouchpoint class then invokes the sendEvent() method of its autonomic manager, thus using the receive-notification interaction style to asynchronously pass the Common Base Event. The ReceiveNotificationOutputter class has a reference to this customized class because it created an instance of it in its constructor. This instance of the ManagedResourceTouchpoint class serves as the managed resource touchpoint for the entire autonomic solution.
To a certain extent, the autonomic manager implementation for this scenario, AME, is already customized for this solution in that it already has a resource model defined that can consume Common Base Events (see Building a resource model). For this scenario, the decision tree in the resource model must also be modified to examine the Common Base Events that are received and develop and execute corrective actions if a problem is found.
The CanonicalSituationMonitor resource model described here is contained in the Problem Determination scenario bundle (in PDScenario_Home/bin/RM/subdirectory) and can be examined as described in A level 4 autonomic manager (adaptive).
The part of the resource model that requires modification is the VisitTree JavaScript method. This function can be found by selecting the Source tab for the CanonicalSituationMonitor resource model and scrolling until you see the start of the VisitTree method. This is the part of the resource model that receives the Common Base Events that have been sent to the Common Base Event data repository used by AME (see Building a resource model).
This particular scenario is looking for Common Base Events that have the following characteristics:
The above message IDs indicate the error situation of interest. These are the error messages in the WebSphere Application Server and Cloudscape logs that will be translated by the Generic Log Adapter into Common Base Events and sent to the AME Common Base Event data repository where AME retrieves them.
The general operation of the VisitTree code is:
This scenario uses the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes introduced in Manageability interface by extending these classes to inherit and customize the base behavior. The classes created are PDAutonomicManagerTouchpointSupport, which extends AutonomicManagerTouchpointSupport, and PDManagedResourceTouchpoint, which extends ManagedResourceTouchpoint. These child classes provide the necessary customized function to allow the customized AME and GLA-based touchpoint to work together to form the autonomic solution. The source code for the customized classes can be found in the pdmi_api.jar file within the Problem Determination scenario bundle of the Autonomic Computing Toolkit. It is recommended that you refer to these files for the following discussion.
This class overrides the parent class's start() and sendEvent() methods as outlined in the following sections.
The start() method is overridden to provide customized class instantiation and publication to the RMI registry. The method is reproduced here:
public void start() throws RemoteException
{
// publish this touchpoint support object
publish(this, "//localhost/PDAutonomicManagerTouchpointSupport");
// resolve all resource touchpoints
ManagedResourceTouchpoint resolvedTP =
resolveTouchpoint("//localhost/PDManagedResourceTouchpoint");
// add resolved touchpoint to touchpoint list
resourceTouchpoints.add(resolvedTP);
// assign self as manager for all resolved touchpoints
Iterator i = resourceTouchpoints.iterator();
while (i.hasNext()
)
{
// get the next touchpoint in the list
ManagedResourceTouchpoint mrtp =
(ManagedResourceTouchpoint)i.next();
// assign self as manager
mrtp.assignManager(this);
}
}
The differences between this method and the overridden method are the URL names used to publish the autonomic manager to the RMI registry and to find the published managed resource touchpoint. In this example, these URL names are fixed, although the start() method could invoke another method to obtain a list of URLs for the managed resource.
To provide support for the receive-notification interaction style in AME, the sendEvent() function is overridden. A portion of the overridden method from PDAutonomicManagerTouchpointSupport is reproduced here:
public void sendEvent(ICommonBaseEvent cbe) throws RemoteException
{
// convert the CBE to a string for writting
String cbeMessage = null;
if(cbe instanceof IExternalizableToXML){
cbeMessage = ((IExternalizableToXML)(cbe)).externalizeCanonicalXMLString();
}
else{
cbeMessage = cbe.toString();
}
.
.
.
// if necessary, create a file writer for the AME CBE log
if ( fw == null )
{
fw = new FileWriter(CBE_OUT_FILE, false);
}
.
.
.
// write the CBE to the log so that AME will find it
if ( fw != null )
{
fw.write(cbemessage);
fw.flush();
.
.
.
This method converts the Common Base Event received from the managed resource touchpoint to a string and writes that string to the Common Base Event data repository that the AME uses as its Common Base Event source (see Building a resource model). Hence, the overridden sendEvent() method ensures that Common Base Events are placed in the proper context for consumption by AME when the receive-notification interaction style is used.
This class overrides the parent class's start() method as outlined below.
The start() method is overridden to provide customized class instantiation and publication to the RMI registry. The method is reproduced here:
public void start() throws RemoteException
{
// publish this touchpoint in the RMI registry
publish(this, "//localhost/PDManagedResourceTouchpoint");
}
This method differs from the parent method in that it publishes a URL to RMI that is meaningful in this scenario. This URL is the name that the autonomic manager touchpoint support class uses to find this touchpoint. No other parent class methods need to be overridden for this scenario.
The Integrated Solutions Console provides a way to create a browser-based viewing console for the autonomic solution. Integrated Solutions Console is based on the IBM WebSphere Portal Server, and uses this portal capability to provide views into solutions. These views can be anything that can be displayed in a standard Web browser including HTML, JavaScript, and Java applets. Integrated Solutions Console organizes these views using a dynamic HTML-based navigation tree to allow you to move from view to view within a common, browser-based environment. This enables the consolidation of administration interfaces into one convenient place.
The Problem Determination scenario uses the Integrated Solutions Console to provide a view into the operations of the solution as well as a convenient way to start and stop the scenario. For information about this solution's use of the Integrated Solutions Console, see the Autonomic Computing Toolkit Problem Determination Log/Trace Scenario Guide, included in the Autonomic Computing Toolkit. For in-depth information on developing Integrated Solutions Console components, see the Integrated Solutions Console Developer Information Center, included in the Integrated Solutions Console bundle.
With these customizations in place, the level 4 autonomic solution acts as follows: The GLA translates log entries into Common Base Events and sends them to the AME, using the receive-notification interaction style. It uses the overridden sendEvent() method of the PDAutonomicManagerTouchpointSupport class to send the Common Base Events. Finally, AME uses its CanonicalSituationMonitor resource model to consume the Common Base Events, interpret their contents, and perform corrective actions, thus completing a full autonomic self-healing loop.
For in-depth information on running this autonomic solution, see the Problem Determination Log/Trace Scenario Guide included in the Documentation bundle of the Autonomic Computing Toolkit. That guide contains the information you need to install and configure the software for this scenario, run the scenario, and interpret the results.
In addition to the standard solutions that can be developed with the Autonomic Computing Toolkit, custom solutions are also possible. This chapter is a guide to using the technologies included in the Autonomic Computing Toolkit with an existing stand-alone product to create a custom autonomic solution.
Numerous autonomic solutions can be created using the Autonomic Computing Toolkit technologies. Previous chapters have already described the use of sample autonomic solutions, including the use of tools to customize certain aspects of the solution. It is also possible to use the manageability interface implementations to develop new, custom autonomic managers and managed resource touchpoints.
For this particular custom autonomic solution example, you will combine both of the methods mentioned above (modifying existing solutions and creating new ones). The autonomic manager implementation in this solution is AME, which is included in the Problem Determination scenario and was discussed earlier (see A level 4 autonomic manager (adaptive)). You will create a new custom managed resource touchpoint. This custom touchpoint will use the manageability interface implementation classes (see Manageability interface) to directly create and send Common Base Events to its autonomic manager.
This solution achieves a level 4 (adaptive) maturity level.
The example in this chapter uses a hypothetical application server. The following assumptions are made for this sample:
To set up a development environment for this solution, install the Problem Determination scenario bundle and then make a copy of its installation directory. This copy will contain AME, which you will customize, and the amtapi.jar and associated files, which you will use.
The following .jar files must be placed in your Java classpath for build time and run time:
These files can be found in the amtapi/lib subdirectory of the Problem Determination scenario.
You will also modify the CanonicalSituationMonitor resource model (see A level 4 autonomic manager (adaptive)). Rename and save this resource model.
A new Java package will be created for this solution called com.ibm.autonomic.sample.as. You will create all of the Java classes for this solution within subpackages of this package.
Perform the following steps to implement this custom autonomic solution:
These steps are detailed in the following sections.
The first step in creating an autonomic solution is to decide what aspect of a system might benefit from autonomic capabilities such as self-configuration, self-healing, self-optimization, and self-protection. This example solution illustrates a self-healing scenario that monitors the state of the application server's applications and attempts to address a problem that affects application execution.
The managed resource touchpoint class extends the ManagedResourceTouchpoint management interface implementation class, found in amtapi.jar. This allows the solution class to inherit the desired behaviors of the parent class and enables the addition of custom behavior for this particular solution.
For this solution, this class is named ASManagedResourceTouchpoint.java is created in its own package, com.ibm.autonomic.sample.as.resource. This is very similar to the technique used for the Problem Determination managed resource touchpoint class, PDManagedResourceTouchpoint.java.
The declaration for the ASManagedResourceTouchpoint.java class is shown below.
package com.ibm.autonomic.sample.as.resource; import java.rmi.RemoteException; import org.eclipse.hyades.logging.events.ICommonBaseEvent; import com.ibm.autonomic.resource.ManagedResourceTouchpoint; /** * ASManagedResourceTouchpoint * */ public class ASManagedResourceTouchpoint extends ResourceProcessControl
The managed resource touchpoint must be published to the RMI registry on the resource machine so that it can be found and used by an autonomic manager. Because you should publish to a different URL than the one that is specified in the parent class's start() method, override that method as follows:
public void start() throws RemoteException
{
publish(this, "//localhost/ASResourceTouchPoint");
}
To actually publish itself, the ASManagedResourceTouchpoint class invokes the publish method inherited from its parent class and passes a pointer to itself (this) and the URL for this touchpoint in the RMI registry (//localhost/ASResourceTouchPoint).
Earlier sections described how to generate Common Base Events using the GLA to convert existing log file entries to Common Base Events. In this solution, you will generate Common Base Events directly within your managed resource and use the custom touchpoint to send these events to the autonomic manager.
To generate a Common Base Event when an error condition occurs, the ASManagedResourceTouchpoint class must be integrated with the application server. This is done in two ways. First, the ASManagedResourceTouchpoint class needs to become a part of the application server's code base so that it is instantiated when the application server starts up. Second, the error-reporting facilities of the application server need to be modified to invoke methods in the ASManagedResourceTouchpoint class when errors occur so that the touchpoint knows to use the error information to generate the Common Base Event and send it to the autonomic manager.
For this example, assume that the application server has an error handler that gets invoked when applications are slowing down due to lack of database connections. This handler must be modified to invoke a method in the ASManagedResourceTouchpoint class that will generate a Common Base Event to represent the error condition. The code for this method in the ASManagedResourceTouchpoint class is as follows:
public void reportDBPoolProblemAsCBE()
{
// a db pool problem has occurred...we must generate a Common Base Event
// representing this problem and send it to the autonomic manager
try
{
// instantiate an instance of the Common Base Event factory
ISimpleEventFactory sefi = SimpleEventFactoryImpl.getInstance();
// create the Common Base Event
ICommonBaseEvent cbe = sefi.createCommonBaseEvent();
// set the creation time
cbe.setCreationTime(System.currentTimeMillis());
// set the Common Base Event version to 1.0.1
cbe.setPreferredVersion(ICommonBaseEvent.VERSION_1_0_1);
// set the properties required for a situation 3-tuple; i.e. the component reporting the
// situation, the component affected by the situation, and the situation itself
// set the source component; i.e. the affected component...this is the application server...
// by setting this and not the reporting component, the Common Base Event will assume
// that this is also the reporting component
// create a new instance of a Source Component:
IComponentIdentification sourceComponentId = sefi.createComponentIdentification();
sourceComponentId.setLocation("127.0.0.1");
sourceComponentId.setLocationType("IPV4");
sourceComponentId.setComponent("Example Application Server");
sourceComponentId.setSubComponent("Application Server DB Connection Pool");
sourceComponentId.setComponentIdType("Application");
sourceComponentId.setComponentType("Application Server");
// now set the source component in the Common Base Event
cbe.setSourceComponentId(sourceComponentId);
// set the situation...because we're dealing with a problem with the db connection pool size,
// we'll categorize this as a connection situation...first create a new instance of a connection
// situation
IConnectSituation connSituation = sefi.createConnectSituation();
connSituation.setSuccessDisposition("UNSUCCESSFUL");
connSituation.setSituationDisposition("AVAILABLE");
// create a new instance of a situation
ISituation situation = sefi.createSituation();
situation.setCategoryName("ConnectSituation");
situation.setSituationType(connSituation);
// set the situation in the Common Base Event
cbe.setSituation(situation);
// set the error message id...this is what we're looking for in the Resource Model in order
// to invoke a corrective action (see section 6.1.7)...the message id is set using a message
// data element
IMsgDataElement mde = sefi.createMsgDataElement();
// set the message id and message id type
mde.setMsgId("AS005E");
mde.setMsgIdType("AppServer");
// add the message data element to the cbe
cbe.setMsgDataElement(mde);
// invoke the touchpoint's method that sends a Common Base Event to the autonomic
// manager using the sendEvent() method...this uses the receive-notification interaction
// style
sendEventToManager(cbe);
}
catch (Throwable th)
{
// problem creating the Common Base Event
System.out.println("Could not create Common Base Event: " + th);
}
}
The last method invoked is sendEventToManager(). This is actually invoking the parent method, which sends the Common Base Event to the touchpoint's autonomic manager using the sendEvent() method of the manageability interface, thus using the receive-notification interaction style to asynchronously send event data.
The Common Base Event is being created and sent directly rather than using the GLA to translate log entries. While the GLA is very convenient for generating Common Base Events for existing log files, there is some degradation of performance by using this method and the direct generation method demonstrated here is the preferred method of event generation.
For in-depth information on the Common Base Event objects and properties used in the method above, see Appendix A, Understanding Common Base Events Specification V1.0.1.
The manager touchpoint support class extends the AutonomicManagerTouchpointSupport management interface implementation class, found in amtapi.jar.
For this solution, this class is named ASAutonomicManagerTouchpointSupport.java and is create in its own package, com.ibm.autonomic.sample.as.manager. A very similar technique is used for the Problem Determination manager touchpoint support class, PDAutonomicManagerTouchpointSupport.java.
The declaration for the ASAutonomicManagerTouchpointSupport.java class is shown in the following example:
package com.ibm.autonomic.sample.as.resource; import java.rmi.RemoteException; import org.eclipse.hyades.logging.events.ICommonBaseEvent; import org.eclipse.hyades.logging.events.IComponentIdentification; import org.eclipse.hyades.logging.events.IConnectSituation; import org.eclipse.hyades.logging.events.IMsgDataElement; import org.eclipse.hyades.logging.events.ISimpleEventFactory; import org.eclipse.hyades.logging.events.ISituation; import org.eclipse.hyades.logging.events.SimpleEventFactoryImpl; import com.ibm.autonomic.resource.ManagedResourceTouchpoint; /** * ASManagedResourceTouchpoint * */ public class ASManagedResourceTouchpoint extends ResourceProcessControl
The manager touchpoint support class instance must be published to the RMI registry so that its managed resource touchpoints that it is managing can address the manager. You should publish the manager touchpoint support class using a different URL than the one specified in the parent class, so override the start() method of the parent class while maintaining its behavior that finds the autonomic manager's managed resource touchpoints and assigns itself as their manager.
The new start() method in the ASAutonomicManagerTouchpointSupport class is as follows:
public void start()
{
try
{
// publish this touchpoint support object
publish(this, "//localhost/ASAutonomicManagerTouchpointSupport");
// resolve all resource touchpoints
IManagedResourceTouchpoint resolvedTP =
resolveTouchpoint("//localhost/ASManagedResourceTouchpoint");
// add resolved touchpoint to touchpoint list
resourceTouchpoints.add(resolvedTP);
// assign self as manager for all resolved touchpoints
Iterator i = resourceTouchpoints.iterator();
while (i.hasNext())
{
// get the next touchpoint in the list
IManagedResourceTouchpoint mrtp = (IManagedResourceTouchpoint)i.next();
// assign self as manager
mrtp.assignManager(this);
}
}
catch (Throwable th)
{
System.out.println("Error connecting to managed resources:");
th.printStackTrace();
}
}
The start() method invokes the resolveTouchpoint() method of the parent class, passing the name of the managed resource touchpoint that was published in the start() method of the ASManagedResourceTouchpoint class. The autonomic manager's new start() method also publishes itself to the RMI registry and then assigns itself as the manager of the managed resource touchpoint after the touchpoint is resolved.
The class manager tracks its managed resource touchpoints using a list that is declared in the parent class. Hence, even though there is only one managed resource in this particular solution, the autonomic manager could manage multiple managed resource touchpoints.
When the autonomic manager's start() method resolves a managed resource touchpoint found in the RMI registry, it invokes that touchpoint's assignManager() method, specifying itself as the touchpoint's autonomic manager.
Because AME cannot start auxiliary programs during its own startup process, its touchpoint support must be started as a separate process. Hence, in this scenario, the ASAutonomicManagerTouchpointSupport class must be invoked from the command line after AME is started. Therefore, a main() method must be added to the class to instantiate it and invoke its start() method as follows:
public static void main(String[] args) throws Exception
{
// create an instance and start it up
ASAutonomicManagerTouchpointSupport amts = new
ASAutonomicManagerTouchpointSupport();
amts.start();
}
The main() method creates an instance of the ASAutonomicManagerTouchpointSupport class and invokes its start() method, which will cause it to publish itself to the RMI registry.
In this solution, Common Base Events should be written to a log file where AME can retrieve them. To accomplish this, the sendEvent() method of the ASAutonomicManagerTouchpointSupport class must be overriden. The parent class implementation is just a place holder that throws an exception indicating that the method must be implemented by child classes.
AME expects to find Common Base Events in a log file called CBEOut.log, so this is where the sendEvent() method writes them, as follows:
public void sendEvent(ICommonBaseEvent cbe) throws RemoteException
{
// convert CBE to string for writing to a file
String cbeMessage = cbe.toString();
// write the CBE to a the AME datastore file.
try
{
if (fw == null)
{
fw = new FileWriter("CBEOut.log", false);
}
}
catch (Exception e)
{
e.printStackTrace();
throw new RemoteException("Cannot create CBEOut.log file : " + e.toString());
}
try
{
if (fw != null)
{
fw.write(cbeMessage);
fw.flush();
}
else
System.out.println("CBE out file is null");
}
catch (Exception e)
{
e.printStackTrace();
throw new RemoteException("Cannot write CBE message : " + e.toString());
}
}
The method first converts the Common Base Event to a string, because AME expects this format. The method then opens the CBEOut.log file and writes the converted Common Base Event string.
Because the CanonicalSituationMonitor resource model is already configured to consume Common Base Events, you do not have to modify that aspect of its behavior. The Common Base Events that the modified ASAutonomicManagerTouchpointSupport class writes to the CBEOut.log file can be read by AME and converted to a CSF class instance, which in turn is passed to the VisitTree method, as described in Building a resource model.
The VisitTree code, however must be modified to look for Common Base Events from your application server, determine whether or not they indicate an error condition, and then initiate any required corrective actions. You also need to modify some of the initialization script to set up some of the variables used by VisitTree. These modifications are outlined in the following sections.
Some variables need to be defined for the VisitTree method as follows:
// TRACE Constants to be used by Svc.Trace() calls var TRACE_ERROR = 0; var TRACE_FINE = 2; var TRACE_FINER = 3; var TRACE_FINEST = 4; // This variable can be used in your Svc.Trace calls to make it easier to // search through the log file and find calls made by your resource models. var TRACE_SOURCE = "RM TRACE: "; var str_MY_APPSVR = "MyApplicationServer"; //The WAS MSGID which indicates db pool problem var str_DB_POOL_ERR = "AS005E"; var dbPoolSizeScript = "";
Remove the remaining variable declarations at the beginning of the resource model.
The init() function must be modified to correctly set variables as follows:
function Init(Svc)
{
interpType = Svc.GetInterp();
//Use the interp to set the which file would be executed for recovery
if (interpType == "w32-ix86")
{
dbPoolSizeScript = "IncreaseDBPoolSize.bat";
}
else
{
dbPoolSizeScript = "./increasedbpoolsize.sh";
}
Svc.AssociateParameterToClass("parmLogName", "CSF");
return (0);
}
The script that is invoked to increase the database connection pool size is set based on the operating system platform.
Modify the VisitTree method as follows:
function VisitTree(Svc)
{
var numOfInstances;
var idx;
// Process each situation written to the error log during this cycle.
numberOfInstances = Svc.GetNumOfInst("CSF");
for (idx = 0; idx < numberOfInstances; idx++)
{
// Note: The entire CBE is bundled up into one property in the CIM
// class (i.e., situation)...get that property for parsing
var str_situation = Svc.GetStrProperty("CSF", idx, "situation");
// Extract the properties that are required for the analysis.
var str_msgId = getTagValue(str_situation, "<msgId>");
var str_sourceComponentId_component = getParmValue(str_situation,
"component");
// We are interested only in the situations from our application
// server
if (str_sourceComponentId_component.indexOf(str_MY_APPSVR) > 0)
{
// If it's the error we're looking for, invoke the db pool
// size script to fix the problem
if (str_msgId == str_DB_POOL_ERR)
{
shellRc = Svc.ShellCmd(startScript);
}
}
}
return (0);
}
The function first determines how many Common Base Events it has to work with. It then uses a loop to process each one. Within this loop, the situation string of the CSF class is extracted (this represents all of the Common Base Event data; see CSF class). Next, the Common Base Event data of interest is extracted, namely the reporting component and the message ID. If the reporting component matches your application server and the message ID matches the database connection pool size error ID, then the script to correct the problem is invoked. This causes the application server's database connection pool size to be increased, thus completing the self-healing autonomic solution.
After making the changes to the JavaScript in the resource model, save it and export it using RMB's export facilities.
To build the solution, perform the following steps:
For more information on building a sample, see the AME 1.0 Developer's Guide.
To run the sample, the .jar files specified in Building the sample must be in the classpath, along with any .jar files and classes necessary to run AME and the application server. The order in which the various solution components are started is important because the resource touchpoint must be published before the autonomic manager starts. Also, the RMI registry must be started before any touchpoints can be published. Therefore, the start order must be as follows:
The running autonomic manager will now monitor incoming Common Base Events that indicate the AS005E error condition and react to them by effecting a corrective action on the application server. To test the solution, you must cause the error condition in the application server. The easiest way to do this is to set the application server database connection pool size to 1, then use a tool to generate a large demand on an application running on the application server that uses database connections. This should cause an overload of the connection pool, thus generating the AS005E error condition and invoking the corrective actions.
Another possibility is to create a script that artificially generates the error condition within the application server (for example, by invoking the error handler during the application server's post-startup processing). This should in turn generate the Common Base Event indicating the error situation and cause the expected corrective actions.
This appendix describes the Common Base Event and supporting technologies that define the structure of an event in a consistent and a common format. The purpose of the Common Base Event is to facilitate the effective intercommunication among disparate enterprise components that support logging, management, problem determination, autonomic computing, and e-business functions in an enterprise. This appendix specifies a baseline that encapsulates properties common to a wide variety of events, including business, autonomic, management, tracing, and logging type events. The format of the event is expressed as an XML document using UTF-8 or UTF-16 encoding.
This appendix is prescriptive about the format and content of the data that is passed or retrieved from a component. However, it is not prescriptive about the ways in which individual applications are to store their data locally. Therefore, the application requirement is only to be able to generate or render events in Common Base Event data format, not necessarily to store them in that format. The goal of this effort is to ensure the accuracy, improve the detail and standardize the format of events to assist in designing robust, manageable and deterministic systems.
A small event can change things far beyond the seeming initial circumstance. Nowhere is this more true than in today's complex world of e-business where multitudes of interconnected systems must work together to perform many of the simple housekeeping activities that are necessary to keep a computing system healthy. Clearly, in this world, small incidents can have wide-reaching implications and few things are as small, yet pervasive, in a computing infrastructure as an event. The event, which encapsulates message data sent as the result of an occurrence of a situation, represents the very foundation on which these complex systems communicate. Events exchanged between and among applications in complex information technology systems represent the very nervous system that allows these various facets of the system to interoperate, communicate and coordinate their activities. Fundamental aspects of enterprise management and e-business communications, such as performance monitoring, security and reliability, as well as fundamental portions of e-business communications, such as order tracking, are grounded in the viability and fidelity of these events. Quality event data leads to accurate, deterministic and proper management of the enterprise. Poor fidelity can lead to misguided, potentially harmful results, or even results that are fatal to the system. Even simple things such as the formatting of the date and time specified within an event can render the remaining data in the event useless the format used by the sender is not understood by the receiver beforehand. Clearly, efforts to ensure the accuracy, improve the detail and standardize the format of these fundamental enterprise building blocks is an imperative towards designing robust, manageable and deterministic systems. Hence, the Common Base Event is defined as a new standard for events to be used by enterprise management and business applications.
The Common Base Event described here lends itself easily to several types of events, in particular: logging, tracing, management, and business events. In all of these cases there is a significant need for the data elements and the format of those elements to be consistent, because all of these events need to be correlated with each other. Using log files, or events published to subscribers, most IBM and non-IBM products generate data whose interpretation requires the availability of contextual information. Yet, this context is frequently maintained only in the minds of developers and analysts who are intimately familiar with the application that generates the event. This lack of context can lead to hazardous situations when other applications that are responsible for handling the event attempt to interpret it, or when the event is used for system management or problem determination purposes. Consider again the basic problem of parsing time stamps. Format and granularity (for example, are the units milliseconds or microseconds?) both present needless obfuscation for the application that receives the time-stamped event. A more general problem is the lack of consistency in the information that is presented. For example:
Obviously, the current lack of standardization creates considerable difficulty for automated situation handling. Complexity increases further when the problem occurs in a solution that is composed of multiple components. Without a standard, data stored in logs or published as events are of little value to autonomic management or business systems that rely on the completeness and accuracy of data to determine an appropriate course of action to take in response to the event. The Common Base Event definition alleviates this problem by ensuring completeness of the data by providing properties to publish the following information:
All properties defined in the Common Base Event model apply to one of these three broad categories, hereafter referred to as 3-tuple. In addition, the location of the reporter and source components is also considered. The affected component might not reside in the same physical machine as the component that reports it. This broader scope of information encapsulates enough data so that events can be exchanged and interpreted in a deterministic and appropriate manner across multiple management systems that consume the events without losing fidelity due to serial hops among the multiple management systems.
Table 3 provides a summary of the Common Base Event properties. The entries in the table represent the data that is collected for the 3-tuple. The reporterComponentId and sourceComponentId table entries define the reporter and the affected component IDs respectively. The remaining fields in the table comprise the "situation" data.
The following sections describe the conventions used in this model.
The key words MUST , MUST NOT, REQUIRED, SHALL. SHALL NOT, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL (shown in uppercase in the following sections) are to be interpreted as they are described in RFC-2119. 1
Formatted data is always in human-readable form. All formatted data and string values MUST be encoded as UTF-8 or UTF-16 strings.
The Common Base Event only supports the following subset of XML schema data types and the array variation of these types. Description of these data types can be found in the XML Schema specification. 2 The data types are XML schema signed data types as follows:
The maximum string length MUST NOT exceed 1024 characters. If a longer string is needed then a hexBinary type MAY be used.
Based on empirical data concerning known consumers and constraints placed on the processing and storage of events, field lengths have been specified to ensure the broadest possible accept