アダプター構成ファイルの構造

アダプター構成ファイルには、汎用ログ・アダプターのランタイム・インスタンスによって実行される コンテキスト の集合が収められています。 各コンテキストは、単一のログ・ファイルの処理方法を表します。 アダプター構成ファイルにはこれらのコンテキストの多くを収めることができるので、アダプターは同時に複数のログ・ファイルを処理することができます。

特定のログ・ファイルに関連付けられる各コンテキストは、 一連のコンポーネントから構成されています。 コンポーネントごとに、ログ・ファイルの処理で果たす役割があります。

以下の図に、典型的な汎用ログ・アダプター構成の構造を示します。

単一のコンテキストを持つアダプター、および多くのコンポーネントを示した図

コンテキスト

コンテキストは、ログ・ファイル処理のために 1 つにチェーニングされているコンポーネントの順序付けグループを表します。 ログ・ファイルごとに個別のコンテキストがあり、 単一の構成で複数のコンテキストを定義することができます。 汎用ログ・アダプターには、以下の 2 つのコンテキストの実装が用意されています。

コンテキストのプロパティーは以下のとおりです。

プロパティー 振る舞い
説明 string コンテキストのテキスト記述。 この値は、アダプター構成エディターでのみ使用されます。
固有の ID string このコンテキストの固有の ID。コンテキストはこのストリングを参照してどのコンポーネント・インスタンスを使用するかを識別します。
連続稼働 (Is Continuous Operation) boolean このログ・ファイルをモニターし、 「最大アイドル時間」プロパティーと「一時停止インターバル」プロパティーに基づき変更の有無を調べるかどうかを指定します。
最大アイドル時間 integer (ミリ秒) コンテキストがシャットダウンするまでにログ・ファイルの変更を待機する最大時間。
一時停止インターバル integer (ミリ秒) コンテキストがログ・ファイルの終わりに達してから再び読み取りを開始するまでに待機する時間。
ISO 言語コード ログ・ファイルが生成されたときのロケールの言語コード。これらのコードは小文字の 2 文字からなるコードで、ISO-639 で定義されています。これらのコードの完全なリストは多くのサイトに掲載されています (例えば、http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt)。この値が指定されていない場合は、汎用ログ・アダプターが実行しているときの現行ロケールの言語が使用されます。この値は、ログ・ファイル内のタイム・スタンプを構文解析するときに使用されます。
ISO 国別コード ログ・ファイルが生成されたときのロケールの国別コード。これらのコードは大文字の 2 文字からなるコードで、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 システム・プロパティーで指定されています) を使用して構文解析されます。

センサー

センサーは、ログ・ファイルの内容を読み取って処理するためのメカニズムを備えています。汎用ログ・アダプターには以下のセンサーが用意されています。

以下の表に、センサー・タイプ間で共通の属性をリストします。

センサーの属性

属性名 振る舞い
センサー・タイプ string アダプターが使用するセンサー・タイプ。
説明 (必須) string センサーのテキスト記述。 この値は、アダプター構成エディターでのみ使用されます。
固有の ID (必須) string このコンポーネントの固有 ID。 センサーはこのストリングを参照してどのコンポーネント・インスタンスを使用するかを識別します。
最大ブロック化 (必須) Integer 処理のために抽出に転送するまでセンサーが読み取る最大行数。 StaticParserSensor タイプでは、このフィールドは、 処理のためにアウトプッターに転送するまで static パーサーが作成する共通ベース・イベント・オブジェクトの最大数を示します。
信頼性バッファー (Confidence Buffer) Integer ファイルの最後の n バイトを保存し、 これを使用して、前回の読み取り以降にファイルに対して追加が発生したかどうかを判別します。
フッター・サイズ (Footer size) Integer 静的コンテキストを含む n バイトのファイル。ログ・ファイルの中には、ログ・ファイルの終わりにフッターが付加されているものもあります。 ログ・ファイルのこの部分は、ログ・データとはみなされません。 ファイルのフッター部分は、前回のファイルの読み取り以降に追加が発生したかどうかの判別には使用されません。

以下の表に、 各センサー・タイプに固有のプロパティーをリストします。 以下のプロパティーはコンポーネント・コードで認識されるので、 コンポーネントで認識および使用されるように表のとおりに正確に入力してください。

