Create GLA components using Release 2 of the Autonomic ......Autonomic Computing Toolkit Skill...

Create GLA components using Release 2 of theAutonomic Computing ToolkitSkill Level: Introductory

Eric GiguereAuthor

14 Dec 2004

This tutorial explains how to create components for the Generic Log Adapter (GLA)for Autonomic Computing by creating a simple outputter as an example. Outputtersare GLA components that externalize the Common Base Event (CBE) instancesgenerated by the GLA. The tutorial describes the GLA architecture, how componentswork, and how to configure the GLA to use specific components. Finally, the tutorialdemonstrates how to write and test a very simple custom outputter.

Section 1. Before you start

About this tutorial

The Generic Log Adapter (GLA) lets you to process log files and transform theircontents into events that follow the Common Base Event (CBE) format. Internally,the GLA consists of a chain of components that have different roles in thetransformation process. The last member in the chain is the outputter, thecomponent that externalizes a CBE instance generated by the GLA. Typicaldestinations for CBE instances include the console, a file, or an autonomiccomputing log agent, and the GLA ships with outputters for each of thesedestinations. However, your specific needs might not be addressed by the standardGLA outputters. This tutorial shows you how to write custom outputters. By followingthe same general pattern you can write any type of GLA component.

The tutorial describes the various parts of the GLA and how it processes log files inorder to generate and output CBE instances, and examines how components arestructured and configured. It also describes how to build the simplest outputter, anoutputter that prints event information to the console, by building an Eclipse plug-in,and how to test the outputter from within the Eclipse environment.

Create GLA components using Release 2 of the Autonomic Computing Toolkit© Copyright IBM Corporation 1994, 2008. All rights reserved. of 30

http://www.ibm.com/legal/copytrade.shtml

Prerequisites

To take this tutorial, you should have a general understanding of autonomiccomputing technology and moderate experience with the Java programminglanguage. You must download and install the GLA and all its required componentsas described in the next section. The Eclipse installation included with the GLA isused as the development environment.

