Enable the WSDM Event Format using the Generic Log Adapter

Document options Document options requiring JavaScript are not displayed Discuss Rate this page Help us improve this content

Level: Intermediate

Abdi Salahshour (abdis@us.ibm.com), Senior Software Engineer, IBM　
Jane Fang (janefang@ca.ibm.com), Software Engineer, IBM

20 Nov 2007

Get the details of the mapping between Common Base Events and the Web Services Distributed Management (WSDM) Event Format (WEF). This mapping helps when you already have adopted the Common Base Event format, but want to transform native log events further into WEF events. Then, learn how to turn a Common Base Event adapter into a WEF adapter.

Introduction

The Generic Log Adapter (GLA) transforms software log events from their native format into a Common Base Event 1.0.1 format. The IBM® Autonomic Computing Toolkit provides GLA configuration adapters to support over 280 log types, and these adapters are used by the Log and Trace Analyzer problem determination tools. In 2005, the Common Base Event specification was submitted to the Organization for the Advancement of Structured Information Standards (OASIS) WSDM Technical Committee, which adopted the Common Base Event as a base for the WSDM Event Format (WEF). If you've already adopted the Common Base Event format but want to transform native log events further into WEF events, this article describes the details of the mapping between the Common Base Event and WEF and shows you how into turn a Common Base Event adapter into a WEF adapter.

Events are an external, visible manifestation of all system operations — they represent the onset, evolution, and conclusion of processes. The situation represented by an event may have only local relevance or may provide a key piece of information required by a high-level environment management system. The event, which encapsulates data sent as the result of an occurrence, or situation, represents the very foundation on which these complex systems communicate.  

The Common Base Event -- which uses a consistent and common format to represent an event produced during the operation of an IT system -- facilitates effective intercommunication among disparate components that support logging, management, problem determination, autonomic computing, and on demand business functions in an enterprise. The goal of defining the Common Base Event format is to ensure the accuracy, improve the detail, and standardize the format of events to assist in designing robust, manageable, and deterministic systems. Quality event data leads to accurate management of the enterprise.

The Generic Log Adapter is a framework that provides a set of Java™ libraries that can be called within your code to perform continuous or one-time conversion of native log events into Common Base Events and conversion of Common Base Events into WEF events and vice versa.  In addition, it provides out-of-the-box adapters for many key product logs.

The Common Base Event definition, besides providing definitions and requirements for the basic meta-data, ensures completeness of the data by providing properties to publish the following information:

• The identification of the component that is reporting the situation
• The identification of the component that is affected by the situation (which may be the same as the component that is reporting the situation)
• A common description of the situation that occurred
• Content that can be used to correlate situations 

In March 2005, the "OASIS WSDM Technical Committee produced two specifications, Web Services Distributed Management: Management Using Web Services (MUWS 1.1)" Part 1 and Part 2 (see Resources), which include the WSDM Event Format. WEF is based on IBM's submission of the Common Base Event to OASIS; the standardized WEF essentially is a subset of the Common Base Event. WEF maintains the significant elements and structure of the Common Base Event (including metadata, source and reporter identification, and canonical situations); however, it omits a few elements and attributes of the Common Base Event, where the Common Base Event format is more prescriptive and provides semantic richness for events. WEF provides numerous standardized extension points that allow for additional elements and attributes to be added.

The IBM Autonomic Computing Toolkit provides a Java library that lets you generate WEF events and perform bidirectional conversion between WEF events and Common Base Events. The library is built on the Apache Muse WEF library in a way that no information is lost when converting Common Base Events into WEF events or vise versa.

This article assumes that you have some working knowledge of GLA adapters, the Common Base Event format, and the WEF format.  You can get more background information in Resources, if needed.

Let's look at the mapping between Common Base Event and WEF events applied by the library.

Back to top

Mapping Common Base Events into WEF

The WEF format has the essential elements of the Common Base Event format and are mapped one-to-one as shown in Table 1.

To provide the same semantic richness offered by Common Base Event, the following product-specific elements are introduced in WEF through extension points as shown in Table 2.

ExtendedContent can also be used to wrap any elements that have no equivalent element in WEF.

Severity

The attribute severity of WEF ranges from 0 to 6, as shown in Table 3 . However, in the Common Base Event schema, the severity values range from 0 to 70. The fourth column in Table 3 shows the valid range of values for each Common Base Event severity level.

When converting a WEF event into a Common Base Event, the severity is converted into the corresponding Common Base Event severity (shown on the second column), except Major (that is, 4), which is converted to the value 45.