センサー・タイプ プロパティー 適用
SingleFileSensor
directory (必須)
SinlgeFileSensor が読み取るファイルのディレクトリー・ロケーション
fileName (必須)
SingleFileSensor が読み取るファイルの名前。アプリケーションがログ・ファイルのローテーションを使用している場合は、正規表現を使用してファイル名を指定することができます。
: fileName フィールドを解釈する場合には、大/小文字が考慮されます。フィールドが大/小文字を区別しないようにする場合は、正規表現を使用してファイル名を指定してください。
shell
コンバーター・コマンドの実行環境である UNIX シェル。UNIX プラットフォームでのみ使用。
converter
センサーを開始する前に実行するプリプロセス命令のコマンド行。
正規表現規則に従ってログ・ファイルを構文解析するためのアダプターを作成する場合に使用。
StaticParserSensor
directory (必須)
StaticParserSensor が読み取るファイルのディレクトリー・ロケーション
fileName (必須)
StaticParserSensor が読み取るファイルの名前。
parserClassName (必須)
static パーサーを実装する Java クラスの名前。 このクラスは org.eclipse.hyades.logging.parsers.IParser インターフェースを実装する必要があります。
static パーサー Java クラスに従ってログ・ファイルを構文解析するためのアダプターを作成する場合に使用。

抽出

抽出は、センサーから提供された入力行の集合を取得し、メッセージ境界でそれらを切り離します。

汎用ログ・アダプターには、以下の抽出が用意されています。

抽出用の構成として、以下のプロパティーが用意されています。

プロパティー 振る舞い
説明 string 抽出のテキスト記述。 この値は、アダプター構成エディターでのみ使用されます。
固有の ID string このコンポーネントの固有 ID。 抽出は、このストリングを参照してどのコンポーネント・インスタンスを使用するかを識別します。
改行を含む boolean ログ・ファイル内のメッセージが複数行にまたがるかどうかを示します。
改行の置換 boolean このファイル内の改行を別のストリング・セグメントに置き換えます。 置き換えは、抽出が開始パターンまたは終了パターンを検索する前に行われます。
注: このオプションを使用した場合、ログ・ファイルから構文解析された値には、パーサーの置換規則によって明示的に追加されていない限り、改行は含まれない、という副次作用が生じます。
改行シンボル string 改行と置き換えるストリング・セグメント。 「改行の置換」が true の場合のみ使用されます。
開始パターンの組み込み boolean 次のコンポーネントに転送するメッセージの一部として開始パターンを組み込むかどうかを示します。 この値が false の場合、メッセージの一致する部分は転送されません。
開始パターン string または正規表現 メッセージの開始を識別するストリング・セグメント。 常に RegularExpressionExtractor クラスを使用することができます。 ただし、開始パターンが単純なストリングの場合、 SimpleExtractor クラスの方が発生するオーバーヘッドは少なくなります。
終了パターンの組み込み boolean 次のコンポーネントに転送するメッセージの一部として終了パターンを組み込むかどうかを示します。 この値が false の場合、メッセージの一致する部分は転送されません。
終了パターン string または正規表現 メッセージの終わりを識別するストリング・セグメント。 終了パターンが指定されない場合、メッセージは次の開始パターンで区切られます。

パーサー

パーサーは、抽出で区切られたメッセージを取得して、 ストリング値のマッピング・セットをデータ構造にビルドします。 汎用ログ・アダプターの場合のデータ構造は共通ベース・イベント 1.0.1 です。

汎用ログ・アダプターには、以下のパーサー・クラスが用意されています。:

このパーサーには 2 つの実行フェーズがあります。

  1. グローバル処理フェーズ。 抽出から提供されたメッセージに対し、グローバルな正規表現セットが実行されます。
  2. 属性処理フェーズ。 特定の置換規則セットが実行されて、 データ構造 (共通ベース・イベント 1.0.1) の各属性に割り当てる値が判別されます。

この 2 つの実行フェーズにより、 グローバル処理フェーズ時にメッセージを一連の属性値にトークン化し、 属性処理フェーズ時にその属性値を属性名または索引で参照することができます。

パーサーの一部として指定するグローバル・プロパティーは以下のとおりです。

プロパティー 振る舞い
説明 string パーサーのテキスト記述。 この値は、アダプター構成エディターでのみ使用されます。
固有の ID string このコンポーネントの固有 ID。 パーサーはこのストリングを参照してどのコンポーネント・インスタンスを使用するかを識別します。
セパレーター・トークン string または正規表現 メッセージを属性と値のペアに分解するトークン、 または一連のトークンを表す正規表現。

例えば、ログ・ファイルの行ごとに属性とその値が入っている場合は、 セパレーター・トークンとして ¥n を指定することができます。 メッセージを分解すると属性処理フェーズでストリング・セグメントを参照できるというメリットがあります。
注: セパレーター・トークンが指定されていない場合、グローバル処理は実行されません。

指定トークン string または正規表現 セパレーター・トークンによって作成されたストリング・セグメントを属性と値のペアに分解するトークン、 または一連のトークンを表す正規表現。 例えば、各属性と値が = 符号で切り離されていて、 指定トークンの値が = の場合、属性とその値を属性処理フェーズで参照することができます。 セパレーター・トークンは指定されているが指定トークンは指定されていない場合、 メッセージは属性値のリストに分解され、置換規則において索引で参照することができます。

