13 診断コンテキストを管理するためのDyeInjectionモニターの構成

WebLogic診断フレームワーク(WLDF)のインストゥルメンテーション・コンポーネントには、HTTPやRMIなどのリクエストを一意に識別し、システムにおけるそのフローを追跡する方法も用意されています。システムが受信するあらゆるリクエストの特定の特性(発信元のユーザー、クライアント・アドレスなど)を確認し、そのリクエストに診断コンテキストをアタッチするようにWLDFを構成できます。この機能によって、特定のリクエストの経過時間などを測定でき、すべてのリクエストがシステムを通過する際にどのように処理されているかを把握することができます。

診断コンテキストは、リクエストの特性を表す64ビットの仕分けベクトルと一意のコンテキストIDから構成されます。特定のリクエストに関連付けられたコンテキストIDはイベント・アーカイブに記録され、以下の処理に使用できます。

• インストゥルメンテーション・イベントの生成を調整します。つまり、指定された条件に一致する場合のイベントの生成頻度を決定します。

• ログ・レコードをリクエストに関連付けます。

• WLDFアクセサ・コンポーネントを使用して、ログ・レコードやイベント・レコードの検索をフィルタ処理します(「データ・アクセサを使用した診断データへのアクセス」を参照)。

WLSTを使用してDyeInjectionモニターを動的に作成する方法の例は、「サンプル: DyeInjectionモニターの動的な作成」を参照してください。

この章には次の項が含まれます:

• 診断コンテキストの内容、ライフサイクル、構成
  診断コンテキストには、一意のコンテキストIDおよび64ビットの仕分けベクトルが含まれます。仕分けベクトルには、リクエストに関連した診断コンテキストの特性を識別するために設定されるフラグが含まれます。
• プロセスの概要
  DyeInjectionモニターはリクエストを調査して、仕分けベクトルで構成されている仕分け値のいずれかがリクエストの属性と一致しているかどうかを確認します。DyeInjectionモニターを構成して、リクエストを特定してその流れを追跡できます。リクエストの追跡は、システムを通過するリクエストがどのように処理されるか確認するために役立ちます。
• DyeInjectionモニターによる仕分けベクトルの構成
  DyeInjectionモニターを使用して仕訳ベクトルを構成し、システム内のリクエストをモニターします。すべてのリクエストがDyeInjectionモニターの構成に対してチェックされ、診断コンテキストが作成されてリクエストにアタッチされます。
• インストゥルメンテーション・イベントの量を制御するスロットル機能の使用方法
  スロットル機能を使用すると、診断モジュールのモニターで処理されるリクエストの数を制御できます。
• weblogic.diagnostics.contextの使用
  weblogic.diagnostics.contextパッケージを使用すると、アプリケーションから診断コンテキストにアクセスできます。

診断コンテキストの内容、ライフサイクル、構成

診断コンテキストには、一意のコンテキストIDおよび64ビットの仕分けベクトルが含まれます。仕分けベクトルには、リクエストに関連した診断コンテキストの特性を識別するために設定されるフラグが含まれます。

現在、仕分けベクトルの32ビットが使用可能な各仕分けフラグにつき1つずつ使用されています(表13-1を参照してください)。

• コンテキストのライフ・サイクルとコンテキストID
  
• 仕分け、仕分けフラグ、仕分けベクトル
  
• 診断コンテキストが構成される場所
  

コンテキストのライフ・サイクルとコンテキストID

リクエストの診断コンテキストはそのリクエストがシステムに参加したとき(たとえばクライアントでHTTPリクエストを発行したとき)に作成され、初期化されます。診断コンテキストは、リクエストがスレッド境界やJava仮想マシン(Java Virtual Machine JVM)境界を超えてもそのリクエストにアタッチされ続けます。診断コンテキストは、リクエストのライフ・サイクル全体を通して存続します。

すべての診断コンテキストは、ドメイン内で一意のコンテキストIDによって識別されます。このコンテキストIDはリクエストと共に移動するため、特定のリクエストがシステムで処理される過程でそのリクエストに関連付けられたイベントやログ・エントリを特定することができます。