On the other hand, when converting a Common Base Event into a WEF event, the severity value (cbeSeverity) is converted to the corresponding WEF severity value and the original value (cbeSeverity) is also kept in an ExtendedContent. For example, a Common Base Event severity 55 is converted to 5, and an ExtendedContent element (shown in Listing 1) is created and added in the WEF event.  

<ExtendedContent extendedDataType="ExtendedDataElement"
instanceOf="ExtendedDataElement">
    <ExtendedDataElement name="severity" type="string">
        <values>55</values>
    </ExtendedDataElement>
</ExtendedContent>
  

Situation

The situation element in a WEF event contains more information than a Common Base Event situation element.  It also contains equivalents for Common Base Event root-level attributes: msg, priority, and creationTime. For an explanation of these elements/attributes, refer to "OASIS Web Services Distributed Management: Management Using Web Services (MUWS 1.1) Part 1" (see Resources).

The WEF situation category types are almost the same as Common Base Event situation types. However, some Common Base Event situation types have extra attributes. Because a WEF situation can have as many wrapping qualifications, those attributes are mapped as qualifications as shown in Table 4.

The WEF situation also includes the MsgDataElement attribute and elements, msgCatalogTokens, msgId, and msgIdType.  For details refer to "Web Services Distributed Management: Management Using Web Services (MUWS 1.1) Part 1."

ReportTime

In a WEF event, ReportTime is an optional attribute. However, if the event does have the attribute wefReportTime, it will be converted by the GLA Adapter into an extendedDataElement as shown in Listing 2.

<extendedDataElement name="ReportTime" type=”string”>
    <values>wefReportTime<values>
</extendedDataElement>

WEF any elements

The GLA provides an adapter to convert WEF events to Common Base Event-formatted events. This adapter is a simple solution for those product logs that are natively in a WEF format so that they can be consumed by advanced analysis tools that consume Common Base Events, such as in the Autonomic Computing Log and Trace problem determination tools.  

WEF provides four extension points for you to plug in four types of any elements. Such any elements are converted into Common Base Event extended data elements with a name indicating the type of any element.

Listing 3 and 4 show how a WEF event (Listing 3) is converted into a Common Base Event event (Listing 4).

<muws1:ManagementEvent
    xmlns:muws1="http://docs.oasis-open.org/wsdm/muws1-2.xsd"
    ReportTime="2007-05-07T08:25:16-04:00">
  <muws1:EventId>uuid:ADT-A04-ADT_A01</muws1:EventId>
    <muws1:SourceComponent>
      <muws1:ComponentAddress>
        <wsa:EndpointReference 
             xmlns:wsa="http://www.w3.org/2005/08/addressing">
    	    <wsa:Address>
    	      http://localhost:8080/axis2/services/HealthcareProviderService
   	    </wsa:Address>
    	  </wsa:EndpointReference>
    	</muws1:ComponentAddress>
    </muws1:SourceComponent>
    <muws2:Situation 
        xmlns:muws2="http://docs.oasis-open.org/wsdm/muws2-2.xsd">
      <muws2:SituationCategory>
        <muws2:ReportSituation />
      </muws2:SituationCategory>
    <muws2:SituationTime>
      2007-05-07T08:25:16-04:00
    </muws2:SituationTime>
  </muws2:Situation>
  <HL7V2>MSH|^~\\&|HealthcareProviderService^
    	http://hips.hl7.example^URI||||200705070825||
    	ADT^A04^ADT_A01PID|||1000||DOE^JOHN
  </HL7V2>
</muws1:ManagementEvent>

<CommonBaseEvent creationTime="2007-05-07T12:25:16.000Z" 
  globalInstanceId="ADT-A04-ADT_A01">
  <extendedDataElements name="ExtendedDataElement_situation" 
    type="string">
    <children name="ReportSituation" type="string">
   <values>http://docs.oasis-open.org/wsdm/muws2-2.xsd</values>
   <values>muws2</values>
    </children>
  </extendedDataElements>
  <extendedDataElements name="ReportTime" type="string">
    <values>1178540716000</values>
  </extendedDataElements>
  <extendedDataElements name="Source_Address_any">
    <children name="wsa:EndpointReference" type="string">
   <children name="uri" type="string">
     <values>http://www.w3.org/2005/08/addressing</values>
   </children>
   <children name="wsa:Address" type="string">
     <children name="uri" type="string">
    <values>http://www.w3.org/2005/08/addressing</values>
     </children>
     <children name="Text" type="string">
    <values>
      http://localhost:8080/axis2/services/HealthcareProviderService
    </values>
     </children>
   </children>
    </children>
  </extendedDataElements>
  <extendedDataElements name="ManagementEvent_any">
    <children name="HL7V2" type="string">
   <children name="uri" type="string">
     <values>http://www.ibm.com/AC/commonbaseevent1_0_1</values>
   </children>
   <children name="Text" type="string">
     <values>
    MSH|^~\&|HealthcareProviderService^
