第 6 章   エラーと監視のログ


iPlanet Trustbase Transaction Manager には、エラーや監視のログに使用できる一連のライブラリがあります。これらのライブラリのデフォルト実装により、フレームワークやビジネスコンポーネントで情報をリレーショナルデータベース内に格納して、外部のブラウザやエラー管理コンソールから使用することが可能です。

エラーログと監視ログは、どちらもログマネージャによって制御されます。ログマネージャは、現在の構成に従って、データを適切な場所に格納します。この設計によって、エラーや監視の情報を記録するための、場所に依存しないメカニズムが提供され、iPlanet Trustbase Transaction Manager の複数の実装間でコンポーネントを再使用できます。このログマネージャは、iPlanet Trustbase Transaction Manager を起動するたびにアクティブになります。ログマネージャの構成は、最初は初期化ファイルから読み込まれますが、次の起動からはログマネージャによって生成された永続構成オブジェクトから読み込まれます。

概要

---

図 6-1    iPlanet Trustbase Transaction Manager ログマネージャ

  

ログマネージャによって記録されるデータは、リクエスト元のコンポーネントにより、エラーログオブジェクトまたは監視ログオブジェクトとして提供されます。ログマネージャでは記録されるオブジェクトのタイプはチェックされますが、内容はチェックされません。タイプのチェックでは、受け渡すオブジェクトが iPlanet Trustbase Transaction Manager で定義されたエラーログクラスまたは監視ログクラスのサブクラスであることが確認されます。したがって、開発者はソリューションで特別に使用する新規のエラーログタイプまたは監視ログタイプ (請求ログなど) を定義できます。

ログマネージャは、ストア API によりデータストアから抽出されます。したがって、ログをさまざまな方法で実装したり (請求情報のログを別の物理レポジトリに格納するなど)、特定のログタイプ (サードパーティの監視システムに渡されるイベントを生成するエラーなど) を実装したりすることができます。

監視ログ

---

監視ログは、iPlanet Trustbase Transaction Manager プラットフォームのライフタイムにおける、次のような特定の時点で生成されます。

• サービスの起動イベント

• サービスの終了イベント (通常の終了と、異常な終了の両方)

• すべての構成の変更

• すべてのセキュリティドメインの変更

これらの標準的な iPlanet Trustbase Transaction Manager 監視ログタイプは、
uk.co.jcp.tbaseimpl.log.audit.type パッケージ内で定義されています。

イベントの監視ログ

iPlanet Trustbase Transaction Manager 監視ログにエントリが生成されるようにするには、まずログをとる AuditObject タイプの新規インスタンスを作成します。このインスタンスは、uk.co.jcp.tbaseimpl.log.audit.AuditObject のサブタイプであることが必要です。次にこのインスタンスを静的メソッド AuditLog.log(...) に渡します。

ログされる監視の例を次に示します。