仕分け、仕分けフラグ、仕分けベクトル

コンテキスト情報は、64ビットの仕分けベクトルとしてリクエストと共に移動します。それぞれのビットは仕分けの存在を識別するフラグです。各仕分けがリクエストの1つの属性(発信したユーザー、発信したクライアントIPアドレス、アクセス・プロトコルなど)を表します。

特定の属性に対応する仕分けフラグが設定されている場合、その属性が存在することを示しています。フラグが設定されていない場合、その属性が存在しないことを示しています。

たとえば、次のような構成を考えます:

• リクエストの発信元がIPアドレス127.0.0.1であることを示すために仕分けフラグADDR1が構成されています。

• リクエストの発信元がIPアドレス127.0.0.2であることを示すために仕分けフラグADDR2が構成されています。

• USER1フラグは、ユーザー[e-mail]からのリクエストを示すために構成されます。

IPアドレス127.0.0.1からのリクエストがシステムに参加すると、そのリクエストの仕分けベクトルのADDR1仕分けフラグが設定されます。ADDR2とUSER1仕分けフラグは設定されません。

[e-mail]からのリクエストが127.0.0.1か127.0.0.2以外のIPアドレスからのシステムを登録する場合、リクエストに対して仕分けベクトルにUSER1フラグが設定されます。ADDR1とADDR2仕分けフラグは設定されません。

[e-mail]からのリクエストが127.0.0.2のIPアドレスからシステムを登録する場合、リクエストに対する仕分けベクトルにUSER1とADDR2フラグが設定されます。ADDR1フラグは設定されません。

診断コンテキストを利用する診断およびモニター機能では、仕分けベクトルを調査することにより、1つまたは複数の属性が存在する(すなわち、関連付けられたフラグが設定されている)かどうかを特定することができます。前述の例では、診断モニターを構成して、ADDR1仕分けの設定されたすべてのリクエスト、つまりIPアドレス127.0.0.1から発信されたすべてのリクエストをトレースできます。また、ADDR1とUSER1の両方の仕分けの設定されたすべてのリクエスト、つまりIPアドレス127.0.0.1のユーザー[e-mail]から発信されたすべてのリクエストをトレースする診断モニターを構成することもできます(127.0.0.1の他のユーザーからのリクエストはトレースされません)。

また、仕分けベクトルには受信するリクエストに対して仕分け頻度を指定するTHROTTLE仕分けもあります。この特別な仕分けの詳細は、「THROTTLE仕分けフラグ」を参照してください。

利用できる仕分けとそれによって表される属性のリストについては、「DyeInjectionモニターでサポートされる仕分け」を参照してください。仕分けベクトルを構成および使用するプロセスについては、この章の次の項で説明します。

診断コンテキストが構成される場所

診断コンテキストは、診断モジュールの一部として構成されます。診断コンテキストを構成するのにサーバー・レベルにDyeInjectionモニターを使用します。DyeInjectionモニターは標準の診断モニターであるため、その動作は変更できません。DyeInjectionモニターがコードにウィービングされるジョインポイントは、リクエストがシステムに参加する可能性のある場所です。

診断アクションによって、各リクエストがDyeInjectionモニターの構成に対してチェックされてから、そのリクエストにコンテキストが作成されてアタッチされ、必要に応じた仕分けフラグが設定されます。リクエストに設定される仕分けフラグが、下流の診断モニターに対して構成される仕分けフラグに適合する場合、リクエストの関連Context IDがあるイベントはEventアーカイブに追加されます。たとえば、リクエストがUSER1とADDR1仕分けフラグのみを設定し、USER1とADDR1フラグ設定の両方で対してリクエストを追跡するための構成された診断モニターがある場合(他に設定されたフラグがない)イベントはEventアーカイブに追加されます。

診断モニターのタイプ、(ジョインポイントを定義する)ポイントカット、および診断アクションについては、「インストゥルメンテーションの構成」を参照してください。

プロセスの概要

DyeInjectionモニターはリクエストを調査して、仕分けベクトルで構成されている仕分け値のいずれかがリクエストの属性と一致しているかどうかを確認します。DyeInjectionモニターを構成して、リクエストを特定してその流れを追跡できます。リクエストの追跡は、システムを通過するリクエストがどのように処理されるか確認するために役立ちます。

