Common Base Event 模型是各種類型的企業應用程式間之事件的新標準。這個標準提供了構成這些事件之資料元素在元素本身以及其格式的一致性。
關鍵字 "必須 (MUST)"、"不可 (MUST NOT)"、"必要 (REQUIRED)"、"將會 (SHALL)"、"不會 (SHALL NOT)"、"應該 (SHOULD)"、"不應該 (SHOULD NOT)"、"建議 (RECOMMENDED)"、"可以 (MAY)" 和 "選用 (OPTIONAL)" 會依照 RFC-2119 的說明(請參閱 www.ietf.org/rfc/rfc2119.txt)來解釋。
格式化的資料一定是可供閱讀的格式。所有格式化的資料和字串值都「必須」編碼成 UTF-8 字串。
- Common Base Event 只支援下列 XML 綱目資料類型的子集,以及這些類型的陣列變異。這些資料類型的說明位於 XML 綱目規格中。這些資料類型為 XML 綱目的簽章資料類型。請參閱相關參照。
- byte
- short
- int
- long
- float
- double
- string
- dateTime
- duration
- hexBinary
- boolean
最大字串長度「必須」不超出 1024 個字元。如果需要較長的字串,您「可以」選擇 hexBinary 類型。
我們已根據已知使用者的相關經驗資料,以及事件處理程序和儲存體的限制,來指定欄位長度,以確保最大的可接受度以及精確度。不過,傳送端可能有時候會超出這些長度限制。在這個情況下,事件的使用者有責任採取適當的動作,一則依其現狀接受該事件,再則調整它以符合規格,或是將它視為無效加以捨棄。不過,
即使資料不符合這個事件規格,通常保留資料還是比遺失整個事件來得好。因此,建議您盡最大努力來儘可能保留事件資料。
這份文件中指定的所有名稱和字串都會區分大小寫。
構成 Common Base Event 的內容如下,其會識別 3-tuple 狀況所收集的資料:
localInstanceId 為字串類型,且用來在本端環境下識別事件的實例。這個值並不隱含保證在全域都是唯一的。不過,一旦設定,在事件的活動期間它都會保持不變。localInstanceId 值的內容「可以」是多部份格式的值,如時間戳記、位置、偏移、訊息 ID;也「可以」使用其他應用程式定義的技術來提供內容,以確保 ID 的唯一性。比方說, 您可以設定字串連接的 ID、提供本端主機 IP 位置、提供 access.log 檔絕對路徑的字串、提供本端完整主機名稱的字串、提供時間戳記的字串,以及代表 sequenceNumber 的字串。產生的字串看起來如下:
9.27.11.27 mycomputer.toronto.ibm.com 20021009012534.002000-240_0
這個內容並不是主要內容。它是「選用」的內容且不可改變,也就是說,它一旦設定就不會變更。它「可以」由發出事件的元件來提供, 或是由事件的使用者指派。localInstanceId 的字串長度上限「不可」超過 128 個字元。
globalInstanceId 是一個複式資料類型,其代表事件的主要 ID。這個內容會在全域唯一地識別事件, 且「可以」用做事件的主要索引鍵。這個值「必須」是「全域唯一 ID」(GUID),且長度至少為 128 個位元但不大於 256 個位元。系統是倚賴 GUID 產生演算法來確保這個值的唯一性。
這是「選用」的內容,不過,它在指定之後就不會變更,也就是說,它一旦設定,在事件的活動期間都不可改變。globalInstanceId 可以由發出事件的元件來提供,或是由事件的使用者提供。
globalInstanceId 對建立事件之間的關聯是必要的。如果未指定 globalInstanceId,就無法依照 AssociatedEvent 的說明提供關聯。
建立事件的日期和時間「必須」依照 XML 綱目的 dateTime 資料類型來指定。creationTime 的值提供的精度「必須」和產生平台允許的一樣精確。
這是「必要」的內容,它不可改變,且「必須」由報告事件的元件來提供。它一旦設定,在事件的活動期間都不可改變。
severity 指出事件說明的狀態對於報告事件的應用程式的嚴重性層次。內容可包含之值的意義,可由通用值或限定元的列舉來說明, 以指出事件的嚴重性層次。比方說,資訊、警告或對映到預期嚴重性層次的一些整數,都是有效的值。這份文件不隱含任何特定的實作方式,而是建議下列的值,並瞭解這個欄位的使用者可以依照其實作要求,指定其他的值。這個欄位只是要協助您定義所發生之各種狀況的嚴重性, 並可讓管理者著重在企業中目前發生的最嚴重的問題。
以下依照嚴重性遞增的順序,列出預先定義的嚴重性層次:
這些值從 0 到 70。保留的值從 0 代表不明開始, 並且以 10 的增量遞增,直到 60 代表危險為止。您「可以」新增其他嚴重性但「不可」超過 70。如果未指定值,這個事件會解譯成沒有嚴重性,相當於 "無"。
這是「選用」的內容,它一旦設定就不可改變。severity 沒有預設值。
priority 會定義事件的重要性,以及處理記錄的相對順序。預先定義的優先順序如下:
這些值從 0 到 100。保留的值為 10 代表「低」、50 代表「中」、70 代表「高」。您「可以」新增其他優先順序但「不可」超過 100。
如果未指定值,這個事件會解譯成沒有優先順序,相當於 "無"。
priority 內容和 severity 是獨立且分開的,priority 比較像是使用者驅動的內容, 而 severity 則代表受影響的元件察覺到的狀況的狀態。比方說,優先順序為「高」且嚴重性為「次要」的事件,應該比優先順序為「低」且嚴重性為「嚴重」的事件先行處理。
這是「選用」的內容且可改變。priority 沒有預設值。
reporterComponentId 會識別代替受影響的元件來報告事件或狀況的元件。這個內容的資料類型為 ComponentIdentification 類型所說明的複式類型, 其提供唯一識別元件所需的資料。
如果報告元件和來源元件不同,它就是「必要」的內容。否則,這個欄位「必須」省略。這個內容不可改變,也就是說,它一旦設定就不能變更。
sourceComponentId 會識別受事件或狀況影響的元件。這個內容的資料類型為 ComponentIdentification 類型所說明的複式類型, 其提供唯一識別元件所需的資料。
這個內容是「必要」的且不可改變。事件的產生者「必須」提供 sourceComponentId。如果報告者和受影響的元件相同,則 reporterComponentId「必須」省略。
situationType 係指定導致報告事件的狀況類型。這是個可繼承的字串值。
建議的保留關鍵字如下:
這是「選用」的內容且不可改變。situationType 的字串長度上限「不可」超過 512 個位元組。
contextDataElements 是這個事件所參照且類型為 ContextDataElement 的環境定義陣列。這個內容包含的資料會用來協助相互關聯產生的訊息或事件,以及問題診斷之工作單元的執行路徑。
這是「選用」的內容且可改變。它可以由發出事件的元件來提供,也可以由事件的使用者指派。
msg 內容是伴隨事件的文字。這通常是經過解析且為可供閱讀格式的訊息字串, 它會根據特定語言環境來呈現。
msg 內容的語言環境係由 MsgDataElement 類型的 msgLocale 內容指定。msg 語言環境沒有預設值。
這個內容是「選用」的,但如果 MsgDataElement 的 msgCatalogId 和 msgCatalog內容未指定值,則「建議」它有值。
msgDataElement 是個參照 MsgDataElement 的內容。這個內容包含的資料會用來指定和這個事件包含之訊息相關聯的所有相關資訊。
這是「選用」的內容且不可改變。它是由發出事件的元件所提供。
extensionName 內容包含這個事件所代表之「事件類別」的名稱(例如:Trace、CommonBaseEvent)。事件類別名稱代表特定事件內預期存在的任何其他內容。如果您選擇要使用 ExtendedDataElement(說明於下一節中),建議您指定 extensionName 的值。
這是「選用」的內容,它不可改變且「必須」由報告事件的元件來提供。如果指定的值為空值,則值會假設為 "CommonBaseEvent"。
extendedDataElements 和 extendedProperties
extendedDataElements 內容是 ExtendedDataElement 類型之名稱元素的順序。它係用於延伸性,方法是
提供位置來指定 CommonBaseEvent 資料模型中未說明的任何其他屬性。這裡放置的資訊會假設是產品特定的資料。
這個內容是您可以提供的內容,且可以由相互關係規則來過濾、搜尋或參照具名的元素。
這是「選用」的內容且可改變。也就是說,它在設定之後還可以變更。這個內容的值可以由發出事件的元件提供, 或是由事件的使用者指派。
associatedEvents 內容允許無限制地群組事件或母項-子項關係。這個內容是個組成 globalInstanceIds 的複式類型, 其識別相關聯的事件以及一個類型欄位,該欄位會說明由關聯名稱所代表的關聯類型。
這是「選用」的內容且可改變。也就是說,它在設定之後還可以變更。這個內容的值可以由發出事件的元件提供, 或是由事件的使用者指派。
repeatCount 是給定事件在特定時間間隔內的發生次數。時間間隔係由以下說明的 elapsedTime 內容指定。使事件成為之前發出之事件的重複項目的定義,是特定應用程式專用的,因此不是由這個規格所定義。
這個內容是「選用」的且可改變。repeatCount 可以由發出事件的元件或是由事件的使用者來設定。它沒有預設值。0 的值或沒有值表示不重複事件。
elapsedTime 是特定事件發生一些次數的時間間隔或經歷時間。發生次數係由 repeatCount 的值指定。這個值表示觀察重複事件的期間。
這個內容的值「必須」以微秒精度表示。
這個內容是「選用」的且可改變。不過,如果指定了 repeatCount,則經歷時間必須存在。elapsedTime 可由設定 repeatCount 的同一元件來設定。elapsedTime 沒有預設值。
sequenceNumber 是個來源定義的號碼,其允許在一個邏輯順序(不同於到達使用者位置的順序,例如:事件伺服器或管理工具)中傳送和處理多則訊息。序號可協助使用者排序到達的訊息。這和事件的時間以及特定提供者有關。
這個內容是「選用」的,它一旦設定就不可改變。它沒有預設值。
在問題報告中,於問題診斷時應考量兩種一般種類的元件: 觀察和報告狀況的元件(報告者),以及遇到狀況的實際元件(受影響者)。元件識別提供了唯一識別元件所需的屬性集合。同樣的資料會用來識別報告事件或狀況的元件,以及受影響或遇到狀況的元件。在某些情況下,這些元件會是相同的。
比方說,在一般的資訊技術環境下,在該環境下執行的應用程式活動通常會藉由管理代理程式或配接器,利用從應用程式收到或收集的事件來監視。
範例 1:假設有一個稱為 myWebApp 的 WebSphere 應用程式在表格查詢時,由於遠端系統上發生 DB2 伺服器問題而逾時。Web 應用程式接著會發出一個事件,指出失敗狀況。在本例中,myWebApp 是「受影響」或「來源」元件。
範例 2:假設有一個應用程式 X 在 Windows 伺服器中執行。該應用程式發現錯誤,並將一個項目加入 Windows 錯誤日誌中。接著另一個應用程式(配接器)從錯誤日誌中讀取訊息,並產生及送出 Common Base Event。在本例中,事件的「受影響」或「來源」元件為應用程式 X,而報告元件為產生及送出該事件的配接器。
以下為 ComponentIdentification 類型的詳細說明。
location 指定對應於元件位置的實際位址。例如:主機名稱、IP 位址、VTAM LU。location 值的格式係由 locationType 內容指定。您最好指定完整的主機名稱。
這個內容是「必要」的且不可改變。也就是說,它一旦設定就不能變更。location 的字串長度上限「不可」超過 256 個字元。
這個內容指定 location 內容值的格式和意義。這個內容有下列已知的保留關鍵字:
預設值為 "Unknown"。這個內容是「必要」的且不可改變。也就是說,它一旦設定就不能變更。locationType 的字串長度上限「不可」超過 32 個字元。
application 內容指定應用程式的使用者名稱(例如:myApp)。應用程式的版本資訊可以附加在元件最後,以 # 字元區隔。
這是「選用」的內容且不可改變。也就是說,它一旦設定就不能變更。application 的字串長度上限「不可」超過 256 個字元。
executionEnvironment 內容識別應用程式在其中執行的立即環境。比方說,WebSphere Application Server 名稱:cell:node:server。
executionEnvironment 的版本資訊可以附加在元件最後,以 # 字元區隔。executionEnvironment 的字串長度上限「不可」超過 256 個字元。
這是「選用」的內容且不可改變。也就是說,它一旦設定,在事件的活動期間都不能變更。
component 指定元件的邏輯身分。這個內容「必須」包含特定應用程式、產品或子系統的名稱(例如:IBM DB2 V7.1)。這個值在報告者位置指定的範圍內「應該」是唯一的。
這個內容是「必要」的且不可改變。也就是說,它一旦設定,在事件的活動期間都不能變更。component 名稱的字串長度上限「不可」超過 256 個字元。
subComponent 指定事件之邏輯元件內容的進一步描述。
它「應該」包含元件內容之子元件的身分,且應該是事件中所指定的最精確的定義。這個內容可以是應用程式或作業系統資源之各種組件的其中一個, 例如:模組名稱、類別名稱、類別和方法名稱。
這個內容是「必要」的且不可改變。也就是說,它一旦設定,在事件的活動期間都不能變更。subComponent 的字串長度上限「不可」超過 512 個字元。
componentIdType 指定由這個 componentIdentification 所識別之元件的格式和意義。這個內容的保留(但非專屬)關鍵字清單如下:
這個內容是「必要」的且不可改變。componentIdType 的字串長度上限「不可」超過 32 個字元。
instanceId 指定由 component 內容所指定之元件實例的控點或 ID。亦即,Grid Service Handle(GSH)、EJBHandle。
這個內容是「選用」的且不可改變。也就是說,它一旦設定就不能變更。instanceId 的字串長度上限「不可」超過 128 個字元。
processId 為字串類型,其識別產生事件之「執行中」元件或子元件的程序 ID。
這是「選用」的內容且不可改變。也就是說,它一旦設定就不能變更。processId 的字串長度上限「不可」超過 64 個字元。
threadId 內容為字串類型,且會識別由產生事件的程序 ID 所指出之元件或子元件的執行緒 ID。執行中的程序可以產生一或多個執行緒來處理其功能和送入的要求。因此,執行緒 ID 會據以變更。
這是「選用」的內容且不可改變。也就是說,它一旦設定就不能變更。threadId 的字串長度上限「不可」超過 64 個字元。
ExtendedDataElement 可讓您提供要指定的名稱-類型-值的集合以供延伸之用。您可在這裡併入 CommonBaseEvent 資料模型中未說明的任何其他屬性。這裡指定的集合會假設是產品特定的資料。
這些具名的內容可以由相互關係規則來過濾、搜尋或參照。這個「名稱」係由您定義,不過,保留關鍵字的非專屬清單如下:
RawData - 這個關鍵字代表「依其現狀」的資料,其格式通常是這類資料的產生者所專用。它可以是任何格式,包括二進位碼。這些資料可以逐項擷取,並且支援瞭解其環境定義格式的工具。
RootHeader - 這個關鍵字可以用來識別由 dataRefs 所定義之 ExtendedDataElements 階層的根 ExtendedDataElement。
ExtendedDataElement 類型的詳細說明如下:
name 內容指定 ExtendedDataElement 的名稱。這個名稱對事件中所有其他有關的內容(例如:RawData、msgLocale 和 EventStatus)而言「必須」是唯一的。
這個內容是「必要」的且不可改變。
以下是 values 內容中指定之值的資料類型。
有效的類型如下:
上述資料類型是 ExtendedDataElement 類型唯一支援的有效類型。預設值為 "string"。
這個內容是「必要」的且不可改變。
由上述 type 內容所定義之類型的這個延伸資料元素的值陣列。
這個內容是「選用」的且可改變。如果指定了 "value" 或 "hexValue" 內容,則「不可」指定這個內容。
hexValues 內容是個位元組陣列,其包含不在上述支援的類型清單中,任何其他資料類型或 complexType 的資料。
這個內容是「選用」的且不可改變。如果指定了 "values" 或 "value" 內容,則「不可」指定這個內容。
注意事項:hexValue 和 values 內容是互斥的。您只能定義這兩個內容的其中一個。
children 內容會參照其他 ExtendedDataElement 來指定 ExtendedDataElement 的結構化清單。這個清單可讓您建立對應於一組特定 CommonBaseEvent 之相關 ExtendedDataElement 的階層。因此,這是個有效且快速的方式來取得相關 ExtendedDataElement 清單的存取權, 而不需察看及檢查所有的 ExtendedDataElement。
這個內容是「選用」的且可改變。
ContextDataElement 說明
ContextDataElement 類型會定義這個事件所參照的一或多個環境定義。這個複式類型包含的資料會用來協助相互關聯產生的訊息或事件,以及用於問題診斷之工作單元的執行路徑。
下表提供了代表 Common Base Events 中之環境定義的資料內容摘要。摘要表之後為這個 ContextDataElement 的詳細說明。
contextDataElement 的詳細說明如下:
這是環境定義的資料類型。這個類型應該可讓事件的使用者辨識環境定義值的格式。這個類型是特定應用程式專用的(例如:PD_LogRecordCorrelator)。
這個內容是「必要」的且不可改變。
這是建立這個環境定義資料元素的應用程式名稱(例如:Correlation engine)。
這個內容是「必要」的且不可改變。
這是和環境定義實作有關的環境定義值。
這個內容不可改變,且如果 contextId 指定了一個值,則這個內容不是必要的。
這個內容是對元素的參照,元素中包含產品或使用者專用的環境定義。
這個內容不可改變;且如果 contextValue 指定了一個值,則這個內容不是必要的。如果指定了 contextValue 內容,則「不可」指定這個內容。
注意事項:contextValue 和 contextId 是互斥的,您只能定義這兩個內容的其中一個。不過,如果 contextValue 設定了一個值,則會忽略 contextId。
AssociatedEvent 說明
AssociatedEvent 類型可讓您群組事件。它可以識別相關聯的事件和其 associationEngine。
AssociatedEvent 類型的詳細說明如下:
這是建立這個 AssociatedEvent 的 AssocationEngine 參照。
這個內容是「必要」的,且一旦設定就不可改變。
對應於和這個事件相關聯之事件的 globalInstanceIds 陣列。
這是「必要」的內容且可改變,其係由 name 內容所指定的關聯引擎所提供。
AssociatedEvent 說明
AssociationEngine 元素可以識別相關聯的事件, 這個複式類型也提供一些內容來說明關聯的類型。它在 XML 綱目中係由其自己的獨立實體來表示, 且 AssociatedEvent 元素會參照它。
AssociationEngine 類型的詳細說明如下:
會建立關聯之應用程式的名稱(例如:my correlation engine name)。
這個內容是「必要」的,且一旦設定就不可改變。
這個內容應包含由這個 AssociationEngine 所建立的關聯類型。
一些已定義好的關聯如下:
保留的關鍵字值包括:
這個內容是「必要」的,且一旦針對特定的 "name" 內容設定就不可改變。
元素的主要 ID。這個內容「必須」是全域唯一的。建議的值為 128 位元或 256 位元的「全域唯一 ID」(以十六進位字串表示)。這個值在設定之後,就「必須」永不變更。
這是「必要」的內容且不可改變。
MsgDataElement 說明
這個 MsgDataElement 代表的資料會用來指定和這個事件包含之訊息相關聯的所有相關資訊。
msgId 內容會指定事件的訊息 ID。這個 ID 通常是唯一的值,且是英數字或數字字串。它可以是識別訊息目錄中某一訊息的簡單數字字串,或是英數字元的多組件字串(例如:DBT1234E)。msgId 的內容格式係由下一節中說明的 msgIdType 內容所指定。
這是「選用」的內容,它一旦設定就不可改變,且應該由發出事件的元件來提供。msgId 內容的字串長度上限「不可」超過 256 個字元。
msgIdType 內容會指定 msgId 的意義和格式。如果 ID 符合或代表標準或已知的慣例,它會由這個內容命名。比方說,IBM3.4.1 隱含地表示訊息 ID 是具有 3 個組件、8 個字元的字串 ID,其包含 3 個英文字母代表元件,後面接著 4 個數字字元,且字尾為一個英文字母(例如:DBT2359I)。其他類似的保留關鍵字有 IBM3.4、IBM4.4、IBM3.1.4、IBM3.4.1、IBM4.4.1 和 IBM3.1.4.1。
現行保留關鍵字的非專屬清單包括:
這是「選用」的內容,它一旦設定就不可改變,且應該由發出事件的元件來提供。如果指定了 msgId 內容,就必須提供這個內容。msgIdType 內容的字串長度上限「不可」超過 32 個字元。
msgLocale 內容會指定呈現 msg 的語言環境。它的值是符合 IETF RFC 1766 規格的語言環境碼。比方說,en-US 是代表「美國英文」的值。
這個內容是「選用」的,它一旦設定就不可改變。如果指定了 msgLocale,事件的使用者就必須負責決定語言環境。
每一 msgLocale 的字串長度上限「不可」超過 5 個字元。
msgCatalogTokens 內容係由字串值的陣列所組成,該陣列會用來保存用於將 NLS 型的訊息,解析成完整格式化文字的替代資料。值的順序係由陣列元素隱含的順序所指定。記號的語言環境應該和 msgLocale 所定義之訊息文字的語言環境相同。
這個內容是「選用」的,它一旦設定就不可改變。如果沒有替代值,就不需要指定這個內容。msgCatalogTokens 內容的字串長度上限「不可」超過 256 個位元組。
msgCatalogId 內容是一則訊息的索引或 ID,用來解析訊息目錄中的訊息文字。
這個內容是「選用」的,它一旦設定就不可改變。
msgCatalog 內容是訊息目錄的完整名稱,其包含 msgCatalogId 所指定之翻譯後的訊息。
這個內容是「選用」的,它一旦設定就不可改變。msgCatalog 內容的字串長度上限「不可」超過 128 個字元。
msgCatalogType 內容會指定 msgCatalog 的意義和格式。現行保留關鍵字的非專屬清單包括:
這個內容是「選用」的,它一旦設定就不可改變,且如果定義了 msgCatalog 內容,則「必須」提供這個內容。msgCatalogType 內容的字串長度上限「不可」超過 32 個字元。
相關參照
Common Base Event XML 綱目規格
(C) Copyright IBM Corporation 2000, 2003. All Rights Reserved.