共通ベース・イベントの個々の属性のプロパティーは以下のとおりです。

注: グローバル処理フェーズで構文解析された値は、先頭および末尾の空白文字が切り取られます。そのため、位置を示す値を使用する置換規則は、値には先頭および末尾には空白文字がないものと想定して作成することができます。

プロパティー 振る舞い
直前の一致置換をデフォルトとして使用する boolean この属性に対する現在の置換規則セットが正の一致を戻す場合、 その一致値を保管して、次のレコードを処理するときに正の一致がなかった場合のデフォルトとして使用することができます。
デフォルト値 string この属性に対する置換規則のいずれも正の一致を提供しない場合、 またはこの属性に対する置換規則がない場合は、 ここで指定されているデフォルト値がこの属性に割り当てられます。 特定の属性ですべてのレコードに対し同じ値を必要とする場合は、 その属性のデフォルトの置換規則を作成する代わりにこのプロパティーを使用することができます。 保存された値がある場合は、「直前の一致置換をデフォルトとして使用する」が優先されることに留意してください。
親で必須 boolean これを使用して、親要素が有効であるようにするためには、この要素が有効な値を持つ必要があるかどうかを指定することができます。例えば、situation 要素にこのオプションが選択された場合、これはパーサーに対して、共通ベース・イベント・オブジェクトは有効な situation 要素を持つ必要がある、ということを示します。処理中に状態エレメント がヌル値を戻すと、パーサーは共通ベース・イベント・オブジェクトの他の子エレメントを処理しなくなります。 これは、必須の子エレメントが無効な値を戻したため、パーサーは共通ベース・イベント・オブジェクト が無効であることをすでに認識しているためです。
子の選択 boolean これを使用すると、有効な子属性または子要素が有効な値を戻した場合に、この要素に対する処理を停止する必要があるかないかを指定できます。 例えば、それぞれサブツリーを持つ 3 つの子要素 ReportSituationRequestSituation、および StartSituation を持つ situation を考えてみましょう。situation 要素に対して子の選択オプションが選択された場合、構文解析は、有効な値を戻したその最初の子のサブツリーで停止します。

置換規則は属性処理フェーズの一部として実行されます。 規則は上から順に処理されます。 一致する規則が見つかると、このプロパティーに対しそれ以降の規則は実行されません。 一致する規則が見つからない場合は、 その属性の「直前の一致置換をデフォルトとして使用する」プロパティーまたは 「デフォルト値」プロパティーが指定されていない限り、属性に値は入りません。

置換規則のプロパティーは以下のとおりです。

プロパティー 振る舞い
一致 正規表現 この置換規則で処理されるストリング・セグメントの有効範囲内で一致が見つかった場合に、この属性に適用する値を識別する正規表現。 正規表現を指定しない場合は、この規則が一致するものと見なされます。
名前と値の属性ペア 「桁」では、グローバル処理フェーズ時に作成された名前と値の属性ペアを参照することができます。
  • セパレーター・トークンと指定トークンの両方が指定されている場合、 「」ストリングは、$h('Attr1')@@$h('Attr2')... という文法に従って名前で複数の属性を参照することができます。
    $h('Attrn') には、事前に作成済みの属性名を指定します。
    ここで、@@ は属性と属性の間のセパレーターです。
  • セパレーター・トークンは指定されているが指定トークンは指定されていない場合は、 「桁」ストリングは、n1@@n2.. という文法に従って名前の代わりに索引で 1 つ以上の属性を参照することができます。
    ここで、n1 と n2 は索引を表す整数です。 索引は 1 から始まります。メッセージ・ストリングがセパレーター・トークンから始まる場合、 索引 1 の属性値はヌルになります。 したがって、最初の属性値は索引 2 から始まります。

「一致」プロパティーでは、セパレーターを追加して、どの正規表現をどの属性値に適用するかを示すことができます。

置換 string 属性に入れる値。 これは、ストリングでも、「一致」プロパティーの正規表現を参照しても構いません。 「一致」プロパティーによって抽出されるストリング・セグメントは、 正規表現のグループ化を使用して参照することができます。 $1 は最初のグループ、$2 は 2 番目のグループ、というようになります。
ビルドイン機能の使用 チェック・ボックス 前の置換規則のいずれも一致しない場合に、 属性に対して「ビルドイン機能の使用」を選択すると、 汎用ログ・アダプターのランタイムは独自の内部関数を使用してその属性の値を生成します。 このフィーチャーは、以下の CBE 属性に対してのみサポートされています。
  • localInstanceId
  • globalInstanceId
  • componentIdentification.location
  • componentIdentification.locationType
