Document Number SC30-4083-03
| Note |
|---|
|
Before using this information and the product it supports, read the general information in Appendix C, Notices. |
Third Edition (September 2005)
This edition applies to Release 3 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 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.
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 functions.
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 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.
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.
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.
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.
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.
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.
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 (FLEXnet Publisher Installation Module and Solution Architect from Macrovision.) -- are detailed in separate documentation provided with the Autonomic Computing Toolkit. These two scenarios have been combined into the Solution Installation and Deployment Scenario Guide.
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.
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.
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.
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 acceptance and fidelity. However, it is possible that at times a sender may exceed these length restrictions. In this case, it is incumbent upon the consumer of an event to take appropriate actions to either accept the event as-is, massage it to conform to the specification, or discard as invalid. However, in general, preservation of data -- even data that is out of conformance with this event specification -- is preferable to a total loss of the event. Therefore, it is recommended that all efforts be made to preserve as much of the event data as possible.
All names and strings specified in this document are case sensitive.
The Common Base Event data model described here is built with some level of extensibility to lend itself easily to the needs of a variety of types of events generated by different IT and business products. In particular, the data elements and the format of those elements need to be consistent, as all of these events need to be correlated with each other, but they also need to be flexible to allow for adaptation to product-specific requirements.
The use of the ExtendedDataElement (described in ExtendedDataElement description) is RECOMMENDED for including product-specific attributes. This property allows for user-supplied extensions for any other attributes not defined in the CommonBaseEvent.
Product-specific schema MAY be included in the CommonBaseEvent XML Schema (described in Common Base Event XML schema) to extend that property with the product specific requirements in the "any namespace" of the schema. The event consumers or management tools that support the CommonBaseEvent schema SHOULD store and forward the unrecognized and unsupported portion of the extended schema. However, there is no implied guarantee that the extended elements are saved and forwarded by the consumer of the event that does not recognize the extension.
Multiple versions of the XML schema are supported by appending a version number to the XML schema file name. The current XML file name is therefore, commonbaseevent1_0_1.xsd. Also, the CommonBaseEvent schema provides "version" token in the schema declaration (see Common Base Event XML schema) and a "version" attribute in the CommonBaseEvent element.
Table 3 is a summary of the CommonBaseEvent
properties; that is, the data collected for the situation 3-tuple.
As stated earlier, the 3-tuple consists of the ID of the component
experiencing the situation, the ID of the component reporting the situation,
and the situation itself.
Table 3. CommonBaseEvent XML properties
The following sections contain detailed descriptions of these properites
The version attribute is of type string and is used to identify the version of a given event such that it can be recognized and managed appropriately by receivers of the event.
This field is OPTIONAL in that if it is not specified, the version of the Common Base Event is said to be 1.0. Otherwise this field MUST be filled in and MUST be consistent with the version specified in the schema header. The string length for version MUST NOT exceed 16 characters. When an application is creating an event following this version of the specification this field should be set to 1.0.1.
This property is mutable in the case where a migration procedure has upgraded a Common Base Event to a newer version.
The localInstanceId is of type string and is used to locally identify instances of an event. There is no implied guarantee that this value is globally unique but unique within the execution process that generates the event. However, after it is set it MUST remain constant for the lifetime of the event. The value content of the localInstanceId MAY be a multipart value, such a timestamp, location, offset, or message ID and MAY use other application-defined techniques to ensure the uniqueness of the ID values. For example, the identifier value might be set to the string concatenation of the local host IP address, the absolute path of the access.log file, the local fully qualified host name, a time stamp, and the sequenceNumber. The resulting identifier might look as follows:
9.27.11.27mycomputer.toronto.ibm.com2002100902534.002000-240
This property is not a key. This is an OPTIONAL property that is not mutable; that is, once it is set it MUST NOT be changed. It MAY be provided by the component that issues the event or MAY be assigned by the consumer of the event. The string length for the localInstanceId MUST NOT exceed 128 characters.
The globalInstanceId is a complex data type that represents the primary identifier for the event. The property globally and uniquely identifies the event and MAY be used as the primary key for the event. The value MUST be a GUID that is at least 128 bits in length but not greater than 256 bits and MUST start with an alphabetic character (for example, A-Z). The GUID generation algorithm MUST ensure the uniqueness of this value.
One standard for constructing a GUID is defined in the Internet draft draft-leach-uuids-guids-01. This value is computed based on using cryptographic quality random information. This Internet draft does not generate a GUID that starts with an alphabetic character; to use it you MUST prepend it with a single character.
This is an OPTIONAL property. However, when it is specified it is not mutable; that is, after it is set, it MUST NOT be changed for the lifetime of the event. The globalInstanceId MAY be provided either by the component that issues the event or by the consumer of the event.
The globalInstanceId is required if associations among events are to be established. If globalInstanceId is not specified, then the association specified by AssociatedEvent (AssociatedEvent description) cannot be used.
The date and time that the event was created that MUST be specified as defined by the XML Schema dateTime data type. 3 The value of the creationTime MUST provide granularity as precisely as the generating platform allows.
This is a REQUIRED property that is not mutable (that is, its value MUST NOT be changed for the lifetime of the event) and MUST be provided by the component that reports the event.
The severity indicates the event status severity level with respect to the component that reports the event. These values are usually provided by a component's domain expert. The meanings of the values that this property may contain MAY be described by an enumeration of common values or qualifiers that indicate the severity level of the event. For example, information, warning, or a set of integers that map to the intended severity levels are all valid values. This appendix does not imply any specific implementation, but instead suggests the following values based on prior art with the understanding that users of this field MAY add additional implementation-specific values. This field is intended to define the seriousness of the kind of situation that was encountered so that administrators can focus on the most severe problems.
The predefined severity levels, in order of increasing severity, are as follows:
The associated values are 0 to 70. The reserved values start at 0 for Unknown and increase by increments of 10 to 60 for Fatal. Other severities MAY be added but MUST NOT exceed 70. If no value is specified, this event is interpreted as having no severity.
This is an OPTIONAL property and is not mutable once it is set. There is no default value for severity.
The priority defines the importance of the event and the relative order in which the event records SHOULD be processed. The predefined priorities are as follows:
The values are 0 to 100. The reserved value for Low is 10, for Medium is 50, and for High is 70. Other priorities MAY be added but MUST NOT exceed 100.
If no value is specified, then this event is interpreted as having no priority.
The priority property is independent of severity, because priority is intended to be used primarily by event consumers, whereas severity indicates the state of the situation as perceived by the affected component. For example, an event with priority HIGH and severity MINOR should be processed before an event with priority LOW and severity CRITICAL.
This is an OPTIONAL property and it is mutable. There is no default value for the priority.
The reporterComponentId is the identification of the component that reported the event or situation on behalf of the affected component. The data type for this property is a complex type as described by the ComponentIdentification type that provides the required data to uniquely identify a component.
It is a REQUIRED property if the reporting component is different than the source component. Otherwise, this field MUST NOT be present. This property is not mutable.
The sourceComponentId is the identification of the component that was affected or was impacted by the event or situation. The data type for this property is a complex type as described by the ComponentIdentification type that provides the required data to uniquely identify a component.
This property is REQUIRED and it is not mutable. The producer of the event MUST provide the sourceComponentId. If the reporter and the affected components are the same, then the reporterComponentId MUST NOT be present.
The situation is the data that describes the situation or event reported by the event. The situation information includes a required set of properties or attributes that are common across products groups and platforms, yet architected and flexible to allow for adoption to product-specific requirements. The situation is an element of type Situation (see Situation), which specifies the type of the situation that caused the event to be reported.
This is a REQUIRED property and is not mutable.
The contextDataElements is an array of contexts of type ContextDataElement (see ContextDataElement description) that this event is referencing. This property holds data that is used to assist with problem diagnostics by correlating messages or events generated along the execution path of a unit of work.
This is an OPTIONAL property and is not mutable. It MAY be provided by the component that issues the event or MAY be assigned by the consumer of the event.
The msg property is the text that accompanies the event. This is typically the resolved message string in human-readable format rendered for a specific locale.
The locale of the msg property is specified by the msgLocale property of the MsgDataElement type (see MsgDataElement description).
This property is OPTIONAL but RECOMMENDED if the msgCatalogId and msgCatalog properties of the MsgDataElement do not specify any values.
The string length for msg MUST NOT exceed 1024 characters.
The msgDataElement is a property that is refers to a MsgDataElement. This property holds data that is used to specify all the related information associated with the message that this event holds.
This is an OPTIONAL property and is not mutable. It is provided by the component issuing the event.
The extensionName property contains the name of an "event class" that this event represents (for example, Trace, CommonBaseEvent). The event class name is indicative of any additional properties expected to be present within the specific event. If you choose to use ExtendedDataElement, it is RECOMMENDED that you specify a value for the extensionName.
This is an OPTIONAL property and is not mutable. It can only be provided by the component that reports the event. If the value specified is null, then the value is assumed to be CommonBaseEvent.
The extendedDataElements property is a sequence of name elements of type ExtendedDataElement (described in ExtendedDataElement description). It offers extensibility by providing a way to specify any other attributes not defined by the CommonBaseEvent data model. Information placed here is assumed to be product-specific data.
This property is user-supplied; its named elements can be filtered, searched, or referenced by the correlation rules.
This is an optional property and is mutable. The value for this property MAY be provided by the component that issues the event or the event consumer MAY assign it.
The associatedEvents property allows for event grouping or parent-child relationship. This property is a complex type that consists of globalInstanceIds that identify the associated events (described in AssociatedEvent description).
This is an OPTIONAL property and is mutable. The value for this property MAY be provided by the component that issues the event or the event consumer MAY assign it.
The repeatCount specifies the number of occurrences of identical events within a specified time interval. The time interval is specified by the elapsedTime property described next. The definition of identical events is application specific and therefore is not defined by this specification.
This property is OPTIONAL and is mutable. The repeatCount property MAY be set by the component that issues the event or the event consumer. There is no default value. A value of 0 or no value indicates no repeated occurrences of the event.
The elapsedTime is the time interval during which some number of identical events occurred. The number of occurrences is specified by the value of the repeatCount. The elapsedTime value indicates the duration of time within which the repeated events were observed.
The value of this property MUST be expressed in microseconds granularity.
This property is OPTIONAL and is mutable. However, if the repeatCount is specified, an elapsed time MUST be present. The elapsedTime MUST be set by the same component that sets the repeatCount. There is no default value for elapsedTime.
The sequenceNumber is a source-defined number that allows multiple messages to be sent and processed in a logical order that might be different than the order in which they arrived at the consumer's location (for example, with event servers or management tools). The sequence number helps consumers to sort messages when they arrive. This is with respect to time and to the particular provider of the event.
This property is OPTIONAL and it is not mutable. There is no default value.
In the area of problem reporting, two general categories of components that should be considered for problem diagnosis: the component that observes and reports the situation (the reporter component), and the actual component that experiences the situation (the affected component). Component identification provides a collection of attributes that are required to uniquely identify a component. The same data is used to identify both the reporter and the affected component. In some cases, these components might be the same.
For example, in a typical IT environment the activities of applications running in that environment are monitored using events that are received or collected from the applications using management agents or adapters.
Table 4 is a summary of the properties for the
ComponentIdentification type. A detailed description of the
ComponentIdentification properties follows the summary
table.
Table 4. ComponentIdentification properties
| Property name | Type | Description |
|---|---|---|
| location | xsd:string | Specifies the physical address that corresponds to the location of a component. For example, host name, IP address, MAC address, or IBM VTAM(R) logical unit (LU). The format of the value of the location is specified by the locationType property. The RECOMMENDED value is a fully qualified host name. This value should be unique within the network that is capable of raising events to a specified receiver. For example, if an adapter were monitoring a router, this attribute SHOULD contain the IP address of the machine where the adapter resides, not the IP address of the router that is having the problem. This is a REQUIRED property. The string length for location MUST NOT exceed 256 characters. |
| locationType | xsd:Name | Specifies the format and meaning of the value in the location
property. The reserved keywords for this property are:
|
| application | xsd:string | The name of the application (for example, myWebApp). This is an optional property. The application version information MAY be appended to the end of the component separated by a # character (for example, maWebApp#4.5.1). This is an OPTIONAL property. The string length for application MUST NOT exceed 256 characters. |
| executionEnvironment | xsd:string | This property identifies the immediate environment that an application is running in. For example, a WebSphere Application Server name: cell:node:server. The executionEnvironment version information can be appended to the end of the component separated by a # character. This is an OPTIONAL property. The string length for executionEnvironment MUST NOT exceed 256 characters. |
| component | xsd:string | Specifies the logical identity of a component. This property MUST contain the name of a particular application, product or subsystem (for example, IBM DB2# 7.1). This value SHOULD be unique within the scope specified by the locationType. The component version information MAY be appended to the end of the component name separated by a # character. This is a REQUIRED property. The string length for the component name MUST NOT exceed 256 characters. |
| subComponent | xsd:string | Specifies a further distinction for the logical component property of the event. It SHOULD contain the identity of the subcomponent of the component property. This property MAY be one of the various parts of an application or operating system resource (for example, a module name, a class name, a class and method name, and so on). It SHOULD be the most granular definition specified in the event. The subcomponent version information MAY be appended to the end of the subcomponent name separated by a # character. This is a REQUIRED property. The string length for the subComponent name MUST NOT exceed 512 characters. |
| componentIdType | xsd:string | Specifies the format and meaning of the component identified by this
componentIdentification. The non-exclusive reserved keywords
for this property are:
|
| instanceId | xsd:string | Specifies a handle or identifier for the instance of the component that is specified by the component property (for example, Grid Service Handle [GSH] or EJBHandle). This is an OPTIONAL property. The string length for instanceId MUST NOT exceed 128 characters. |
| processId | xsd:string | This property identifies the process ID of the running component or subcomponent that generated the event. This is an OPTIONAL property with no default value. The string length for processId MUST NOT exceed 64 characters. |
| threadId | xsd:string | This property identifies the thread ID of the component or subcomponent that generated the event. This value changes with every new thread spawned by the process identified by processId. This is an OPTIONAL property with no default value. The string length for threadId MUST NOT exceed 64 characters. |
| componentType | xsd:string | The componentType is a well-defined name that is used to characterize all instances of a given kind of component. This property is REQUIRED property. The maximum string length for componentType MUST NOT exceed 512 characters. |
The location specifies the physical address that corresponds to the location of a component. Examples of locations include: a host name, IP address, MAC address, or VTAM LU. The format of the value of the location is specified by the locationType property. The RECOMMENDED value is a fully qualified host name.
This property is REQUIRED and it is not mutable. The string length for location MUST NOT exceed 256 characters.
This property specifies the format and meaning of the value in the location property. The reserved keywords for this property are:
This property is REQUIRED and is not mutable. The string length for locationType MUST NOT exceed 32 characters. If the location value does not have a well-known type, the locationType MUST contain Unknown.
The application property specifies the user name of application (for example, myApp). The application version information MAY be appended to the end of the component separated by a # character (for example, myApp#3.2). It is RECOMMENDED that the vendor name be prepended to the application name.
This is an OPTIONAL property and is not mutable. The string length for the application name MUST NOT exceed 256 characters.
The executionEnvironment property identifies the immediate environment that an application is running in. For example, a WebSphere Application Server name: cell:node:server.
The executionEnvironment version information MAY be appended to the end of the component separated by a # character (for example, thiscell:thisnode:thisserver#5.3.2). The string length for executionEnvironment MUST NOT exceed 256 characters.
This is an OPTIONAL property and is not mutable.
The component specifies the logical identity of a component. This property MUST contain the name of a particular application, product, or subsystem (for example, IBM DB2#7.1). This value SHOULD be unique within the scope specified by the reporter location.
This property is REQUIRED and is not mutable. The string length for the component name MUST NOT exceed 256 characters.
The subComponent specifies a further distinction for the logical component property of the event.
It SHOULD contain the identity of the subcomponent of the component property and it SHOULD be the most granular definition specified in the event. This property MAY be one of the various parts of an application or operating system resource such as a module name, class name, class, method name, and so on.
This property is REQUIRED and it is not mutable. The string length for the subComponent name MUST NOT exceed 512 characters.
The componentIdType specifies the format and meaning of the component identified by this componentIdentification. The reserved, nonexclusive list of keywords for this property are:
This property is REQUIRED and it is not mutable. The string length for componentIdType MUST NOT exceed 32 characters.
The instanceId specifies a handle or identifier for the instance of the component that is specified by the component property, for example, Grid Service Handle (GSH), 4 EJBHandle, and so on.
This property is OPTIONAL and is not mutable. The string length for instanceId MUST NOT exceed 128 characters.
The processId is a string type that identifies the process ID of the running component or subcomponent that generated the event. The value is platform-specific.
This is an OPTIONAL property that is not mutable. The string length for processId MUST NOT exceed 64 characters.
The threadId property is of type string and identifies the thread ID of the component or subcomponent indicated by the process ID that generated the event. A running process may spawn one or more threads to execute its functions. Therefore, the thread ID will change accordingly. The value is platform-specific.
This is an OPTIONAL property that is not mutable. The string length for threadId MUST NOT exceed 64 characters.
The componentType is a well-defined name (syntax and semantics) that is used to characterize all instances of a given kind of component. For details of the contents of this property, refer to the componentType entry in Component type namespace.
This property is REQUIRED and it is not mutable; that is, once it is set it MUST NOT be changed. The maximum string length for componentType MUST NOT exceed 512 characters.
Table 5 is a summary of the properties for the Situation
type. A detailed description of the Situation properties
follows the summary table.
| Property name | Type | Description |
|---|---|---|
| situationType | cbe:SituationType | The situationType specifies the type of the situation that caused the event to be reported. This is an REQUIRED property. |
| categoryName | xsd:string | The categoryName specifies the type of the situation that
caused the event to be reported. The categoryName is a
string and has the following set of values:
|
This property categorizes the type of the situation that caused the event to be reported. The categoryName property has the following set of values:
This is a REQUIRED property and once it is set it is not mutable.
The situationType specifies the type or category of the situation that caused the event to be reported. The categorization of situations facilitates the building of tools that focus on implementing the analysis and planning functions rather than on product-specific data formats. The data type for this property is a complex type. The situation types or categories are defined below. SituationType is an abstract element that is used to define all supported situation types (for example, StartSituation, StopSituation, and so on).
The simplest way to understand the usefulness of categorization is by providing a use case. For example, assume that a problem has been detected with component A. The first step in the root-cause analysis might be to check to see if x was actually started, because it is known that A has a dependency on x. One approach to determine if x is running is to check the log file for x to see if it has started. The problem from a programmatic perspective is that there is not standard way to check the log files to see if x has started. x might log "Component x started" or it might say, "Change server state from starting to running." The reality is that both of these messages provide the same information, but they provide it using different terminology, making it difficult for a program to use. Simple checks like this would be much easier if all components reported, for example, that they "started." Writing code to check dependencies would be much easier and would be, largely, component independent. For example, if product A had dependencies on x and y, the code to check the status of x and the code to check the status of y would be the same, in both cases, it would look for a "started" message.
This is a REQUIRED property and after it is set it is not mutable.
The following sections outline the well-known and acceptable values for the
situationType Table 6).
Table 6. situationType property
| Property name | Type | Description |
|---|---|---|
| reasoningScope | xsd:string | This property specifies the scope of the impact of the situation reported. The initial set of values is described following this table. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters. |
This is a REQUIRED property and once it is set it MUST NOT change. This property specifies the scope of the situation. The reasoningScope defines whether this situation has an internal only impact or has a potential external impact. The reasoningScope is of type SituationReasoningScopeType and has the following initial set of values:
The StartSituation deals with the start up process for a component. Messages that indicate that a component has begun the startup process, that it has finished the startup process, or that it has aborted the startup process all fall into this category. Existing messages include words like starting, started, initializing, and initialized, for example:
DIA3206I The TCP/IP protocol support was started successfully.
DIA3000I "%1S" protocol support was successfully started.
DIA3001E "%1S" protocol support was not successfully started.
WSVR0037I: Starting EJB jar: {0}
Table 7 shows the StartSituation properties.
Table 7. StartSituation properties
| Property name | Type | Description |
|---|---|---|
| successDisposition | xsd:string | This property specifies the success disposition of an operation of a
situation that caused the situation to be reported. The
successDisposition is a string with the following set of
values:
|
| situationQualifier | xsd:string | This property specifies the situation qualifiers that are representation
of the parameters necessary to describe the situation. The
situationQualifier is a string with the following set of
values:
|
The StopSituation deals with the shutdown process for a component. Messages that indicate that a component has begun to stop, that it has stopped, or that the stopping process has failed all fall into this category. Existing messages include words like stop, stopping, stopped, completed, and exiting, for example:
WSVR0220I: Application stopped: {0}
WSVR0102E: An error occurred stopping, {0}
MSGS0657I: Stopping the MQJD JMS Provider
Table 8 shows the StopSituation properties.
Table 8. StopSituation properties
| Property name | Type | Description |
|---|---|---|
| successDisposition | xsd:string | This property specifies the success disposition of an operation of a
situation that caused the situation to be reported. The
successDisposition is a string with the following set of
values:
|
| situationQualifier | xsd:string | This property specifies the situation qualifiers that are representation
of the parameters necessary to describe the situation. The
situationQualifier is a string with the following set of
values:
|
The ConnectSituation deals with the situations that identify aspects about a connection to another component. Messages that say a connection failed, that a connection was created, or that a connection was ended all fall into this category. Existing messages include words like connection reset, connection failed, and failed to get a connection, for example:
DBMN0015W: Failure while creating connection {0}
DBMN0033W: connection close failure {0}
DBMN0023W: Failed to close a connection {0}
Table 9 shows the ConnectSituation properties.
Table 9. ConnectSituation properties
| Property name | Type | Description |
|---|---|---|
| successDisposition | xsd:string | This property specifies the success disposition of an operation of a
situation that caused the situation to be reported. The
successDisposition is a string with the following set of
values:
|
| situationDisposition | xsd:string | This property specifies the situation disposition that is representation
of the parameters necessary to describe the situation. The
situationDisposition is a string with the following set of
values:
|
The RequestSituation deals with the situations that a component uses to identify the completion status of a request. Typically, these requests are complex management tasks or transactions that a component undertakes on behalf of a requestor and not the mainline simple requests or transactions. Existing messages include words like configuration synchronization started, and backup procedure complete, for example:
ADMS0003I: Configuration synchronization completed
Table 10 shows the RequestSituation properties.
Table 10. RequestSituation properties
| Property name | Type | Description |
|---|---|---|
| successDisposition | xsd:string | This property specifies the success disposition of an operation of a
situation that caused the situation to be reported. The
successDisposition is a string with the following set of
values:
|
| situationQualifier | xsd:string | This property specifies the situation qualifiers that are representation
of the parameters necessary to describe the situation. The
situationQualifier is a string with the following set of
values:
|
The ConfigureSituation deals with the components identifying
their configuration. Any changes that a component makes to its
configuration should be logged using this category. Additionally,
messages that describe current configuration state fall into this
category. Existing message include words like port number is, address
is, and process id, for example:
ADFS0134I: File transfer is configured with host="9.27.11.13", port="9090", securityEnabled="false".
Table 11 shows the ConfigureSituation properties.
Table 11. ConfigureSituation properties
| Property name | Type | Description |
|---|---|---|
| successDisposition | xsd:string | This property specifies the success disposition of an operation of a
situation that caused the situation to be reported. The
successDisposition is a string with the following set of
values:
|
The AvailableSituation deals with the situations reported from the component, regarding its operational state and availability. This situation provides a context for operations that can be performed on the component by distinguishing if a product is installed, operational and ready to process functional requests, or operational and ready/not ready to process management requests. Existing message include words like those that now ready to take requests, online, and offline, for example:
ADMC0013I: SOAP connector available at port 8880 ADMC0026I: RMI Connector available at port 2809
Table 12 shows the AvailableSituation properties.
Table 12. AvailableSituation properties
| Property name | Type | Description |
|---|---|---|
| operationDisposition | xsd:string | This property specifies the operation state of the component reported by
the situation. The operationalDisposition is a string with
the following set of values:
|
| availabilityDisposition | xsd:string | This property specifies the availability disposition of an entity or
component that caused the situation to be reported. The
availabilityDisposition is a string with the following set of
values:
|
| processingDisposition | xsd:string | This property specifies the processing disposition of a component
operation that caused the situation to be reported. The
processingDisposition is a string with the following set of
values:
|
The ReportSituation deals with the situations reported from the component, such as heartbeat or performance information. Data such as current CPU utilization, current memory heap size, and so on would fall into this category. Existing messages include words like utilization value is, buffer size is, and number of threads is, for example:
IEE890I WTO Buffers in console backup storage = 1024
Table 13 shows the ReportSituation properties.
Table 13. ReportSituation properties
| Property name | Type | Description |
|---|---|---|
| reportCategory | xsd:string | This property specifies the category of the reported situation.
The reportCategory is a string with the following set of
values:
|
The CreateSituation deals with the situations documenting when a
component creates an entity. Messages telling that a document was
created, or a file was created, or an EJB was created all fall into this
category. Existing message include words like was created, about to
create, and now exists, for example:
ADMR0009I: Document cells/flatfootNetwork/applications/Dynamic Cache Monitor.ear/Dynamic Cache Monitor.ear was created
Table 14 shows the CreateSituation properties.
Table 14. CreateSituation properties
| Property name | Type | Description |
|---|---|---|
| successDisposition | xsd:string | This property specifies the success disposition of an operation of a
situation that caused the situation to be reported. The
successDisposition is a string with the following set of
values:
|
The DestroySituation deals with the situations documenting when
an entity or component was removed or destroyed. Messages telling that
a document was destroyed or a file was deleted all fall into this
category. Existing message include words like was created, about to
create, and now exists, for example:
CONM6007I: The connection pool was destroyed for data source (UDDI.Datasource.techs8.server1).
Table 15 shows the DestroySituation properties.
Table 15. DestroySituation properties
| Property name | Type | Description |
|---|---|---|
| successDisposition | xsd:string | This property specifies the success disposition of an operation of a
situation that caused the situation to be reported. The
successDisposition is a string with the following set of
values:
|
The FeatureSituation deals with the situations that announce that a feature of a component is now ready (or not ready) for service requests. Situations that indicate things like services being available and services or features being unavailable fall into this category. Existing situations include words like now available, currently available, and transport is listening on port 123, for example:
SRVE0171I: Transport HTTPS is listening on port 9443 MSGS0601I: WebSphere Embedded Messaging has not been installed
Table 16 shows the FeatureSituation properties.
Table 16. FeatureSituation properties
| Property name | Type | Description |
|---|---|---|
| featureDisposition | xsd:string | This property specifies the availability disposition of a feature of a
component that caused the situation to be reported. The
featureDisposition is a string with the following set of
values:
|
The DependencySituation deals with the situations that
components produce to say that they cannot find some component or feature that
they need. This category includes messages about not finding the
version of the component that was expected. Messages that say a
resource was not found, or that an application or subsystem that was
unavailable, also fall into this category. Existing messages include
words like could not find, and no such component, for example:
WSVR0017E: Error encountered binding the J2EE resource, Pet Store JMS Queue Connection Factory, as jms/queue/QueueConnectionFactory from resources.xml no resource binder found
Table 17 shows the DependencySituation properties.
Table 17. DependencySituation properties
| Property name | Type | Description |
|---|---|---|
| dependencyDisposition | xsd:string | This property specifies the dependency disposition of a feature of a
component that caused the situation to be reported. The
dependencyDisposition is a string with the following set of
values:
|
The OtherSituation category is to provide support for the situation that is product-specific requirement other than the predefined categories.
The ExtendedDataElement allows for application-supplied name-type-value collections to be specified for extensibility purposes. This is the mechanism by which other attributes not specified in the CommonBaseEvent data model can be added. Collections specified here are assumed to be product-specific data.
Table 18 is a summary of the properties for the ExtendedDataElement type. A detailed description of the ExtendedDataElement properties follows the summary table.
The named properties can be filtered, searched, or referenced by the correlation rules. The name is user-defined; however, the nonexclusive reserved keywords are as follows:
Table 18. ExtendedDataElement properties
| Property name | Type | Description |
|---|---|---|
| name | xsd:Name | The name of the extended data element. This name MUST be unique with respect to all other fields at the same level of extendedDataElement hierarchy, however, there might exist a child with the same name at different level or hierarchy. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters. |
| type | xsd:Name | The data type of the values specified in the values property.
Valid types are as follows:
|
| values | xsd:string[] | The array of values for this extended data element represented as a string of the specified type, excluding hexBinary. hexBinary values MUST be defined using the hexValue property. The hexValue and the values properties are mutually exclusive. Only one of these properties SHALL be defined. This is an OPTIONAL property. The string length for this property MUST NOT exceed 1024 characters. |
| hexValue |