This tutorial is based on version 3.0 of the Generic Log Adapter, which can bedownloaded from the Autonomic Computing Toolkit(http://www.ibm.com/developerworks/autonomic/probdet1.html#gla1). However,before downloading the GLA, you must install version 1.4 of the Java Runtimeenvironment (JRE). Download the JRE from the Sun Microsystems Web site at:http://java.sun.com/products/archive/j2se/1.4.1_07/index.html.

After the JRE is installed, download the Generic Log Adapter and Log TraceAnalyzer bundle from the Autonomic Computing Toolkit. A version of Eclipse isinstalled with the GLA; you can find it in theAutonomicComputingToolkit\GLA\dev\eclipse directory. Run the ac.bat (Windows) orac.sh (Unix/Linux) files to start Eclipse before proceeding with this tutorial. Allreferences to Eclipse in this tutorial refer specifically to the Eclipse bundled with theGLA.

Section 2. GLA architecture

Purpose of the GLA

Autonomic computing technology depends on being able to monitor the state ofeach part of the overall system in order to respond to changes as they occur.Changes in state are described using the Common Base Event (CBE) format, whichenables communication between various parts of an autonomic computing solution.

Most software needing monitoring does not produce events in the CBE format; thevast majority update a log file whenever a change occurs. After a system crash,system administrators refer to these log files to see what went wrong. Sifting througha log file can be a long process depending on how often the software updates itslogs and how verbose it is with those updates.

Post-crash analysis is undesirable in an autonomic computing system. Instead, thesystem must detect and respond to problems as soon as they occur. Log files mustbe read shortly after they are updated and the changes interpreted and transformedinto events to feed to the rest of the autonomic computing system.

developerWorks® ibm.com/developerWorks

Create GLA components using Release 2 of the Autonomic Computing Toolkit of 30 © Copyright IBM Corporation 1994, 2008. All rights reserved.

http://www.ibm.com/developerworks/autonomic/probdet1.html#gla1

http://java.sun.com/products/archive/j2se/1.4.1_07/index.html


The Autonomic Computing Toolkit monitors the system using the Generic LogAdapter (GLA), a server application written in the Java language.

The GLA component chain

Each log file processed by the GLA is referred to as a context. Each context isassociated with a chain of components representing the different stages used by theGLA to transform log file entries into common base events. The necessarycomponents can vary depending on the project, but a typical component ordering isas follows:

• The sensor reads lines from the log file.

• The extractor determines which lines or line fragments correspond to asingle "message" describing a change in state.

• The parser maps the message into a set of CBE attributes.

• The formatter builds an instance of a Common Base Event object basedon the attributes.

• The outputter stores or sends the CBE object to its final destination,typically a logging agent within the autonomic computing system.

Currently, only one instance of each component type is associated with a givencontext, although, it is possible to use two or more outputters with a single context.

Figure 1 shows how the components fit together:

Figure 1. GLA components

ibm.com/developerWorks developerWorks®



The GLA includes at least one implementation of each component. Two extractorsare provided; for example, one extractor uses regular expressions (to processcomplex log files), and one extractor uses simple string comparisons (to processsimple log files more quickly). The adapter configuration controls which specificcomponent implementations are used by a given context.

The components included with the GLA should be sufficient for most monitoringpurposes. If not, custom components can be created to meet your specificrequirements, as shown later in this tutorial.

Connecting to CVS repository: Selecting CVS Exploring

To create a custom component, you first need to connect to the CVS repositorycontaining the GLA's source code. The repository is easily accessed from withinEclipse by using the CVS perspective. Follow these steps to obtain the GLA sourcecode:

1. Start Eclipse and select Window from the menu bar.

2. Select Open Perspective > CVS Repository Exploring. If CVSRepository Exploring is not listed, select Other... and then choose CVS




Exploring, as shown in Figure 2.

Figure 2. CVS Exploring

Connecting to CVS repository: Selecting repository location

3. Click the right mouse button in the CVS Repositories perspective andselect Repository Location..., as shown in Figure 3.Figure 3. Context Menu in the CVS Repositories perspective




Connecting to CVS repository: Adding CVS repository

4. The Add CVS Repository window is displayed, as shown in Figure 4.Enter dev.eclipse.org in the Host field, /home/tools in theRepository path field, and anonymous in the User field. Make sure theConnection type is set to pserver and select Finish. You are nowconnected to the Eclipse CVS repository.Figure 4. Add CVS Repository dialog




Connecting to CVS repository: Selecting CVS Repository view

5. Open the repository's tree view, as shown in Figure 5.Figure 5. Repository tree view




Connecting to CVS repository: Expanding the HEAD node

6. Expand the HEAD node and navigate to theorg.eclipse.hyades.logging.adapter node. Open the node's context menuand select Add to Branch List..., as shown in Figure 6.Figure 6. Add to Branch List... item




Connecting to CVS repository: Selecting CVS Exploring

1. Enter the branch name Hyades_v3_0_1 in the Enter Branch Tag dialogto select version 3.0.1 of the logging package. This is the version that theGLA is currently built with.

2. After closing the dialog, close the HEAD node and expand the Branchesnode and the two nodes immediately under it as shown in Figure 7.Figure 7. The Branches node




The source code is found in the src node. Open all the subfolders in this node untilyou reach the adapter node. You'll need to refer to this code as you program.

Section 3. Component design

Component basics

At run time, a component is an instance of a Java class. All GLA componentsimplement the IComponent and IProcessUnit interfaces defined in theorg.eclipse.hyades.logging.adapter package. These two interfacesprovide the core functionality available to every component:

• IComponent defines the methods for managing component propertiesand for starting and stopping the component.

• IProcessUnit defines the component's processing methods.

As well, each component type defines an interface that extends the IProcessUnitinterface. Therefore, the interfaces ISensor, IExtractor, IParser,




IFormatter, and IOutputter define methods specific to the operation of aparticular component type. Each component must implement the proper interface forits type.

Default implementations for most of these interfaces are also provided in theorg.eclipse.hyades.logging.adapter.impl package, which include theComponent, ProcessUnit, Sensor, and Extractor classes. ProcessUnit alsoserves as the default implementation for the three other interfaces, IParser,IFormatter, and IOutputter, because they don't define any additional methods.

How outputters work

All components follow the same basic model at run time. Therefore, this tutoriallooks at outputters specifically. Outputters are the last components in the GLAcomponent chain, invoked after the formatter has generated a sequence of CBEinstances. Each outputter class implements the IOutputter interface andoverrides the processEventItems method, defined as follows:

public Object[] processEventItems( Object[] msgs );

As a generic method defined in IProcessUnit, processEventItems is declaredto take and return arrays of java.lang.Object. An outputter, though, is actuallypassed an array of objects that implement the core CBE interface,ICommonBaseEvent. These are the events generated by the formatter. Afterexternalizing these events, the outputter returns the array for processing by the nextoutputter in the component chain, if any.

What the outputter does in its processEventItems method is entirely up to it, ofcourse. It might write the events to a file, create a series of Java Message Service(JMS) messages from them, or whatever else is required. It can even add, remove,or modify the events that it passes back for consumption by subsequent outputters.

Other methods of the IComponent and IProcessUnit interfaces can beoverridden as necessary. For example, override the update method to update thecomponent's internal state whenever its configuration information changes.

Component configuration

All components in the GLA component chain are configured using an XML file. Thisadapter configuration file can be created manually or by using a new Eclipse plug-incalled the Configuration File Editor. You'll use the Configuration File Editor later inthis tutorial, so for now let's discuss the format of the adapter configuration file itself.

Sample configurations are included with the GLA, along with sample logs that canbe processed by those configurations. The sample logs are ideal for testing GLAconfigurations. The samples are found in theAutonomicComputingToolkit\GLA\config directory. Thereare a number of




subdirectories in this directory, one for each software product that is supportedout-of-the-box by the GLA. For example, under the WAS directory you'll find samplelogs and configurations for use with the WebSphere Application Server.

Using a text editor, view the WAS\trace\5.0\static.adapter file, a very simple adapterconfiguration file for tracing WebSphere Application Server 5.0 log files. A slightlysimplified version of this file is shown here:

<?xml version="1.0" encoding="ASCII"?><adapter:Adapterxmlns:adapter="http://www.eclipse.org/hyades/schema/Adapter.xsd"xmlns:cc="http://www.eclipse.org/hyades/schema/ComponentConfiguration.xsd"xmlns:hga="http://www.eclipse.org/hyades/schema/Context.xsd"xmlns:op="http://www.eclipse.org/hyades/schema/Outputter.xsd"xmlns:sensor="http://www.eclipse.org/hyades/schema/Sensor.xsd"><hga:Contexts>

<hga:Contextdescription="Context Instance for the current component"executableClass="org.eclipse.hyades.logging.adapter.impl.BasicContext"loggingLevel="60"name="Basic Context Implementation"role="context"uniqueID="StaticParserContextID1"><hga:Component

description="Static Parser Sensor"executableClass=

"org.eclipse.hyades.logging.adapter.config.sensors.StaticParserSensor"loggingLevel="60"name="Static Parser Sensor"role="sensor"uniqueID="sensorID1"/>

<hga:Componentdescription="Static Parser Outputter"executableClass="org.eclipse.hyades.logging.adapter.config.outputters.StaticParserOutputter"

loggingLevel="60"name="Static Parser Outputter"role="outputter"uniqueID="AdapterStaticParserOutputterID1"/>

</hga:Context></hga:Contexts>

<cc:Configurationdescription="The component level configurations for this Adapter"uniqueID="StaticParserConfigurationID1"><cc:ContextInstancecontinuousOperation="false"description="Context Instance for the current component"maximumIdleTime="20000"pauseInterval="10"uniqueID="StaticParserContextID1"><cc:Sensor

description="A static parser sensor"maximumBlocking="30"type="StaticParserSensor"uniqueID="sensorID1"><sensor:StaticParserSensordirectory=""fileName=""parserClassName="com.ibm.etools.logging.parsers.WASV5TraceLogParser"><sensor:SensorProperty

propertyName="local_log"propertyValue="true"/>

<sensor:SensorPropertypropertyName="country"propertyValue="United States"/>

</sensor:StaticParserSensor></cc:Sensor><cc:Outputter

description="Static Parser Outputter"type="LoggingAgentOutputter"




uniqueID="AdapterStaticParserOutputterID1"><op:LoggingAgentOutputterTypeagentName="IBM WebSphere Application Server V5.0 trace log files"waitUntilLoggingTime="15000">

</op:LoggingAgentOutputterType></cc:Outputter>

</cc:ContextInstance></cc:Configuration>

</adapter:Adapter>

The file defines a single GLA context consisting of two components, a sensor and anoutputter, and a single context instance. A context instance is a set of parameters forinitializing a context. The parameters are described in both the Eclipse online helpand the gla_getting_started.pdf document, which you'll find in the docs directory ofyour GLA installation. Configuration is much simpler and more intuitive when youuse the Configuration File Editor, though, because the editor knows how to edit theindividual parameters.

At run time, a component can access its configuration information using methods inthe IComponent interface.

Section 4. A simple outputter

Starting small

Now, let's write a very simple outputter, an outputter that prints the events it receivesto the console. This outputter will be virtually identical to the CBEstdoutOutputterincluded with the GLA, which you'll find in the source repository in theorg.eclipse.hyades.logging.adapter.outputters package. This versionis slightly different in that it will write the events to the standard error stream, not thestandard output stream.

Creating the project: Create new project

The first step is to create an Eclipse project for the outputter.

1. Select File > New > Project... to open the New Project wizard as shownin Figure 8. The outputter is going to be created as an Eclipse plug-in sothat you can load it later into the GLA test environment. Therefore,instead of creating a Java project, select Plug-in Development in theproject tree of the wizard and Plug-in Project leaf:Figure 8. The New Project wizard




2. Select Next.

Creating the project: Set project name

3. Set StderrOutputter as the plug-in project name and select Nextagain.Figure 9. The New Plug-in Project window




Creating the project: Deselect items

4. Deselect Generate a Java class that controls the plug-ins life cycle.Figure 10. Defaults for the Plug-in project




5. Select Finish.

The plug-in development perspective

Eclipse generates the project and ask if you want to switch to the plug-indevelopment perspective. Press Yes. Your new project appears in the packageexplorer as shown in Figure 11:

Figure 11. The package explorer




The dependency view

Double-click the plugin.xml file at the bottom of the project. In the plug-in editor onthe right, click the Dependencies tab.

Add the dependencies

Select Add and select the org.eclipse.hyades.logging.adapter andorg.eclipse.hyades.logging.core entries, as shown in Figure 12. Click OK.

Figure 12. Add the dependencies




The source XML code

Select the Plugin.xml tab to see the raw XML that defines the plug-in. Edit the XMLto add an extension:

<?xml version="1.0" encoding="UTF-8"?><plugin

id="StderrOutputter"name="StderrOutputter Plug-in"version="1.0.0"provider-name=""class="StderrOutputter.StderrOutputterPlugin">

<runtime><library name="StderrOutputter.jar"/>

</runtime><requires>

<import plugin="org.eclipse.core.resources"/><import plugin="org.eclipse.ui"/><import plugin="org.eclipse.hyades.logging.adapter"/>




<import plugin="org.eclipse.hyades.logging.core"/></requires><extension

point="org.eclipse.hyades.logging.adapter.adapterComponent"><componentClassname

name="mycompany.StderrOutputter"></componentClassname>

</extension>

</plugin>

Note how adding the dependencies has added imports for theorg.eclipse.hyades.logging.adapter and theorg.eclipse.hyades.logging.core plug-ins. Note also that you have yet towrite the mycompany.StderrOutputter component.

Create mycompany.StderrOutputter class

Now create the class mycompany.StderrOutputter in the src folder. The classmust extend org.eclipse.hyades.logging.adapter.impl.ProcessUnitand implement org.eclipse.hyades.logging.adapter.IOutputter, asshown in Figure 13.

Figure 13. New Java Class window




You also have the option to simply extend theorg.eclipse.hyades.logging.adapter.impl.Outputter class, the defaultimplementation of IOutputter.

A skeleton class is created, but it won't compile yet.

The outputter skeleton

All outputters start with the same basic skeleton, a class that extendsProcessUnit, implements IOutputter, and overrides processEventItems :




package mycompany;import org.eclipse.hyades.logging.adapter.IOutputter;import org.eclipse.hyades.logging.adapter.impl.ProcessUnit;import org.eclipse.hyades.logging.events.cbe.CommonBaseEvent;

public class StderrOutputter extends ProcessUnit implements IOutputter {private int _counter = 0;

public Object[] processEventItems( Object[] msgs ){if( msgs instanceof CommonBaseEvent[] ){

return processCBEs( (CommonBaseEvent[]) msgs );}

return null;}

private CommonBaseEvent[] processCBEs( CommonBaseEvent[] events ){// add code to process the events here

return events;

}}

Although the GLA should never call the outputter with anything but an array of eventobjects, always check for valid input before processing the array. The skeletonabove returns null if invalid input is detected. Otherwise, it invokes the privateprocessCBEs method to perform the work.

Processing the events

Now it's time to process the events that are passed to the outputter. You just add afew lines to the processCBEs method to cycle through the array and write eachevent out to the standard error stream as well as a sequence number that countshow many events you've processed. The revised outputter code is as follows:

package mycompany;import org.eclipse.hyades.logging.adapter.IOutputter;import org.eclipse.hyades.logging.adapter.impl.ProcessUnit;import org.eclipse.hyades.logging.events.cbe.CommonBaseEvent;

public class StderrOutputter extends ProcessUnit implements IOutputter {private int _counter = 0;

public Object[] processEventItems( Object[] msgs ){if( msgs instanceof CommonBaseEvent[] ){

return processCBEs( (CommonBaseEvent[]) msgs );}

return null;}

private CommonBaseEvent[] processCBEs( CommonBaseEvent[] events ){for( int i = 0; i < events.length; ++i ){CommonBaseEvent ev = events[i];if( ev != null ){

++_counter;System.err.println( "Stderr " + _counter +

": " + EventFormatter.toCanonicalXMLString(ev) );}

}return events;

}




}

Assuming the code above compiles without errors, you're ready to try it out.

Section 5. Testing the outputter

Running a self-hosted workbench

By creating our ouputter as an Eclipse plug-in, you can test it from within the Eclipseenvironment using a self-hosted workbench, which is effectively another instance ofEclipse launched directly from within the current instance. (Another name for aself-hosted worbench is a run-time workbench.)

To run a self-hosted workbench, select Run > Run As > Run-time Workbench.

This starts a new instance of Eclipse. This instance has access to the plug-in youjust built in the original Eclipse instance. And, important for your purposes, thestandard output and standard error streams from the new Eclipse instance will beredirected to the original Eclipse's console window.

Creating an adapter configuration

After the self-hosted workbench is running, the next step is to create a new adapterconfiguration that references the new outputter. You'll only need to do this once; theconfiguration is saved and available to you the next time you run the self-hostedworkbench.

From the self-hosted workbench, create a simple project to hold the configurationfile. The project is just a placeholder for configuration files, so on the next page setits name to Adapter configuration files as shown in Figure 14, and select Finish.

Figure 14. Create a new project resource




Selecting a Generic Log Adapter file

Select File > New > Other.... In the dialog, select Generic Log Adapter File.

Enter a file name for the new adapter file you're about to create. The name shouldend in .adapter to ensure that the Configuration File Editor can edit it as shown inFigure 15.

Figure 15. Entering a file name for the new adapter file




Selecting a sample log file

Finally, select a sample log file to associate with the adapter configuration. Thissample log file is used when testing the configuration. Any text file will work for thisdemo. In this example, select an Apache access log as shown in Figure 16.




Figure 16. New Generic Log Adapter file

Select Finish to create the adapter.

Configuration File Editor view

The Configuration File Editor opens automatically to a tree view that represents the




various parts of the XML configuration file. Expand the tree view and select theComponent Hyades Logging Agent Outputter as shown in Figure 17.

Figure 17. Selecting the Component Hyades Logging Agent Outputter in thetree view

To the right of the tree view you'll see a component editor with details about theoutputter as shown in Figure 18. Change the Executable Class tomycompany.StderrOutputter.

Figure 18. Changing the Executable Class in the component editor




Save the changes to the adapter file. Now you're ready to try your new outputter.

Testing the outputter

Test your outputter by first selecting the context instance in the tree view as shownin Figure 19.

Figure 19. Selecting the context instance in the tree view

Now move to the window immediately below the tree view and rerun the adapter bypressing the Rerun Adapter toolbar button.

Figure 20. Running the Adapter




This runs the sample log file through the adapter. If you move back to the originalEclipse instance, the one where we developed our outputter, you'll see theoutputter's output (written to the standard error stream) in the console window in thebottom righthand corner of the workbench as shown in Figure 21:

Figure 21. The Outputter's output in the console window

You've successfully tested the outputter. Congratulations, you've written your firstGLA component!

Section 6. Summary

Summary




The Generic Log Adapter for Autonomic Computing lets you build an autonomiccomputing solution that incorporates legacy software that was not written withautonomic computing technology in mind. This tutorial covered the basics of writingcustom components for the GLA, including:

• The architecture of the GLA

• Component configuration

• Creating components using Eclipse

• Testing components from within Eclipse




Resources

Learn

• Stay current with developerWorks technical events and Webcasts.

• More information on Regular Expressions can be found at opengroup.org,sitescooper.org, and The Apache Jakarta project.

• The design document provides more information about Common BaseEnvironment descriptors.

• An autonomic computing roadmap (developerWorks, February 2004) gives youa firm grip of the concepts necessary to understand this tutorial.

• For more information on Eclipse, visit the Eclipse Web site.

Get products and technologies

• The IBM Autonomic Computing Toolkit offers autonomic computingtechnologies to help enhance many of your systems' capabilities.

• Build your next development project with IBM trial software, available fordownload directly from developerWorks.

Discuss

• Participate in developerWorks blogs and get involved in the developerWorkscommunity.

About the author

Eric GiguereEric Giguere, a Studio B author, is a software developer who also writes books andarticles on a variety of topics. For more information, see his Web site at:http://www.ericgiguere.com. He can be reached at [email protected].



http://www.ibm.com/developerworks/offers/techbriefings/?S_TACT=105AGX03&S_CMP=art

http://www.opengroup.org/onlinepubs/007908799/xbd/re.html

http://sitescooper.org/tao_regexps.html

http://jakarta.apache.org/oro/

http://www.ibm.com/developerworks/library/ac-roadmap/

http://www.eclipse.org/

http://www.ibm.com/developerworks/autonomic/overview.html

http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX03&S_CMP=art

http://www.ibm.com/developerworks/blogs/

http://www.studiob.com

http://www.ericgiguere.com

mailto:[email protected]


Create GLA components using Release 2 of the Autonomic ......Autonomic Computing Toolkit Skill...

Documents

Transcript of Create GLA components using Release 2 of the Autonomic ......Autonomic Computing Toolkit Skill...