置換クラス (Substitution Class) string 規則の「」、「一致」、および「置換」の指定と一致する値についてカスタムの構文解析ロジックを実行できるユーザー作成の Java クラスの名前を指定します。 置換規則がレコード内のデータと一致すると、このクラスが呼び出され、 その結果を使用して共通ベース・イベント・オブジェクトが作成されます。
仕様:
  • このクラスを汎用ログ・アダプターで実行するためには、 インターフェース・クラス org.eclipse.hyades.logging.adapter.parsers.ISubstitutionExtension または拡張クラス org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension を実装する必要があります。
  • ログ・ファイル・レコード間の状態データを保管する場合は、拡張クラスを使用します。 クラス org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension により、 汎用ログ・アダプターはこのクラスの 1 つのインスタンスのみを割り振って、 ログ・ファイルのすべてのレコードを構文解析します。
  • ユーザー・クラスを汎用ログ・アダプターのランタイムのクラスパスに含める必要があります。
  • 汎用ログ・アダプターを Eclipse 環境で実行している場合は、 org.eclipse.hyades.logging.adapter プラグインの substitutionExtension 拡張ポイントを使用して、 クラスを汎用ログ・アダプターの Eclipse プラグイン拡張として作成することができます。
時刻形式 string このフィールドは、creationTime エレメントの置換規則にのみ適用されます。 日時の構文解析を単純化する場合に使用されます。 例えば、一部のログ・ファイルに、数値表現の代わりに月の名前を含むタイム・スタンプが入っているとします。 この場合、CBE の creationTime エレメントで必要な XML スキーマの dateTime データ型の形式でストリング値を生成する置換規則を作成することが困難になります。 この場合、ユーザーは「時刻形式」フィールドに Java の単純な日付形式のストリングを指定することができます (java.text.SimpleDateFormat については、javadoc (java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html) を参照してください)。 規則の「桁」、「一致」、および「置換」の指定と一致する値が「時刻形式」ストリングに基づいて構文解析され、 戻された値を使用して CBE creationTime 値が生成されます。
: 時刻形式ストリングを使用してタイム・スタンプを構文解析するときには、コンテキスト・インスタンス構成で指定されている ISO 言語コードおよび国別コードの値によって表されるロケールが使用されます。

フォーマッター

フォーマッターは、パーサーから提供された値に対する属性のマッピングを取得し、 適正な Java オブジェクト・インスタンスをビルドします。 アダプターのランタイムには、共通ベース・イベント・バージョン 1.0.1 仕様に準拠して共通ベース・イベント・オブジェクトを作成する単一のフォーマッターが含まれています。

フォーマッターのプロパティーは以下のとおりです。

プロパティー 振る舞い
固有の ID string このコンポーネントの固有 ID。 フォーマッターは、このストリングを参照してどのコンポーネント・インスタンスを使用するかを識別します。
説明 string フォーマッターのテキスト記述。 この値は、アダプター構成エディターでのみ使用されます。

アウトプッター

アウトプッターは、フォーマッターから提供された共通ベース・イベント・レコードを外部化します。 アウトプッターは、コンテキストの最終的な出力を保管するメカニズムをラップします。 汎用ログ・アダプターは、以下のアウトプッターを提供しています。

アウトプッター・プロパティーは以下のとおりです。

プロパティー 振る舞い
固有の ID string このコンポーネントの固有 ID。 アウトプッターは、このストリングを参照してどのコンポーネント・インスタンスを使用するかを識別します。
説明 string アウトプッターのテキスト記述。 この値は、アダプター構成エディターでのみ使用されます。
アウトプッター・タイプ enumeration このアウトプッターのタイプ。

アウトプッター・タイプおよび必須プロパティーは以下のとおりです。

アウトプッター・タイプ 必須プロパティー
StandardOutOutputter なし
SingleFileOutputter directory、fileName
LoggingAgentOutputter agentName - 作成時にロギング・エージェントに付けられる名前。
waitUntilLoggingTime (オプション)- アウトプッターがエージェントへの書き込みを開始するまで、 ユーザーが接続してエージェントのモニターを開始することを待機する時間。 このプロパティーが指定されない場合、 アウトプッターはエージェントへの書き込みの前にエージェントのモニターを待機しません。

 

関連概念
Hyades 汎用ログ・アダプターの概説
共通ベース・イベント・フォーマットの仕様

関連タスク
ログ・パーサーの作成
ルール・ベース・アダプターの作成
static アダプターの作成

関連参照
アダプター構成ファイルの構造
共通ベース・イベント・フォーマットの仕様
アダプター構成エディター
正規表現グラマー