package com.iplanet.trustbase.app; public class DummyService { ...... private static final String SERVICE_STARTED = "START"; // Audit the occurrence of this event in the Audit Log AuditLog.log(new OperationBeginAudit( this.getClass(), SERVICE_STARTED, new String[]{ serviceName.toString() }); ...... }

すべての AuditObject には、次の 3 つのパラメータを使用します。

• this.getClass()
  クラスオブジェクト。この名前がメッセージの国際化バンドルキーの最初の部分に使われる。これは、通常は監視のログをとるクラスで、監視メッセージとパッケージの関連付けを容易にする。ただし、ほかの任意のクラスオブジェクトを使用することも可能

• SERVICE_STARTED
  任意の文字列。クラス名と連結して、監視目的でメッセージのテキストを見つけるための固有のバンドルキーを提供する。AuditBundle キーとその値については、後述の説明を参照

• new String[] { serviceName.toString() }
  文字列の配列。標準の java.text.MessageFormat クラスを使って最終的な監視メッセージを提供するために、AuditBundle メッセージとともに使用されるパラメータ

上に述べたように、クラスパスに AuditBundle ファイルがあり、実際の監視メッセージを検索できるようにバンドルマネージャに登録されていることが必要です (「新規監視タイプの定義」を参照)。前述の例では、.../com/iplanet/trustbase/app に AuditBundle.properties ファイルが作成されます。このファイルには次の行が含まれます。

com.iplanet.trustbase.app.DummyService_START=The service {0} has begun.

これは「this.getClass()」パラメータによって提供され、文字「_」と文字列「SERVICE_STARTED」が後についた、完全指定のクラス名です。

この監視に関連付けられるメッセージは「The service {0} has begun.」になります。「{0}」の部分は、java.text.MessageFormat クラスにより、監視コンストラクタが受け取る文字列配列のエントリ 0 に置き換えられます。

---

注	監視ログに関連付けられる API クラスは、uk.co.jcp.tbaseimpl.log.audit.AuditLog、uk.co.jcp.tbaseimpl.log.audit.AuditObject、および uk.co.jcp.tbaseimpl.log.audit.type 内の多くの標準的な具体監視クラスです。

---

新規監視タイプの定義

開発者は、新規監視ログタイプを定義して、アプリケーションやドメインに固有のメッセージを使用することができます。これらのログタイプは、uk.co.jcp.tbaseimpl.log.audit.AuditObject クラスのサブクラスであることが必要です。

これらの拡張監視タイプは、iPlanet Trustbase Transaction Manager サービスによって処理されたメッセージに関する情報のログをとる場合に、もっとも一般的に使用されます。

新規監視タイプを実装したら、次の手順に従って、標準の iPlanet Trustbase Transaction Manager 監視ログにこのタイプが表示されるようにします。

• 新規監視クラスを作成し、この監視を利用するサービスの JAR ファイルに入れます。iPlanet Trustbase Transaction Manager サービスの配置については、後の章で詳しく説明します。

• 監視メッセージに対し、適切なリソースバンドルを作成します。メッセージをさまざまな言語で簡単に地域対応化するには、iPlanet Trustbase Transaction Manager 監視ログに表示されるすべての監視タイプ文字列をリソースバンドル内で定義します。これらのバンドルは、新規 AuditType クラスと同じパッケージ (同じディレクトリ) に入れます。リソースバンドルの名前の形式は、標準的な Java の java.util.ResourceBundle クラスで定義されているものと同じにします。バンドルの形式は、名前と値の組み合わせのリストになります。名前の部分は「完全指定の監視タイプクラス名_bundleKey」の形で構成され、値は監視ログの AuditType フィールドに入れられる文字列になります。

• tbase.properties にエントリを作成することによって、新規監視リソースバンドルを登録します。このためには、新規監視リソースバンドルの完全指定の名前を参照する[BundleProviderManager/Audit] セクションにエントリを追加します。

• 最後に、tbase.properties で新規監視タイプを有効にします。このためには、サービスで定義される各新規監視クラスに対し、
  [uk.co.jcp.tbaseimpl.log.present.audit.AuditLogPresentationConfigService] セクションにエントリを追加します。

• iPlanet Trustbase Transaction Manager を再起動して、新規監視タイプをアクティブにします。これは新規サービスを有効にするために必要な作業であり、通常は新規監視タイプを作成するたびに必要な作業ではありません。

AuditObject の実装例を次に示します。

package uk.co.jcp.tbaseimpl.log.audit.type; import uk.co.jcp.tbaseimpl.log.audit.*; /** This class represents an audit object for recording that an operation has begun */ public class OperationBeginAudit extends AuditObject { public OperationBeginAudit ( Class auditClass , String bundleKey , String [] params ) { super ( auditClass , bundleKey , params ); } public static String getAuditTypeString() { // The bundleKey is added to this class name to determine the // actual string to be writteninto the AuditType field of the log String bundleKey = "OPERATION_BEGIN"; return uk.co.jcp.tbaseimpl.log.audit.AuditObject.getAuditTypeString ( uk.co.jcp.tbaseimpl.log.audit.type.OperationBeginAudit.class, bundleKey ); } }

リソースバンドルを定義するファイルを次に示します。このファイルは、パッケージ階層の OperationBeginAudit クラスと同じ場所に入れます。ファイル名は
TheNewAuditBundle_en.properties です。

uk.co.jcp.tbaseimpl.log.audit.type.OperationBeginAudit_OPERATION_BEGIN = OPERATION_BEGIN

新規バンドルを登録するために tbase.properties に追加するエントリを次に示します。ロケールを表す拡張子「_en」および .properties 拡張子は必要ありません。これは標準的な Java の java.util.ResourceBundle クラスと同様です。

[BundleProviderManager/Audit] bundle=uk.co.jcp.tbaseimpl.log.audit.type.TheNewAuditBundle

新規監視タイプを有効にするために tbase.properties に追加するエントリを次に示します。

[uk.co.jcp.tbaseimpl.log.present.audit.AuditLogPresentationConfig Service] auditlog.type.enabled=uk.co.jcp.tbaseimpl.log.audit.type.Operation BeginAudit

エラーの処理とログ

---

iPlanet Trustbase Transaction Manager プラットフォームで発生するエラーは、次の 2 つのカテゴリに分類できます。

• 論理エラー - データ、または処理に不適切な部分があり、リクエストをていねいに拒否する必要がある場合

• 例外 - 予期しない状態が発生し、処理ロジックが中断された場合

どちらの場合も、iPlanet Trustbase Transaction Manager のログマネージャによってエラーが発生したことが記録されるため、分析を行って適切な処置を取ることができます。

エラーのログ

iPlanet Trustbase Transaction Manager では、重要度を取る単独のエラーログクラス、エラーを定義するオブジェクトのクラス、およびプログラマによって定義されたメッセージに加え、メッセージに代入できる任意の数の文字列の引数を使用できます。デフォルトのエラーログの実装 （uk.co.jcp.tbaseimpl.log.error.ErrorLog） では、さまざまな重要度を示す 4 つの定数が定義されています。

表 6-1    エラーの重要度のタイプ

定数	説明
INFORMATION	情報イベントのログに使用。たとえば、コード内の関連のないセクションが実行されたなど、特にエラーとはいえないもの。あまり多用しないようにする。この定数は値「0」を持つ
WARNING	予期された処理可能なものであるが、動作分析のためにログが必要なエラーに使用。この定数は値「1」を持つ
ERROR	システムや、システム内の情報に本質的な問題があることを示す、重大なエラーに使用。ただし、このエラーでは処理の続行や再試行が可能。この定数は値「2」を持つ
FATAL	処理を回復できない、致命的なエラーに使用。これらのエラーが発生すると、処理が放棄される。この定数は値「3」を持つ

---

注	エラーログに関係する API クラスは、uk.co.jcp.tbaseimpl.log.error.ErrorLog および uk.co.jcp.tbaseimpl.log.error.ErrorObject です。

---

iPlanet Trustbase Transaction Manager でエラーのログをとるには、ErrorObject のインスタンスを含む ErrorLog.log( .... ) を呼び出します。ErrorObject のコンストラクタは多数ありますが、これらのコンストラクタはすべて、このエラー固有のエラーコードを識別する文字列パラメータを少なくとも 1 つ含んでいます。

iPlanet Trustbase Transaction Manager のエラーログメカニズムでは、発生するエラーそれぞれに対し、iPlanet Trustbase Transaction Manager 全体で固有なコードが与えられていることが必要です。iPlanet Trustbase Transaction Manager のエラーログサブシステムのエラー情報はすべて、次に示す各データベーステーブルに格納されます。

表 6-2 に、固有なエラーコードの詳細をまとめます。

表 6-2    Error_codes

error_codes テーブル
errorcode	エラーを識別する、固有な errorcode 文字列。長さは必ず 7 文字であること。通常の形式は「XXXnnnn」であり、「XXX」はサービスまたはサブシステムの 3 文字のコードを、「nnnn」は固有の番号を表す。たとえば、「IPH0009」は Identrus プロトコルハンドラのエラー
classname	このエラーのログをとるクラス。これにより、各エラーコードは 1 つの場所からのみ使用可能という制限が追加される
severity	前に述べた、エラーの重要度。各重要度の定数は、 uk.co.jcp.tbaseimpl.log.error.ErrorLog クラスにある
message	エラーログに表示される、地域対応化されたエラーメッセージ。標準的な Java クラスである java.text.MessageFormat によって記述されているため、このメッセージではパラメータを使用可能。これらのパラメータに入れる値は、ErrorObject コンストラクタの 1 つが受け入れる文字列の配列として渡される

次に、実際のエラーログテーブルについて説明します。通常、管理者がこのテーブルを直接表示することはありません。代わりに、ログされたエラーを目的に応じて表示できる、errorview という Oracle のビューを使用します。

表 6-3    エラー

エラーテーブル
errorid	エラーログエントリの固有 ID。順番に増加するシーケンスから生成される。つまり、このフィールドを使って、エラーメッセージをエラーがログされた順番に正確に並べ替えることが可能
errorcode	ログされるエラーのエラーコード。「error_codes テーブル」を参照
message	error_codes テーブルのメッセージ文字列と、ランタイムシステムによって提供された変数パラメータを組み合わせて生成された、最終的なメッセージ文字列
timestamp	エラーがログされた日時を識別する ORACLE の DateTime フィールド
severity	このエラーの error_codes エントリから取得された、重要度を表す整数
classname	エラーをログしたクラス名
machineid	エラーをログした iPlanet Trustbase Transaction Manager の IP アドレスを示す文字列。マルチノードの IAS インストールでは異なる場合もある
contextid	将来の拡張用のコンテキスト ID

エラーがログされる場合、自由形式の文字列データが付属していることが多くあります。これらの文字列データは、エラーが発生したコンテキストを示し、診断の助けとなります。このようなデータのもっとも一般的な例としては、例外のスタックトレースがあります。

表 6-4    エラーサポート

error_support テーブル
errorid	このエントリを「エラーテーブル」のエントリにリンク
datatype	任意の文字列識別子。データフィールド内のデータを分類する。iPlanet Trustbase Transaction Manager で定義されているこのフィールドの唯一の値は、データフィールドの内容が Java の例外のスタックトレースであることを示す「STACKTRACE」
data	自由形式の文字列データ

ここで説明したテーブルでは、iPlanet Trustbase Transaction Manager でサポートされているデータ指向型のエラーログメカニズムが完全に取り込まれています。

新規エラーの定義

新規エラーの定義はとても簡単です。定義を行うには、error_codes テーブルに新規エントリを作成します。現在のところ、この操作をサポートするツールはありませんが、基本的な SQL を使って実行できます。唯一気をつけなければならない点として、error_code フィールドは固有でなければならないことがあげられます。これは ORACLE によるテーブルに対する制限で、新規コードをエラーなしに挿入するには、そのコードが固有である必要があります。

次に、SQL を使ってエラーコードを挿入する例をあげます。

INSERT INTO error_codes values ( 'TST0001', 'com.iplanet.trustbase.sample.service', '1', 'This is the only exception in the test service' );

このエラーのログをとるには、次のコードを使います。

..... } catch (Exception exc) { ErrorLog.log( new ErrorObject( "TST0001", exc ); } .....

これにより、エラーテーブルにエントリが作成され、関連するスタックトレースが error_support テーブルにログされます。

例外の処理

論理エラーと同様、例外の処理でも情報のログをとり、システムのユーザや開発者が例外の発生した状況を分析できるようにします。

iPlanet Trustbase Transaction Manager の例外階層は、呼び出しを行ったコンポーネントが明示的に処理コードを提供しなくても、さまざまなコンポーネントが呼び出しを行ったコンポーネントに対して例外を返せるように設計されています。これは、例外の連続的な各「レベル」(それぞれコードの連続的な「レベル」に関連) が、前のレベルから派生しているためです。たとえば、ServiceException から派生する例外をスローするサービスを考えてみましょう。サービスによって明示的に例外の処理が行われない場合、例外はルータ (呼び出しを行ったコンポーネント) に戻されます。ServiceException は RoutingException から派生しているので、ルータは例外を適切に処理できると想定できます。

図 6-2    iPlanet Trustbase Transaction Manager の例外階層

  

現在 iPlanet Trustbase Transaction Manager システムに内蔵されている処理コードが適切に機能するためには、システムの拡張機能の開発者がこの階層によるアプローチを維持することが非常に重要です。

この階層状の構造は、例外が発生した場所によって異なる処理を行うことを可能にします。コンポーネントおよび関連するアクションを表 6-5 に示します。

表 6-5    例外

コンポーネント	基本的な例外	アクション
サーブレット	TbaseRuntimeException	TbaseRuntimeExceptions をキャッチし、適切な HTTP エラーを生成
プロトコル アナライザ	ProtocolAnalyserException	サーブレットで HTTP エラーとなる ParseException をスローする場合がある
メッセージ アナライザ	MessageAnalyserException	RemoteException が発生した際に生成される。サーブレットで HTTP エラーを引き起こす
メッセージ リーダ	MessageReaderException	埋め込みメッセージを含む場合、メッセージアナライザでキャッチされ、そのメッセージが処理される。その他の場合、例外はサーブレットに渡される
メッセージ ライタ	MessageWriterException	メッセージアナライザを通して、HTTP エラーを返すサーブレットに渡される
ルータ	RoutingException	メッセージアナライザを通して、HTTP エラーを返すサーブレットに渡される
サービス	ServiceException	メッセージを含む場合と、含まない場合がある。ルータを通して、メッセージアナライザに返され、MessageReaderException と同様に処理される