ここでは、サーバー・スコープの診断モジュールにおけるコンテキストの構成と使用について概説します。

1. DyeInjectionモジュールを介して仕分けベクトルを構成します。「DyeInjectionモニターを介した仕分けベクトルの構成」を参照してください。

2. システムにリクエストが入ると、そのリクエストの診断コンテキストがWLDFによって作成されインスタンス化されます。このコンテキストには、一意のコンテキストIDと仕分けベクトルが含まれます。

3. DyeInjectionモニターは、WLDF診断モジュール内でシステム・レベルで有効化されている場合、そのリクエストを調査して、仕分けベクトルで構成されている仕分け値のいずれかがリクエストの属性と一致しているかどうかを確認します。たとえば、そのリクエストの発行元がUSER1またはUSER2に関連付けられているユーザーかどうか、およびADDR1またはADDR2に関連付けられているIPアドレスかどうかが確認されます。

4. DyeInjectionモニターは、リクエストの属性に一致する各仕分け値について、診断コンテキスト内で関連付けられている仕分けビットを設定します。たとえば、DyeInjectionモニターが、USER1=weblogic、USER2=[e-mail]、ADDR1=127.0.0.1、ADDR2=127.0.0.2のように構成されており、リクエストの発行元がIPアドレス127.0.0.2のユーザーweblogicである場合、仕分けベクトル内でUSER1およびADDR2仕分けビットが設定されます。

5. リクエストがシステム内を移動する過程では、仕分けベクトルを持つ診断コンテキストもそのリクエストと共に移動します。この64ビットの仕分けベクトルの内容はフラグのみで、値は含まれません。そのため、この例では明示的に設定した2つのフラグUSER1とADDR2のみが仕分けベクトルに含まれます。これにはUSER1とADDR2に関する実際のユーザー名とIPアドレスは含まれていません。

   ノート:

   すべての仕分けベクトルには、暗黙的にPROTOCOL仕分け群の1つも含まれます。これについては、「DyeInjectionモニターを介した仕分けベクトルの構成」で説明します。

6. 管理者は下流のコード内で診断モニター(アプリケーション・スコープまたはサーバー・スコープの診断モニター)がアクティブとなるように構成し、モニターの仕分けマスクをUSER1およびADDR2と設定します。

7. 診断モニターは、診断コンテキストの仕分けベクトルで設定されている仕分けフラグが診断モニターの仕分けマスクと一致すると、関連付けられている1つまたは複数のアクションを実行します。

   この例では、USER1とADDR2フラグが仕分けベクトルに設定されていると、モニターは動作を実行します。さらに、リクエストに関連するイベントがイベント・アーカイブに書き込まれます。

DyeInjectionモニターによる仕分けベクトルの構成

DyeInjectionモニターを使用して仕訳ベクトルを構成し、システム内のリクエストをモニターします。すべてのリクエストがDyeInjectionモニターの構成に対してチェックされ、診断コンテキストが作成されてリクエストにアタッチされます。

システムに参加するすべてのリクエストに対して診断コンテキストを作成するには:

1. 「診断モジュールのサマリー」ページで、モニターする1つまたは複数のサーバー用に診断モジュールを作成します。「組込みに基づいたカスタム診断システム・モジュールの作成」を参照してください。
2. 新規に作成したモジュールの名前をクリックして、「<MODLE_NAME>の設定」ページを開きます。
3. 「構成 - インストゥルメンテーション」タブで、「有効」チェック・ボックスを選択します。
4. 「このモジュールの診断モニター」タブで、「追加と削除」ボタンを使用してDyeInjectionモニターを追加します。
5. DyeInjectionモニターをクリックして、「DyeInjectionの設定」ページを開きます。
6. 「有効化」チェック・ボックスを選択します。(1つの診断モジュールで同時に使用できるDyeInjectionモニターは1つのみ。)

DyeInjectionモニターを構成するには、仕分けに値を割り当てます。使用できる仕分けフラグについては、表13-1を参照してください。

