The Common Base Event model is the new standard for events among the different types of enterprise applications. This standard proposes consistency of data elements that comprise these events, both in the elements themselves and in their format.
The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" are to be interpreted as described in RFC-2119 (See www.ietf.org/rfc/rfc2119.txt).
Formatted data is always in human readable form. All formatted data and string values MUST be encoded as UTF-8 string.
- The Common Base Event will only support 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. The data types are XML schema signed data types. See the related reference.
- byte
- short
- int
- long
- float
- double
- string
- dateTime
- duration
- hexBinary
- boolean
The maximum string length MUST never exceed 1024 characters. If a longer string is needed then you MAY choose a hexBinary type.
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, we recommend that all efforts be made to preserve as much of the
event data as possible.
All names and stings specified in this document are case sensitive.
The following properties, which identify the data that is collected for the situation 3-tuple constitute the Common Base Event:
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. However, once it is set, it stays constant for the life of the event. The value content of the localInstanceId MAY be a multi-part value, such a timestamp, location, offset, message ID; or MAY use other application-defined techniques for providing the content to ensure the uniqueness of the ID. For example, you may set the identifier to the concatenation of a string, giving the local host IP address, a string providing the absolute path of the access.log file, a string giving the local, fully qualified host name, a string giving the time stamp, and a string representing the sequenceNumber. The resulting String appears as:
9.27.11.27 mycomputer.toronto.ibm.com 20021009012534.002000-240_0
This property is not a key. This is an OPTIONAL property that is not mutable, that is, once it is set it cannot be changed. It MAY be provided by the component issuing the event or assigned by the consumer of the event. The maximum 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 Globally Unique Identifier (GUID) that is at least 128 bits in length but not greater than 256 bits. It is incumbent upon the GUID generation algorithm to insure the uniqueness of this value.
This is an OPTIONAL property, however when it is specified it is not mutable, that is, once it is set, it cannot be changed for the life of the event. The globalInstanceId may be provided either by the component issuing the event or by the consumer of the event.
The globalInstanceId is required to establish associations between events. If globalInstanceId is not specified the association, as described by AssociatedEvent, cannot be provided.
The date and time the event was created MUST be specified as defined by the XML schema dateTime data type. The value of the creationTime MUST provide granularity as precisely as the generating platform allows.
This is a REQUIRED property, which is not mutable and MUST be provided by the component reporting the event. When it is set, it cannot be changed for the life of the event
The severity indicates the severity level of the status the event is describing, with respect to the application that reports the event. The meanings of the values the property may contain may be described by an enumeration of common values or qualifiers, indicating the severity level of the event. For example, information, warning, or some integers mapping into the intended severity levels are all valid values. This document does not imply any specific implementation, but instead suggests the following values with the understanding that users of this field may add additional values as their implementations dictate. This field simply helps define the seriousness of the kind of situation that was encountered and helps to enable administrators to focus on the most severe problems currently occurring in the enterprise.
The following predefined severity levels are listed in order of increasing severity:
The values are 0 to 70. The reserved values start at 0 for Unknown and increase by increments of 10, up to 60 for Fatal. Other severities MAY be added but MUST NOT exceed 70. If no value is specified, then this event is interpreted as having no severity, which is the equivalent of "NONE".
This is an OPTIONAL property and it 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 records should be processed. The following priorities are predefined:
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, which is the equivalent of "NONE".
The priority property is separate and apart from severity, in that priority is intended to be more of a consumer-driven property, where severity dictates 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 for uniquely identifying a component.
It is a REQUIRED property if the reporting component is different from the source component. Otherwise, this field MUST be omitted. This property is not mutable, that is, once it is set, it cannot be changed.
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 for uniquely identifying 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 be omitted.
The situationType specifies the type of the situation that caused the event to be reported. This is an extensible string value.
Proposed reserved keywords are:
This is an OPTIONAL property, which it is not mutable.. The maximum string length for situationType MUST NOT exceed 512 bytes.
The contextDataElements is an array of contexts of type ContextDataElement that this event references. This property holds data that is used to assist with correlating messages or events generated along the execution path of a unit of work for problem diagnostics.
This is an OPTIONAL property and mutable. It may be provided by the component issuing 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 that is rendered for a specific locale.
The locale of the msg property is specified by the msgLocale property of the MsgDataElement type. There is no default value for the msg locale.
This property is OPTIONAL but RECOMMENDED to have a value if the msgCatalogId and msgCatalog properties of the MsgDataElement do not specify a value.
The msgDataElement is a property that references 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 non-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, which is described in the next section, it is recommended you specify a value for the extensionName.
This is an OPTIONAL property, which is not mutable and MUST be provided by the component reporting the event. If the value specified is null, then the value is assumed to be "CommonBaseEvent".
extendedDataElements and extendedProperties
The extendedDataElements property is a sequence of name elements of type
ExtendedDataElement. It is to
be used for extensibility by
providing a location to specify any other attributes not accounted for in the
CommonBaseEvent data model. Information placed here is assumed to be
product-specific data.
This property is one that you can supply, and named elements can be filtered, searched on, or referenced by the correlation rules.
This is an OPTIONAL property that is mutable. That is, after it is set it may be changed. The value for this property may be provided by the component issuing the event or assigned by the consumer of the event.
The associatedEvents property allows for non restricted grouping of events or parent-child relationship. This property is a complex type that is made up of globalInstanceIds identifying the associated events along with a type field describing the type of association that is represented by the name of the association.
This is an OPTIONAL property that is mutable. That is, after it is set it may be changed. The value for this property may be provided by the component issuing the event or assigned by the consumer of the event.
The repeatCount is the number of occurrences of a given event for a specific time interval. The time interval is indicated by the elapsedTime property described below. The definition of what makes an event a repetition of a previously issued event is application-specific and therefore not defined by this specification.
This property is OPTIONAL and mutable. The repeatCount may be set by the component issuing the event or the consumer of the event. There is no default value. A value of 0 or no value indicates no repeat of the event.
The elapsedTime is the time interval or the elapsed time for some number of occurrences of a specific event. The number of occurrences is specified by the value of the repeatCount . This value indicates the duration of the time within which the repeated events were observed.
The value of this property MUST be expressed in microseconds granularity.
This property is OPTIONAL and mutable. However, if the repeatCount is specified then an elapsed time must be present. The elapsedTime may 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 is different from the order in which they arrived at the consumer's location (for example, an event server or management tools). The sequence number helps consumers to sort arrived messages. This is with respect to time and to the particular provider of the event.
This property is OPTIONAL and it is not mutable once it is set. There is no default value.
ComponentIdentification Description
In problem reporting, there are two general categories of components that should be considered for problem diagnosis: the component observing and reporting the situation (reporter), and the actual component that is experiencing the situation (affected). Component identification provides a collection of attributes that are required to uniquely identify a component. The same data is used to identify both the component that is reporting an event or situation and the component that is affected or experiencing the situation. In some cases, these components will be the same.
For example, in a typical information technology environment, commonly, the activities of applications running in that environment are often monitored using events that are received or collected from the applications by means of either management agents or adapters.
Example 1: Consider the case where a WebSphere application, called myWebApp, times out on a table query due to a DB2 server problem that is located on a remote system. The web application then issues an event indicating the failure situation. In this case, myWebApp is the "affected" or the "source" component.
Example 2: Consider a case where there is application X running on a Windows server. The application encounters an error and adds an entry to the Windows error log. Then there is a separate application (an adapter) that reads messages from the error log and generates a common base event and submits it. In this case, the "affected" or the "source" of the event is the application X and the reporting component is the adapter that generated and submitted the event.
A detailed description of the ComponentIdentification type follows.
The location specifies the physical address that corresponds to the location of a component. For example, a hostname, IP address, VTAMR LU. The format of the value of the location is specified by the locationType property. The preferred value is a fully qualified hostname.
This property is REQUIRED and it is not mutable. That is, once it is set it cannot be changed. The maximum string length for location MUST NOT exceed 256 characters.
This property specifies the format and meaning of the value in the location property. This property has the following well-known, reserved keywords:
The default value is "Unknown". This property is REQUIRED and not mutable. That is, once it is set it cannot be changed. The maximum string length for locationType MUST NOT exceed 32 characters.
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.
This is an OPTIONAL property and it is not mutable. That is, once it is set it cannot be changed. The maximum 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. The maximum string length for executionEnvironment MUST NOT exceed 256 characters.
This is an OPTIONAL property and it is not mutable. That is, once it is set it cannot be changed for the life of the event.
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 V7.1). This value SHOULD be unique within the scope specified by the reporter location.
This property is REQUIRED and it is not mutable. That is, once it is set it cannot be changed for the life of the event. The maximum string length for the component name MUST NOT exceed 256 characters.
The subComponent specifies a further delineation for the logical component property of the event.
It SHOULD contain the identity of the subcomponent of the component property and should be the most granular definition specified in the event. This property can 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.
This property is REQUIRED and it is not mutable. That is, once it is set it cannot be changed for the life of the event. The maximum string length for the subComponent name MUST NOT exceed 512 characters.
The componentIdType specifies the format and meaning of the component that
is identified by this componentIdentification. The reserved, nonexclusive list
of keywords for this property are:
This property is REQUIRED and it is not mutable. The maximum 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. That is, Grid Service Handle(GSH), EJBHandle.
This property is OPTIONAL that is not mutable. That is, once it is set it cannot be changed. The maximum 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.
This is an OPTIONAL property that is not mutable. That is, once it is set it cannot be changed. The maximum 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 carry its function and incoming requests. Therefore, the thread ID will change accordingly.
This is an OPTIONAL property that is not mutable. That is, once it is set it cannot be changed. The maximum string length for threadId MUST NOT exceed 64 characters.
ExtendedDataElement Description
The ExtendedDataElement allows you to supply name-type-value collections to be specified for extensibility purposes. This is where you can include any other attributes that are not accounted for in the CommonBaseEvent data model. Collections specified here are assumed to be product-specific data.
The named properties can be filtered, searched on, or referenced by the correlation rules. The "name" is defined by you, however, the nonexclusive list of reserved keywords are as follows:
RawData - This keyword is indicative of "as is" data that is usually in a format that may be proprietary to the producer of such data. It may be in any form including binary. It is intended to allow the data to be retrieved verbatim, and to support tools that understand the format of the context.
RootHeader - This keyword is intended to identify the root ExtendedDataElement for a hierarchy of the ExtendedDataElements that are defined by the dataRefs.
The detailed description of the ExtendedDataElement type is as follows:
The name property specifies the name of the ExtendedDataElement. This name MUST be unique with respect to all other properties in the event (for example, RawData, msgLocale, and EventStatus).
This property is REQUIRED and it is not mutable.
The data type of the values specified in the values property below.
Valid types are as follows:
The above data types are the only valid types supported by the ExtendedDataElement type. The default value is "string".
This property is REQUIRED and is not mutable.
An array of values for this extended data element of the type defined by the type property described above.
This property is OPTIONAL and it is mutable. It MUST NOT be specified if the "value" or the "hexValue" property is specified.
The hexValues property is an array of bytes that holds the data for any other data type or complexType that is not in the supported list of types defined above.
This property is OPTIONAL and it is not mutable. It MUST NOT be specified if the "values" or the "value" property is specified.
Note: The hexValue and values properties are mutually
exclusive. Only one of these two properties can be defined.
The children property refers to other ExtendedDataElement(s) to specify a structured list of ExtendedDataElement's. This list allows for the creation of a hierarchy of related ExtendedDataElement's corresponding to a specific group of CommonBaseEvents. Accordingly, this is an efficient and quick way to get access to the list of related ExtendedDataElement's without having to look through and examine all the ExtendedDataElement's.
This property is OPTIONAL and it is mutable.
ContextDataElement Description
The ContextDataElement type defines one or more contexts that this event references. This complex type holds data that is used to assist with correlating messages or events generated along the execution path of a unit of work for problem diagnostic purposes.
The following table provides a summary of the data properties representing a context in the common base event. A detailed description of this ContextDataElement follows the summary table
A detailed description of the contextDataElement is as follows:
This is the data type of the context. This type should allow the consumer of the event to recognize the format of the context value. The type is application-specific (for example, PD_LogRecordCorrelator).
This property is REQUIRED and not mutable.
This is the name of the application that created this context data element (for example, Correlation engine).
This property is REQUIRED and not mutable.
This is the value of the context with respect to the implementation of the context.
This property is not required if contextId specifies a value and it
is not mutable.
This property is the reference to the element that contains a product- or user-specific context.
This property is not required if contextValue specifies a value; and it is not mutable. It MUST NOT be specified if the contextValue property is specified.
Note: The contextValue and the contextId are mutually exclusive, only one of
these two properties can be defined. However, if contextValue is set to a value
the contextId is ignored.
AssociatedEvent Description
The AssociatedEvent type allows for the grouping of events. It allows identifying associated events and its associationEngine.
The detailed description for the AssociatedEvent type is as follows:
This is a reference to the AssocationEngine that created this AssociatedEvent.
This property is REQUIRED and not mutable once it is set.
An array of globalInstanceIds that correspond to the events that are associated with this event
This is a REQUIRED property that is mutable and is provided by the
association engine, which is specified by the name property.
AssociatedEvent Description
The AssociationEngine element allows for the identification of associated events, this complex type also provides properties to describe the type of the association. It is represented by its own standalone entity in the XML schema and the AssociatedEvent elements are referring to it.
The detailed description for the AssociationEngine type is as follows:
Name of the application that will create the association (e.g,. my correlation engine name).
This property is REQUIRED and not mutable once it is set.
This property should contain the type of association created by this AssociationEngine.
Some well defined associations are:
Reserved keyword values include:
This property is REQUIRED and not mutable when it is set for a specific "name" property.
The primary identifier for the element. This property MUST be globally unique. The recommend value for this is either a 128 bit or 256 bit Globally Unique Id (represented as hex string). Once this value is set it MUST never be changed.
This is a REQUIRED property that is not mutable.
MsgDataElement Description
This MsgDataElement represents the data that is used to specify all the related information that is associated with the message that this event holds.
The msgId property specifies the message identifier for the event. This identifier is commonly a unique value string of alphanumeric or numeric characters. It can be as simple as string of numeric characters that identifies a message in a message catalog or a multi-part string of alphanumeric characters (for example, DBT1234E). The format of the content of the msgId is specified by the msgIdType property as described in the next section.
This is an OPTIONAL property, which is not mutable once it is set and should be provided by the component issuing the event. The maximum string length for the msgId property MUST NOT exceed 256 characters.
The msgIdType property specifies the meaning and format of the msgId. If the ID conforms to, or represents a standard or a well-known convention, it is named by this property. For example IBM3.4.1 implies a message ID of a 3 part, 8-character string identifier, consisting of 3 alphabetic characters representing a component, followed by 4 numeric characters, and suffixed with one alphabetic character (for example, DBT2359I). Other similar reserved keywords are IBM3.4, IBM4.4, IBM3.1.4, IBM3.4.1, IBM4.4.1, and IBM3.1.4.1.
The current nonexclusive list of reserved keywords includes:
This is a OPTIONAL property that is not mutable once it is set and should be provided by the component issuing the event. It must be provided if msgId property is specified. The maximum string length for the msgIdType property MUST NOT exceed 32 characters.
The msgLocale property specifies the locale that the msg is rendered in. Its value is a locale code in conformance with the IETF RFC 1766 specifications. For example, en-US is the value for United States English.
This property is OPTIONAL and it is not mutable once it is set. If msgLocale is specified then it is up to the consumer of the event to decide the locale.
The maximum string length per msgLocale MUST NOT exceed 5 characters.
The msgCatalogTokens property consists of an array of string values that is for holding substitution data used for resolving an NLS-based message into fully formatted text. The order of the values is implied by the implicit order of the array elements. The locale of the tokens should be the same as the locale of the message text as defined by msgLocale.
This property is OPTIONAL and it is not mutable once it is set. If there are no substitution values, then this property does not need to be specified. The maximum string length of the msgCatalogTokens property MUST NOT exceed 256 bytes.
The msgCatalogId property is the index or the identifier for a message that is used for resolving the message text from a message catalog.
This property is OPTIONAL and it is not mutable once it is set.
The msgCatalog property is the qualified name of the message catalog that contains the translated message that is specified by the msgCatalogId.
This property is OPTIONAL and it is not mutable once it is set. The maximum string length for the msgCatalog property MUST NOT exceed 128 characters.
The msgCatalogType property specifies the meaning and format of the msgCatalog. The current nonexclusive list of reserved keywords includes:
This property is OPTIONAL and it is not mutable once it is set and MUST be
provided if msgCatalog property is defined. The maximum string length for
the msgCatalogType property MUST NOT exceed 32 characters.
Related concepts
Common Base Event model
Related reference
Common Base Event XML schema specification
(C) Copyright IBM Corporation 2000, 2003. All Rights Reserved.