配接器配置檔結構

配接器配置檔包含通用日誌配接器執行時期實例所執行的多個環境定義集合。 各環境定義用來說明如何處理單一日誌檔。 由於配接器配置檔可以包含許多環境定義,因此,配接器可以同時處理許多日誌檔。

特定日誌檔所關聯的各個環境定義是由一系列的元件構成。 在處理日誌檔時,每個元件都扮演了某個角色。

下圖顯示一般「通用日誌配接器」配置的結構。

顯示單一環境定義的配接器和許多元件的圖

環境定義

環境定義用來說明元件為了日誌檔的處理而鏈結起來時的排序分組。 每個日誌檔都有個別的環境定義,且單一配置中可以定義多個環境定義。 「通用日誌配接器」提供兩種環境定義實作方式:

環境定義有下列內容:

內容 類型 行為
說明 字串 環境定義的文字說明。這個值只供配接器配置編輯器使用。
唯一 ID 字串 這個環境定義的唯一 ID。環境定義會參照這個字串來識別要用的元件實例。
是連續作業 Boolean 應不應該根據「閒置時間上限」和「暫停間隔」內容來監視這個日誌檔的變更。
閒置時間上限 整數(毫秒) 環境定義在自行關閉之前,等待日誌檔變更的時間量上限。
暫停間隔 整數(毫秒) 在到達日誌檔結尾之後,且在試圖重新讀取之前,環境定義等待的時間量。
ISO 語言碼 產生日誌檔之「語言環境」的語言碼。這些程式碼由兩個小寫的字母所構成,如 ISO-639 所定義。您可以在許多站台中找到這些語言碼的完整清單,例如:http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt。如果沒有指定這個值,系統會使用目前執行「通用日誌配接器」之「語言環境」中的語言。剖析日誌檔中的時間戳記時便會使用這個值。
ISO 國碼 產生日誌檔之「語言環境」的國碼。這些程式碼由兩個大寫的字母所構成,如 ISO-3166 所定義。您可以在許多站台中找到這些國碼的完整清單,例如:http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html。如果沒有指定這個值,系統會使用目前執行「通用日誌配接器」之「語言環境」中的國家。剖析日誌檔中的時間戳記時便會使用這個值。
編碼 要剖析之日誌檔的字元編碼。指定的編碼值必須是 IANA Charset Registry (http://www.iana.org/assignments/character-sets) 中所列的值,且執行「通用日誌配接器」之 JVM 必須支援該值。如果沒有指定這個值,系統會使用執行「一般日誌配接器」之 JVM 的預設檔案編碼(於 file.encoding JVM 系統內容中所指定的值),來剖析日誌檔。

感應器

感應器提供讀取日誌內容的機制,以進行處理。通用日誌配接器提供下列感應器:

下表列出感應器類型共用的屬性。

感應器屬性

屬性名稱 類型 行為
感應器類型 字串 配接器所用的感應器類型。
說明(必要) 字串 感應器的文字說明。這個值只供配接器配置編輯器使用。
唯一 ID(必要) 字串 這個元件的唯一 ID。感應器會參照這個字串來識別要用的元件實例。
區塊作業上限(必要) 整數 在轉遞給擷取器處理之前,感應器所讀取的行數上限。 如果是 StaticParserSensor 類型,這個欄位指出在轉遞給輸出器處理之前,靜態剖析器所建立的 Common Base Event 物件數目上限。
信任緩衝區 整數 檔案所要儲存且用來判斷檔案前次讀取之後是否有進行附加的最後 n 位元組。
標底大小 整數 檔案包含靜態內容的 n 位元組。部分日誌檔會在日誌檔尾端附加標底。 這部分的日誌檔不視為日誌資料。 當判斷檔案前次讀取之後是否有進行附加時,不會用到的檔案標底部分。

下表列出各類型感應器的專用內容。 元件程式碼能夠辨識下列內容,它們的併字必須完全符合表格的指示,元件才能辨認和使用它們。

感應器類型 內容 應用程式
SingleFileSensor
directory(必要)
SinlgeFileSensor 所讀取的檔案的目錄位置。
fileName(必要)
SingleFileSensor 所讀取的檔案名稱。如果應用程式使用日誌檔輪替, 便可以使用正規表示式來指定檔案名稱。
附註:解譯 fileName 欄位時,必須考量大小寫。如果您想要讓該欄位不區分大小寫, 請使用正規表示式來指定檔案名稱。
shell
執行轉換器指令的 UNIX Shell。只供 UNIX 平台使用。
converter
在啟動感應器之前執行前處理指示的指令行。
當建立配接器以便正規表示式規則剖析日誌檔時使用。
StaticParserSensor
directory(必要)
StaticParserSensor 所讀取的檔案的目錄位置。
fileName(必要)
StaticParserSensor 所讀取的檔案名稱。
parserClassName(必要)
實作靜態剖析器的 Java 類別名稱。 這個類別必須實作 org.eclipse.hyades.logging.parsers.IParser 介面。
當建立配接器來用靜態剖析器 Java 類別剖析日誌檔時使用。

擷取器

擷取器會採取感應器所提供的輸入行集合,將它們分到各個訊息界限中。

通用日誌配接器提供下列擷取器

下列內容是在擷取器配置所提供的:

內容 類型 行為
說明 字串 擷取器的文字說明。這個值只供配接器配置編輯器使用。
唯一 ID 字串 這個元件的唯一 ID。擷取器會參照這個字串來識別要用的元件實例。
包含換行 Boolean 指出日誌檔中的訊息是否跨多行。
取代換行 Boolean 用另一個字串區段來取代這個檔案中的換行。置換是在擷取器搜尋開頭型樣或結尾型樣之前進行的。
附註:使用這個選項的負面影響是,從日誌檔剖析出來的值不會包含換行,除非用剖析器替代規則明確新增換行。
換行符號 字串 用來取代換行的字串區段。只有在「取代換行」是 true 時,才會使用這個。
包括開頭型樣 Boolean 要轉遞到下一元件的訊息是否包括 StartPattern。如果值是 false,就會除去訊息的相符部分。
開頭型樣 字串或正規表示式 用來識別訊息開頭的字串區段。您可以一律使用 RegularExpressionExtractor 類別。 不過,如果您的開頭型樣是簡式字串,SimpleExtractor 類別的負荷會比較少。
包括結尾型樣 Boolean 要轉遞到下一元件的訊息是否包括結尾型樣。 如果值是 false,就會除去訊息的相符部分。
結尾型樣 字串或正規表示式 用來識別訊息結尾的字串區段。如果沒有指定結尾型樣,就由下一開頭型樣來定界訊息。

剖析器

剖析器會採擷取器定界的訊息來建置一組字串值至資料結構的對映。 在通用日誌配接器的情況下,資料結構是 Common Base Event 1.0.1

通用日誌配接器提供下列剖析器類別

剖析器有兩個執行階段:

  1. 廣域處理階段,這時會針對擷取器提供的訊息來執行一組廣域正規表示式。
  2. 屬性處理階段,這時會為了判斷指派給資料結構 (Common Base Event 1.0.1) 中之各個屬性的值,而執行各組特定替代規則。

這兩個執行階段可讓訊息在廣域處理階段中記號化,成為一系列的屬性值。 之後,在屬性處理階段中,就可以用屬性名稱或索引來參照屬性值。

下列廣域內容是在剖析器中指定的:

內容 類型 行為
說明 字串 剖析器的文字說明。這個值只供配接器配置編輯器使用。
唯一 ID 字串 這個元件的唯一 ID。剖析器會參照這個字串來識別要用的元件實例。
分隔字元記號 字串或正規表示式 記號,或用來說明將訊息分解成屬性值配對的一系列記號之正規表示式。

比方說,如果日誌檔中的每一新行都含有它的屬性及其值,您可以指定分隔字元記號 \n。 分解訊息的好處是可以在屬性處理階段中參照這些字串區段。
附註:如果沒有指定分隔字元記號,便不會執行廣域處理程序。

指定記號 字串或正規表示式 記號,或用來說明將「分隔字元記號」所建立之字串區段分解成屬性值配對的一系列記號之正規表示式。比方說,如果每個屬性和值是用 = 符號來分開,且指定記號值是 =,就可以在屬性處理階段中參照屬性及其值。 如果指定了分隔字元記號,但指定記號尚未指定,訊息就會分解成一份屬性值清單,替代規則可以利用索引來參照它。

Common Base Event 的個別屬性有下列內容:

附註: 在廣域處理階段期間所剖析的值,其前後空白字元 會被移除。因此,寫入使用位置值的替代規則時, 可以假設值的前後沒有空白字元。

內容 類型 行為
利用上一個相符替代項作為預設值 Boolean 如果這個屬性的目前這組替代規則傳回了正的相符項,就將比對值儲存起來,以便在沒有正的相符項時,用來作為處理下一筆記錄的預設值。
預設值 字串 如果這個屬性沒有任何替代規則提供了正的相符項, 或這個屬性根本沒有替代規則,就會將這裡指定的預設值指派給這個屬性。 如果特定屬性的所有記錄都需要相同的值,就可以使用這個內容,而不必建立這個屬性的預設替代規則。 請注意,如果有儲存的值可供使用,將以利用上一個相符替代項作為預設值為優先。
母項所需 Boolean 可讓您指定這個元素是否要包含一個有效值,才能讓母項元素有效。 比方說,如果為狀況元素選取這個選項, 則表示向剖析器指出 Common Base Event 物件必須包含一個有效的 狀況元素。在處理期間,如果狀況元素傳回空值, 剖析器便不會處理 Common Base Event 物件的任何其他子元素,因為剖析器已經知道這個 Common Base Event 物件是無效的, 因為所需子元素傳回一個無效值。
子項選項 Boolean 可讓您指定有效子項屬性或元素傳回有效值時, 是否要停止這個元素的處理程序。 比方說,假設狀況有三個子元素,ReportSituationRequestSituationStartSituation,每個子元素都有自己的子樹狀結構。 如果為狀況元素選取了子項選取選項, 則會在傳回有效值的第一個子項子樹狀結構中,停止剖析作業。

替代規則是在屬性處理階段中執行的。 它們是由上至下依序處理。 如果規則是一個相符項,就不會針對這個內容來執行進一步的規則。 如果找不到相符項,除非指定了屬性的利用上一個相符替代項作為預設值預設值內容,否則,不會在屬性中放置任何值。

替代規則包含下列內容:

內容 類型 行為
比對 正規表示式 當在這個替代規則所處理的字串區段範圍中有相符的相符項時,用來識別這個屬性所套用的值的正規表示式。如果您沒有提供正規表示式,就會將規則視為「相符項」。
位置 名稱值屬性配對 「位置」可讓您參照在廣域處理階段中建立的名稱值屬性配對。
  • 如果同時指定了分隔字元記號和指定記號,位置字串可以利用下列文法,依名稱來參照許多屬性:$h('Attr1')@@$h('Attr2')...
    $h('Attrn') 用來識別先前建立的屬性名稱。
    其中 @@ 是屬性之間的分隔字元。
  • 如果指定了分隔字元記號,但不是指定記號,「位置」字串可以利用下列文法,依索引而不是名稱來參照一或多個屬性:n1@@n2..
    其中 n1 和 n2 是代表索引的整數。 索引從 1 開始。如果訊息字串的開頭是分隔字元記號,索引 1 的屬性值就是空值。 第一個屬性值是從索引 2 開始。

在「比對」內容中,您可以新增分隔字元來指出哪些正規表示式應該套用到哪個屬性值。

替代 字串 放在屬性中的值。 這可能是字串,它也可能指向「比對」內容中的正規表示式。「比對」內容所擷取的字串區段可以用正規表示式中的分組來參照。 $1 表示第一分組,$2 表示第二分組,依此類推。
使用內建函數 勾選框 當選取了屬性的使用內建函數時,如果先前有替代規則,但沒有任何相符者,它會使通用日誌配接器執行時期利用它自己的內部函數來產生這個屬性的值。 只支援下列 CBE 屬性使用這項特性:
  • localInstanceId
  • globalInstanceId
  • componentIdentification.location
  • componentIdentification.locationType
替代類別 字串 指定使用者建立的 Java 類別名稱,這個類別能在規則的位置比對替代規格所比對的值上執行自訂剖析邏輯。 如果替代規則符合記錄中的資料,就會呼叫這個類別,且會用結果來建立 Common Base Event 物件。
規格:
  • 這個類別必須實作介面類別 org.eclipse.hyades.logging.adapter.parsers.ISubstitutionExtension 或繼承類別 org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension,通用日誌配接器才能執行它。
  • 當您要在日誌檔記錄之間儲存狀態資料時,請使用繼承類別。org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension 類別會使通用日誌配接器只配置這個類別的單一實例來剖析日誌檔的所有記錄。
  • 使用者類別必須包括在通用日誌配接器執行時期的類別路徑中。
  • 如果通用日誌配接器在 Eclipse 環境中執行,您可以利用 org.eclipse.hyades.logging.adapter 外掛程式的 substitutionExtension 延伸點,將類別建立成通用日誌配接器的 Eclipse 外掛程式延伸規格。
時間格式 字串 這個欄位只適用於 creationTime 元素的替代規則,可以簡化日期時間的剖析。 比方說,部分日誌檔所包含的時間戳記含有月份名稱,而不是數值表示法。 這會造成建立替代規則來產生依照 XML 綱目 dateTime 資料類型格式(CBE creationTime 元素所需)的字串值 ,變得十分困難。 在這個情況下,使用者可以在「時間格式」欄位中,依照 java.text.SimpleDateFormat (java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html) 的 javadoc 所說明來指定 Java 簡式日期格式字串。 規則的「位置」、「比對」和「替代」規格所比對的值會根據「時間格式」字串來剖析,產生的值將用來產生 CBE creationTime 值。
附註:「語言環境」由「環境定義實例」配置中所指定之 ISO 語言和國碼值所代表,其只有在使用時間格式字串來剖析時間戳記時,才會使用。

格式製作器

格式製作器會採取從屬性到剖析器提供的值的對映,並建置正確 Java 物件實例。 配接器執行時期包含用來建立符合 Common Base Event 1.0.1 版規格之 Common Base Event 物件的單一格式製作器。

格式製作器包含下列內容:

內容 類型 行為
唯一 ID 字串 這個元件的唯一 ID。格式製作器會參照這個字串來識別要用的元件實例。
說明 字串 格式製作器的文字說明。這個值只供配接器配置編輯器使用。

輸出器

輸出器會提出格式製作器所提供的結果 Common Base Event 記錄。 輸出器提供或包裝用來儲存環境定義最終輸出的機制。「通用日誌配接器」提供下列輸出器:

輸出器的內容:

內容 類型 行為
唯一 ID 字串 這個元件的唯一 ID。輸出器會參照這個字串來識別要用的元件實例。
說明 字串 輸出器的文字說明。這個值只供配接器配置編輯器使用。
輸出器類型 列舉 輸出器的類型。

輸出器類型和必要內容:

輸出器類型 必要內容
StandardOutOutputter
SingleFileOutputter directory、fileName
LoggingAgentOutputter agentName - 在建立記載代理程式時,提供給它的名稱
waitUntilLoggingTime(optional) - 輸出器在開始寫入代理程式之前,等待使用者連接和開始監視代理程式的時間。 如果沒有指定這個內容,輸出器不會等待代理程式受到監視,就直接寫入它。

 

相關概念
Hyades 通用日誌配接器概觀
Common Base Event 格式規格

相關作業
建立日誌剖析器
建立規則型配接器
建立靜態配接器

相關參照
配接器配置檔結構
Common Base Event 格式規格
配接器配置編輯器
正規表示式文法