たとえば、USER1=weblogic、USER2=[e-mail]、ADDR1=127.0.0.1、ADDR2=127.0.0.2などのようにフラグを設定できます。基本的に、モニターするリクエストの発行元となる1人または複数のユーザー、1つまたは複数のIPアドレスに対して1つまたは複数のフラグの値を設定します。

たとえば、IPアドレスが127.0.0.1のクライアントからadmin@avitekというユーザーによって開始されたすべてのリクエストをモニターするには、値admin@avitekをUSER1に、値127.0.0.1をADDR1に割り当てます。

• DyeInjectionモニターでサポートされる仕分け
  
• PROTOCOL仕分けフラグ
  
• THROTTLE仕分けフラグ
  
• 診断コンテキストの作成条件
  

DyeInjectionモニターでサポートされる仕分け

仕分けベクトルで利用できる仕分けについて、以下の表にリストして説明します。

表13-1 サポートされる診断コンテキストの仕分けと対応するリクエストのプロトコル

仕分けフラグ	説明
ADDR1 ADDR2 ADDR3 ADDR4	仕分けADDR1、ADDR2、ADDR3、およびADDR4を使用して、リクエストを発信したクライアントのIPアドレスを指定します。DyeInjectionモニターのプロパティ(ADDR1、ADDR2、ADDR3、ADDR4)に指定されているIPアドレスからリクエストが発信されると、それぞれ対応する仕分けフラグがそのリクエストの診断コンテキストに設定されます。 これらの仕分けを使用してDNS名を指定することはできません。
CONNECTOR1 CONNECTOR2 CONNECTOR3 CONNECTOR4	仕分けCONNECTOR1、CONNECTOR2、CONNECTOR3、およびCONNECTOR4を使用して、コネクタ・ドライバの特性を識別します。 これらの仕分けフィルタは、コネクタ・ドライバによって状況に特有のリクエストのプロパティを識別するために設定されます。これらは、ユーザーが記述子ファイルに直接構成するものではありません。これらの仕分けにはコネクタ・ドライバによって(コネクタAPIを使用して)値が割り当てられ、その結果、接続に関する情報が診断コンテキストに保持されて運ばれます。
COOKIE1 COOKIE2 COOKIE3 COOKIE4	COOKIE1、COOKIE2、COOKIE3、およびCOOKIE4は、HTTP/Sリクエストにweblogic.diagnostics.dyeというCookieが含まれていて、その値がDyeInjectionモニターのそれぞれに対応するプロパティ(COOKIE1、COOKIE2、COOKIE3、COOKIE4)の値と同じ場合に、そのリクエストの診断コンテキストに設定されます。
DYE_0 DYE_1 DYE_2 DYE_3 DYE_4 DYE_5 DYE_6 DYE_7	DYE_0からDYE_7は、アプリケーションの開発者のみが使用できます。「weblogic.diagnostics.contextの使用」を参照してください。
PROTOCOL_HTTP PROTOCOL_IIOP PROTOCOL_JRMP PROTOCOL_RMI PROTOCOL_SOAP PROTOCOL_SSL PROTOCOL_T3	DyeInjectionモニターによりリクエストに使用されているプロトコルが暗黙的に識別され、使用されているプロトコルに応じて、仕分けベクトルの適切な仕分け(1つまたは複数)が設定されます。 PROTOCOL_HTTPは、リクエストにHTTPまたはHTTPSプロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_IIOPは、リクエストにInternet Inter-ORB Protocol (IIOP)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_JRMPは、リクエストにJava Remote Method Protocol (JRMP)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_RMIは、リクエストにJava Remote Method Invocation (RMI)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_SSLは、リクエストにSecure Sockets Layer (SSL)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_T3は、リクエストにT3またはT3プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。
THROTTLE	THROTTLE仕分けは、リクエストがDyeInjectionモニターのTHROTTLE_INTERVALまたはTHROTTLE_RATEプロパティに指定された要件を満たす場合に、リクエストの診断コンテキストに設定されます。
USER1 USER2 USER3 USER4	仕分けUSER1、USER2、USER3、およびUSER4を使用して、リクエストを発信したクライアントのユーザー名を指定します。DyeInjectionモニターのプロパティ(USER1、USER2、USER3、USER4)に指定されているユーザーによってリクエストが発信されると、それぞれに対応する仕分けフラグがそのリクエストの診断コンテキストに設定されます。

