All problem determination Common Base Events must provide human
readable text describing the specific event being reported within the msg
field of the Common Base Event. The text associated with events representing
actual messages or log entries is expected to be internationalized (in other
words, translated and localized). We strongly recommend including the msgDataElement
element in the Common Base Event whenever internationalized text is provided
in the event. This element provides information about how the message text
was created and how it should be interpreted, and is particularly invaluable
when trying to interpret the event programmatically or when trying to interpret
the message independent of the locale or language used to format the message
text.
Note: Readers of this section of the document should be familiar with
the concepts associated with creating internationalized messages (in other
words, messages that are translated and localized). A good source of education
on these concepts is provided by the documentation associated with internationalization
of Java information and the usage of resource bundles within the Java language.
The
msgDataElement element in the Common Base Event includes the following information
about the text (i.e. the value of the msg field) provided with an event:
- The locale of the supplied message text, which identifies how the locale-independent
fields within the message were formatted, as well as the language of the message
(msgLocale).
- A locale-independent identifier associated with the message that can be
used to interpret the message independent of the message language, message
locale, and how the message was formatted (msgId and msgIdType).
- Information on how a translated message was created, including:
- The identifier used to retrieve the message template (msgCatalogId).
- The name and type of message catalog used to retrieve the message template
(msgCatalog and msgCatalogType).
- Any locale-independent information that was inserted into the message
template to create the final message (msgCatalogTokens).
The Common Base Event specification [CBE101] provides information on
the required format of these fields and the Common Base Event Developer’s
Guide [CBEBASE] provides general usage guidelines. This section will provide
additional information about how to format and use these fields for problem
determination events, which should be used to clarify and extend the information
provided in the other documents.
- msg
- All message, log, and trace events must provide a human-readable message
in the msg field of the Common Base Event. The msg field is required for
problem determination events (both log events and diagnostic events). This
is more restrictive than the base specification for the Common Base Event,
which lists this as an optional field; because effective and efficient problem
determination requires the ability to quickly identify the condition being
reported by the event. The format and usage of this message is component-specific,
but the following general guidelines should be followed:
- The message text supplied with messages and log events is expected to
be internationalized.
- The locale of the supplied message text should be provided using the msgLocale
field in the msgDataElement element of the Common Base Event.
- Additional information regarding the format and construction of internationalized
messages should be provided whenever possible, using the msgDataElement element
of the Common Base Event.
- msgLocale
- The message locale should be provided whenever message text is provided
within the Common Base Event (as is the case with all problem determination
events). The msgLocale field is listed as an optional value within the Common
Base Event specification, but it should be provided within problem determination
events whenever it is available. The only reason this is not a required field
for problem determination events is there are instances where the locale information
is not provided or available when formatting the Common Base Event.
- msgId and msgIdType
- Several companies include within internationalized message text a locale-independent
identifier that can be used to interpret the condition being described by
the message text, independent of the language of the message. For example,
most messages issued by IBM software look like "IEE890I WTO Buffers in console
backup storage = 1024", where a unique, locale-independent identifier "IEE890I"
precedes the translated message text. This identifier provides a way to uniquely
detect and identify a message independent of the location (and language) where
it was issued, meaning it is invaluable for locale-independent and programmatic
analysis. The msgId field is listed as an optional value within the Common
Base Event specification, but it must be provided within problem determination
events whenever this identifier is included in the message text. Likewise,
the msgIdType field is listed as an optional value within the Common Base
Event specification, but it must be provided within problem determination
events whenever a value is supplied for msgId. These fields should not be
supplied when the message text has not been translated or localized, for example,
for trace events.
- msgCatalogId
- The msgCatalogId field is listed as an optional value within the Common
Base Event specification, but it should be provided whenever the Common Base
Event includes localized or translated message text, for example when providing
problem determination events representing issued messages or log events.
It is not a required field for problem determination events because not all
problem determination events include translated message text, and there are
cases where the value is not provided or available when formatting the Common
Base Event. This field should not be supplied when the message text has not
been translated or localized, for example, for trace events.
- msgCatalogTokens
- The msgCatalogTokens field is listed as an optional value within the
Common Base Event specification, but it should be provided whenever the Common
Base Event includes localized or translated message text, for example when
providing problem determination events representing issued messages or log
events. It is not a required field for problem determination events because
not all problem determination events include translated message text, and
there are cases where the value is not provided or available when formatting
the Common Base Event. This value contains the list of locale independent
values (message tokens) inserted into the localized message text when creating
a translated message. It is very difficult to extract these values from a
translated message without having knowledge of the translated message template
used to create the message, meaning having these values separate from the
message text is invaluable for locale-independent and programmatic analysis
of the data supplied in the message text. This field should not be supplied
when the message text has not been translated or localized, e.g. for trace
events. Note: The Common Base Event provides several mechanisms for providing
additional data about an event, including this field, extended
data elements, and extensions to the schema. The msgCatalogTokens field should
always be used to supply the list of message tokens included in the message
text associated with an event. These values can also be supplied in other
parts of the Common Base Event as well, but they must be included in this
field.
- msgCatalog and msgCatalogType
- The msgCatalog and msgCatalogType fields are listed as optional values
within the Common Base Event specification, but they should be provided whenever
the Common Base Event includes localized or translated message text, for example
when providing problem determination events representing issued messages or
log events. They are not required fields for problem determination events
because not all problem determination events include translated message text,
and there are cases where the values are not provided or available when formatting
the Common Base Event. These fields should not be supplied when the message
text has not been translated or localized, for example, for trace events.