http://hips.hl7.example^URI||||200705070825||ADT^A04^ADT_A01PID|||1000||DOE^JOHN
     </values>
   </children>
    </children>
  </extendedDataElements>
  <sourceComponentId/>
  <situation categoryName="OtherSituation">
   <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:type="OtherSituation">
    </situationType>
  </situation>
</CommonBaseEvent>
  

In the reverse conversion, when Common Base Events are converted into WEF-formatted events, all Common Base Event Extended Data Elements that do not follow the convention in Table 4 are placed in the ExtendedContent in WEF.

Back to top

Enable the GLA to support WEF

Prerequisites

To use the library, in addition to the GLA framework, the following Java archive files are required and must be placed in the GLA installation path within the ac-gla\lib directory.

Configure the AC adapter to generate WEF events

Any one of the GLA adapters can be modified to output WEF events instead of Common Base Events by using the WEF outputter com.ibm.etools.logging.adapter.outputters.WEF11Outputter.

To configure the static Apache 1.3.26 access log adapter using the GLA editor so that an Apache access log can be transformed into a WEF log, use the following steps:

1. Open the adapter file in the GLA editor. Navigate to Contexts > Basic Context Implementation, and replace the executable class for the Common Base Event file outputter with com.ibm.etools.logging.adapter.outputters.WEF11Outputter.
   

   Figure 1. Open the static adapter in the GLA editor

   
2. Navigate to Configuration > Context Instance. For sensor, set the property directory to the directory where your Apache access log file is and set the property file name to the name of the log file.
   
   
3. Enable the outputter highlighted in Figure 2 by deselecting Disabled, set the property directory to where you want to keep the output file (for example, d:\tmp), and set the property file name to the name of the output file, (for example, myWef.log). Also disable the other two outputters by selecting each outputter and checking Disabled.
   
   

   Figure 2. Configure outputter
   

To test the adapter, click Run in the Extractor Results view shown in Figure 2. In the output file location, in this example d:\tmp, a file named myWef.log should be created that contains WEF events generated for each record in your Apache access log.

Back to top

Conclusion

In this article you learned the details of how Common Base Events can be converted into WEF events using IBM and Apache Muse WEF libraries. This will help those who have already adopted the Common Base Event format and want to transform native log events further into WEF events. This allows a variety of product logs to be used by your favorite event analysis tool that can consume either WEF or Common Base Events for analysis and problem determination.

Resources

• Participate in the discussion forum.
  
  
• Download the Generic Log Adapter for Autonomic Computing from the IBM Autonomic Computing Toolkit.
  
  
• Learn more about the Common Base Event and the supporting technologies that define the structure of an event in a consistent and a common format with the "Canonical Situation Data Format: The Common Base Event V1.0.1."
  
  
• The Common Base Event Producers can be found on the developerWorks Autonomic Computing technology zone. 
  
  
• Get updates on Apache Muse from the Apache Web site.
  
  
• Read the OASIS documentation "Web Services Distributed Management: Management Using Web Services (MUWS 1.1)," both Part 1 and Part 2.
  
  
• IBM Build to Manage Toolkits help you seamlessly enable your solutions with manageability.

About the authors

		Abdi Salahshour is a Senior Software Engineer, problem determination architect, and Master Inventor at IBM's Autonomic Computing Technology and Development, who started with IBM in 1982 and served in many roles -- from design and development of database diagnostic tools to system management and self-healing architecture and enablement in heterogeneous and distributed environments. He was a member of IBM Problem Determination Council, is one of the authors of the IBM Common Base Event specification, one of the principal designers and implementers of the Generic Log Adapter, and the architect and designer of the Log and Trace Analyzer for Java Desktop.

		Jane Fang is a Software Engineer within the Autonomic Computing group at the IBM Toronto Lab. She has been working on Log and Trace Analyzer for Autonomic Computing and related technology for more than three years, and also developed the WEF extension Java library.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top