PROTOCOL仕分けフラグ

DyeInjectionモニターの仕分けフラグUSERn, ADDRn, COOKIEn, and CONNECTORnについては、明示的に値を設定する必要があります。一方、フラグPROTOCOL_HTTP、PROTOCOL_IIOP、ROTOCOL_JRMP、PROTOCOL_RMI、PROTOCOL_SOAP、PROTOCOL_SSLおよびPROTOCOL_T3は、WLDFにより暗黙的に設定されます。DyeInjectionモニターが有効になっていれば、すべてのリクエストに適切なプロトコルの仕分けが挿入されます。たとえば、HTTPによって届いたリクエストにはすべて仕分けPROTOCOL_HTTPが挿入されます。

THROTTLE仕分けフラグ

THROTTLE仕分けフラグを使用して、受信リクエストのうち仕分けを設定するものの量を制御できます。THROTTLEは他のフラグとは異なる方法で構成され、WLDFでの使用方法も異なります。詳細は、「インストゥルメンテーション・イベントの量を制御するスロットル機能の使用方法」,を参照してください。

診断コンテキストの作成条件

診断モジュールでDyeInjectionモニターが有効になっている場合、受信するすべてのリクエストについて診断コンテキストが作成されます。診断モジュールでインストゥルメンテーションを有効にするとき、DyeInjectionモニターはデフォルトで有効にされます。これにより診断コンテキストIDが利用でき、イベントが関連付けられます。DyeInjectionモニターに明示的に設定されているプロパティがない場合でも、一意のコンテキストIDと、暗黙的なPROTOCOL仕分け群のうち1つが指定された仕分けベクトルがすべてのリクエストのコンテキストに含まれます。

DyeInjectionモニターが診断モジュールに無効になっている場合、受信するどのリクエストについても診断コンテキストは作成されません。

インストゥルメンテーション・イベントの量を制御するスロットル機能の使用方法

スロットル機能を使用すると、診断モジュールのモニターで処理されるリクエストの数を制御できます。

スロットル機能は、DyeInjectionモニターに定義されるTHROTTLE仕分けを使用して構成します。

ノート:

USERnおよびADDR n仕分けを使用すると、特定のユーザーまたはIPアドレスからのリクエストを検査することができます。ただし、任意のユーザー・トランザクションを調べる手段にはなりません。THROTTLE仕分けでは、リクエストのサンプリングによりその機能を提供します。

• THROTTLE仕分けの構成
  
• 委任モニター、カスタム・モニターでのスロットル機能の処理方法
  

THROTTLE仕分けの構成

仕分けベクトルの他の仕分けと異なり、THROTTLE仕分けは2つのプロパティを通じて構成されます。

• THROTTLE_INTERVALに、新しく受信されるリクエストにTHROTTLE仕分けが指定されるまでの間隔(ミリ秒)を設定します。

  THROTTLE_INTERVALが0より大きい場合、DyeInjectionモニターでは、最後にTHROTTLE仕分けが指定されたリクエストが届いてから少なくともTHROTTLE_INTERVALのミリ秒数のみ経過した後に受信されたリクエストに対して、その新しいリクエストの仕分けベクトルにあるTHROTTLE仕分けフラグが設定されます。たとえばTHROTTLE_INTERVAL=3000と指定した場合、DyeInjectionモニターでは少なくとも3000ミリ秒の待機後に、受信したリクエストにTHROTTLE仕分けが指定されます。

• THROTTLE_RATEに、新しく受信されるリクエストにTHROTTLE仕分けが指定される度合い(受信されるリクエストの数で表します)を設定します。

  THROTTLE_RATEが0より大きい場合、DyeInjectionモニターでは、最後にTHROTTLE仕分けが設定されたリクエスト以降のリクエストの数がTHROTTLE_RATEと同じになったときに、受信されたリクエストの仕分けベクトルにあるTHROTTLE仕分けフラグが設定されます。たとえば、THROTTLE_RATE = 6と指定した場合、6リクエストごとにTHROTTLE仕分けが指定されます。

THROTTLE_INTERVALとTHROTTLE_RATEは併用できます。いずれかのリクエストを満たす場合、リクエストはTHROTTLE仕分けされます。

THROTTLE_INTERVALまたはTHROTTLE_RATEのどちらかに値を割り当てる場合(両方に割り当てることもいずれにも割り当てないことも可)、THROTTLE仕分けが構成されます。

例13-1に、結果として診断モジュールの記述子ファイルに記述される構成を示します。

例13-1 DyeInjectionモニターのTHROTTLE構成のサンプル、DIAG_MODULE.xml内

<wldf-resource>
  <name>MyDiagnosticModule</name>
  <instrumentation>
    <wldf-instrumentation-monitor>
      <name>DyeInjection</name>
      <properties>
        THROTTLE_INTERVAL=3000
        THROTTLE_RATE=6
      </properties>
    </wldf-instrumentation-monitor>
  </instrumentation>
<!-- Other elements to configure this diagnostic monitor -->
</wldf-resource>

例13-2に、仕分けマスクにTHROTTLE仕分けが設定されているJDBC_Before_Start_Internal委任モニターの構成を示します。

例13-2 委任モニターの仕分けマスクにTHROTTLEを設定する構成のサンプル(DIAG_MODULE.xml内)

<wldf-resource>
  <name>MyDiagnosticModule</name>
  <instrumentation>
    <wldf-instrumentation-monitor>
      <name>JDBC_Before_Start_Internal</name>
      <enabled>true</enabled>
      <dye-mask>THROTTLE</dye-mask>
    </wldf-instrumentation-monitor>
  </instrumentation>
<!-- Other elements to configure this diagnostic monitor -->
</wldf-resource>

委任モニター、カスタム・モニターでのスロットル機能の処理方法

仕分けマスクおよび仕分けフィルタ処理によるメカニズムを使用して、委任モニターおよびカスタム・モニターで処理するために渡すリクエストを、リクエストのプロパティに基づいて制限できます。「DyeInjectionモニターを介した仕分けベクトルの構成」で説明したように、リクエストにおけるプロパティの存在は仕分けの存在によって示されます。THROTTLE仕分けもそうした仕分けの1つと見なされるため、THROTTLEも他の仕分けと同様にフィルタできます。

以下に、スロットル機能の処理方法について説明します。

• 委任モニターまたはカスタム・モニターの仕分けフィルタ処理が有効になっていてモニターに仕分けマスクがある場合、仕分けマスクに基づいてフィルタ処理が実行されます。このマスクにはTHROTTLE仕分けが含まれても含まれなくても構いません。仕分けマスクにTHROTTLEが含まれる場合、モニターに渡されるリクエストの仕分けベクトルにもTHROTTLEが含まれている必要があります。一方、仕分けマスクにTHROTTLEが含まれない場合、リクエストの仕分けベクトルにTHROTTLEが含まれているかどうかにかかわらず、適切なリクエストはすべてモニターに渡されます。

• 委任モニターまたはカスタム・モニターの仕分けフィルタ処理が有効でなく、DyeInjectionモニターにTHROTTLEプロパティが設定されていない場合、仕分けフィルタ処理もスロットル機能も実行されません。

• 委任モニターまたはカスタム・モニターの仕分けフィルタ処理が有効でなく、DyeInjectionモニターにTHROTTLEが構成されている場合、委任モニターでは仕分けマスクが無視されますが、すべてのリクエストについてTHROTTLE仕分けの存在がチェックされます。THROTTLE仕分けの指定されたリクエストのみが委任モニターに渡されて処理されます。したがって、THROTTLE_RATEまたはTHROTTLE_INTERVAL (あるいはその両方)をDyeInjectionモニターに設定すると、すべての委任モニターで処理されるリクエストの数が減少します。スロットル機能を利用するために、すべての委任モニターに仕分けマスクを構成する必要はありません。

• 委任モニターまたはカスタム・モニターの仕分けフィルタ処理が有効になっていて、仕分けマスクに設定されている仕分けがTHROTTLEのみの場合、THROTTLE仕分けが指定されているリクエストのみが委任モニターに渡されます。この動作は、仕分けフィルタ処理が有効でなくDyeInjectionモニターにTHROTTLEが構成されている場合と同じです。

weblogic.diagnostics.contextの使い方

weblogic.diagnostics.contextパッケージを使用すると、アプリケーションから診断コンテキストにアクセスできます。

アプリケーションでは一連のweblogic.diagnostics.context.DiagnosticContextHelper APIを使用して、以下の関数を実行できます。

• 診断コンテキストの不変のコンテキストIDの検査。

• コンテキストの仕分けベクトルにある仕分けフラグの設定の検査。

• 有効な仕分けフラグ名の配列の取得。

• コンテキストの仕分けベクトルにあるDYE_0からDYE_7までのフラグについての設定または設定の解除。(これらのフラグ・ビットをXMLを介して設定する方法はありません。DyeInjectionモニターの<properties>を構成すると、アプリケーション固有でないフラグ・ビットについてXMLを介して設定できますが、仕分けベクトルのDYE_0からDYE_7までを設定できるのはsetDye()メソッドのみです)。

• 診断コンテキストへのペイロード(String型)のアタッチ、または既存のペイロードの読込み。

以下についてはアプリケーションでは処理できません。

• アプリケーション用に予約されている8フラグ以外の仕分けベクトルのフラグの設定。

• 仕分けベクトルの同じアプリケーション・フラグが別のアプリケーションで設定されることの回避。適切に動作するアプリケーションであれば、仕分けフラグを設定する前にあらかじめ設定されているかどうかをテストできます。

• 別のアプリケーションによるペイロードの置換えの回避。適切に動作するアプリケーションであれば、ペイロードを追加する前にペイロードが存在するかどうかをテストできます。

ノート:

診断コンテキストのペイロードは、同一実行コンテキスト内の他のコードによって表示可能で、Workインスタンスと共にプロセスから流れ、同一実行コンテキスト内で実行されている他のコードによって上書き可能です。そのため、アプリケーションで次の動作を確認する必要があります。

• getPayload()メソッドによって返される可能性のあるような機密データをペイロードには含めないようにします。

• コンテキスト・ペイロードで使用可能な特定のデータに関する依存関係を作成しないでください。たとえば、アプリケーションは特定のコンテキストIDへ依存してはなりません。アプリケーションは、ペイロードのコンテンツを使用する場合、最初にそのコンテンツが期待通りのものか検証する必要があります。

アプリケーションでDYE_0からDYE_7までのフラグうち1つまたは複数を設定した時点以降には、モニターや別のアプリケーションでそれらのフラグをチェックするように仕分けマスクを設定し、そのフラグ(群)がコンテキストの仕分けベクトルに存在する場合にアクションを実行できます。診断コンテキストにペイロードがアタッチされている場合、モニターで実行されるアクションはペイロードに格納されてアーカイブ化され、結果としてアクセサ・コンポーネントを通じて利用できるようになります。

例13-3は、診断コンテキストを(暗黙的に)作成し、コンテキストIDを出力し、DYE_0フラグの値をチェックし、その後DYE_0を設定する簡単なサンプルです。

例13-3 例: DiagnosticContextExample.java

package weblogic.diagnostics.examples;
import weblogic.diagnostics.context.DiagnosticContextHelper;
public class DiagnosticContextExample {
 public static void main(String args[]) throws Exception {
   System.out.println("\nContextId=" +
     DiagnosticContextHelper.getContextId());
     System.out.println("isDyedWith(DYE_0)=" +
       DiagnosticContextHelper.isDyedWith(DiagnosticContextHelper.DYE_0));
     DiagnosticContextHelper.setDye(DiagnosticContextHelper.DYE_0, true);
     System.out.println("isDyedWith(DYE_0)=" +
       DiagnosticContextHelper.isDyedWith(DiagnosticContextHelper.DYE_0));
 }
}