ヘッダーをスキップ
Oracle® Fusion Middleware Oracle WebLogic Server診断フレームワークの構成と使用
11g リリース1(10.3.6)
B60994-04
  ドキュメント・ライブラリへ移動
ライブラリ		 製品リストヘ移動
製品		 目次へ移動
目次
前
前 		 次
次		  

11 インストゥルメンテーションの構成

WebLogic診断フレームワーク(WLDF)のインストゥルメンテーション・コンポーネントは、WebLogic Serverインスタンスおよびそのサーバー・インスタンスで実行中のアプリケーションに診断コードを追加するためのメカニズムを提供します。WLDFのインストゥルメンテーションでの主な機能は次のとおりです。

WLDFには、あらかじめ定義された診断モニターと診断アクションのライブラリが用意されています。また、アプリケーション・スコープのカスタム・モニターを作成し、診断コードが挿入されるアプリケーション内の位置をユーザーが決めることもできます。

インストゥルメンテーションについては、次の項で説明します。

概念と用語

この項では、インストゥルメンテーションの概念と用語について説明します。以下の内容について説明します。

インストゥルメンテーションのスコープ

実行可能なインストゥルメンテーション・サービスには、システム・レベル(サーバーおよびクラスタ)のものとアプリケーション・レベルのものがあります。概念、サービス、構成オプション、および実装機能の多くは両者とも同じです。ただし、相違点もいくつかあります。それらについては、このドキュメントで説明しています。サーバー・スコープ・インストゥルメンテーションは、WebLogic Serverインスタンスおよびクラスタ固有のインストゥルメンテーションの構成と機能を指します。これに対して、アプリケーション・スコープ・インストゥルメンテーションは、WebLogic Serverにデプロイされているアプリケーション固有の構成と機能を指します。スコープは各診断モニターに組み込まれており、ユーザーがモニターのスコープを変更することはできません。

構成とデプロイメント

サーバーまたはクラスタ向けのサーバー・スコープ・インストゥルメンテーションは、診断モジュールの一部として、DOMAIN_NAME/config/diagnosticsディレクトリにあるXML構成ファイルで構成およびデプロイされ、config.xmlからリンクされています。

アプリケーション・スコープ・インストゥルメンテーションも、診断モジュールとして構成およびデプロイされます。ただし、アプリケーション・スコープの場合は、デプロイされるアプリケーションのARCHIVE_PATH/META-INFディレクトリ内のアプリケーション・アーカイブとともにパッケージ化されたweblogic-diagnostics.xmlというXML構成ファイルを使用します。

ジョインポイント、ポイントカット、診断ロケーション

インストゥルメンテーション・コードは、サーバーおよびアプリケーションのコード内の特定の場所に挿入(またはウィービング)されます。この特定の場所を表すために、以下の用語が使用されています。

  • 「ジョインポイント」は、クラス内の特定の場所です。たとえば、メソッドの入り口や出口のポイント、メソッド内のコール・サイトなどを指します。

  • 「ポイントカット」は、ジョインポイントのセットを示す用語で、作業項目のスケジューリング、開始、および実行に関わるすべてのメソッドなどを指します。ポイントカットを定義するXML要素は<pointcut>です。ポイントカットについては、「カスタム・モニターのポイントカットの定義」を参照してください。

  • 「診断ロケーション」は、ジョインポイントを基準にした、診断アクティビティが実行される位置です。診断ロケーションには、Before(ジョインポイントの前)、After(ジョインポイントの後)、Around(ジョインポイントの前後)のいずれかを指定できます。診断ロケーションを定義するXML要素は<location-type>です。

診断モニターのタイプ

診断モニターは、そのスコープと種類によって分類されます。スコープは、サーバー・スコープかアプリケーション・スコープのどちらかです。種類は、モニターのポイントカット、診断場所、およびアクションによって決まります。たとえば、Servlet_Around_Serviceはアプリケーション・スコープの委任モニターです。このモニターを使用すると、特定のサーブレット・メソッドやJSPメソッドの入り口と出口で診断アクションをトリガーできます。

診断モニターには、次に示す3種類があります。

  • 標準モニターは、あらかじめ定義されている特定のポイントカットおよび診断ロケーションで、あらかじめ定義されている特定の診断アクションを実行します。標準モニターでは、これらのアクション、ポイントカット、診断ロケーションはハード・コード化されています。モニターを有効または無効にできますが、モニターの動作は変更できません。

    標準モニターはDyeInjectionモニターのみです。このモニターはサーバー・スコープ・モニターであり、サーバー・レベルで診断コンテキストを作成して仕分けの注入を構成するために使用します。第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。

    標準のアプリケーション・スコープ・モニターはHttpSessionDebugのみです。このモニターは、HTTP Sessionオブジェクトを検査するために使用します。

  • 委任モニターでは、スコープ、ポイントカットおよびロケーションがハード・コード化されていますが、モニターで実行するアクションは、ユーザーが選択します。つまり、このモニターでは、あらかじめ定義されているアクションにかわって、ユーザーが選択したアクションが実行されます。委任モニターは、サーバー・スコープかアプリケーション・スコープのどちらかです。

    委任モニターは、それ自体では完成していません。委任モニターが意味のある処理を行うには、少なくとも1つのアクションをモニターに割り当てる必要があります。

    すべてのアクションがどのモニターにも割当て可能なわけではありません。管理コンソールで委任モニターを構成する場合、選択したモニターで対応可能なアクションのみを指定できます。WLSTを使用するか記述子ファイルを手動で編集して委任モニターを構成する場合、アクションはそのモニターに対応する必要があります。WLDFは、委任モニターのXML構成ファイルがデプロイ時にロードされるときにその委任モニターを検証します。

    WLDFインストゥルメンテーション・ライブラリで利用可能な委任モニターとアクションについては付録B「WLDFインストゥルメンテーション・ライブラリ」を参照してください。

  • カスタム・モニターは、次の特徴を持つ特殊な委任モニターです。

    • アプリケーション・スコープ・インストゥルメンテーションにのみ利用できます。

    • あらかじめ定義されたポイントカットやロケーションがありません。

    カスタム・モニターを構成するには、カスタム・モニターに名前を付け、モニターで使用するポイントカットと診断ロケーションを定義し、あらかじめ定義されている診断アクションのセットからアクションを割り当てます。<pointcut>要素と<location type>要素はカスタム・モニターでは必須です。

表11-1に、各種類のモニターの違いを簡単に示します。

表11-1 診断監視のタイプ

モニター・タイプ スコープ ポイントカット 場所 アクション

標準モニター

サーバー

固定

固定

固定

委任モニター

サーバーまたはアプリケーション

固定

固定

構成可能

カスタム・モニター

アプリケーション

構成可能

構成可能

構成可能

モニターに対して「仕分けマスク」を設定すると、診断アクションがトリガーされるタイミングを制限できます。このマスクによって、診断コンテキストのどの仕分けフラグがアクションをトリガーするかが決まります。モニターの仕分けマスクの設定については、「<wldf-instrumentation-monitor> XML要素」を参照してください。


注意:

診断コンテキスト、仕分けの注入、および仕分けフィルタについては、第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」で説明します。

診断アクション

診断アクションは、関連する委任モニターまたはカスタム・モニターに対応する診断コードを実行します(標準モニターの場合、アクションはあらかじめ定義されています)。委任モニターまたはカスタム・モニターがなんらかの意味のある処理を行うには、モニターに対して少なくとも1つのアクションを構成する必要があります。

WLDF診断ライブラリでは、以下のアクションを利用できます。アクションをモニターにアタッチするには、DIAG_MODULE.xml構成ファイルの<action>要素でアクション名を指定します。

  • DisplayArgumentsAction

  • MethodInvocationStatisticsAction

  • MethodMemoryAllocationStatisticsAction

  • StackDumpAction

  • ThreadDumpAction

  • TraceAction

  • TraceElapsedTimeAction

  • TraceMemoryAllocationAction

アクションは、モニターに正しく対応している必要があります。たとえば、TraceElapsedTimeアクションは、診断ロケーションの種類がAroundのカスタム・モニター、または委任モニターで使用できます。詳細は、付録B「WLDFインストゥルメンテーション・ライブラリ」を参照してください。

インストゥルメンテーション構成ファイル

インストゥルメンテーションは、診断記述子の一部としてXML構成ファイルで構成されます。このファイルの名前と格納場所は、システム・レベル(サーバー・スコープ)のインストゥルメンテーションを実装しているか、アプリケーション・レベル(アプリケーション・スコープ)のインストゥルメンテーションを実装しているかによって異なります。

診断XMLスキーマは以下の場所にあります。

http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd

各診断記述子ファイルは、以下の行で始まる必要があります。

<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

WLDFリソースの構成の概要は、第4章「WLDFの構成について」を参照してください。

インストゥルメンテーションに使用するXML要素

この項では、記述子のコード・フラグメント、インストゥルメンテーションの構成に使用するXML要素をまとめた表、および診断モニターについて簡単に説明した表を示します。

<instrumentation> XML要素

表11-2では、DIAG_MODULE.xmlファイルの<instrumentation>要素について説明します。次の構成フラグメントでは、この要素の使用方法を示します。

<wldf-resource>
  <name>MyDiagnosticModule</name>
<instrumentation>
   <enabled>true</enabled>
   <!-- The following <include> element would apply only to an
        application-scoped Instrumentation descriptor -->
   <include>foo.bar.com.*</include>
   <!-- &lt;wldf-instrumentation-monitor&gt; elements to define diagnostic 
        monitors for this diagnostic module -->
</instrumentation>
<!-- Other elements to configure this diagnostic module -->
</wldf-resource>

表11-2 DIAG_MODULE.xml構成ファイル内の<instrumentation> XML要素

要素 説明

<instrumentation>

インストゥルメンテーション構成を開始する要素。

<enabled>

trueの場合、インストゥルメンテーションは有効です。falseの場合、インストゥルメントされたコードは、このインストゥルメンテーション・スコープのクラスに挿入されておらず、このスコープ内のすべての診断モニターは無効です。デフォルト値はfalseです。

サーバーとそこにデプロイされているアプリケーションに対するインストゥルメンテーションを有効にするには、サーバー・レベルでインストゥルメンテーションを有効にする必要があります。さらに、(サーバー・スコープのインストゥルメンテーションの有効化に加えて)アプリケーションに対するインストゥルメンテーションを有効にするには、アプリケーション・レベルでインストゥルメンテーションを有効にする必要があります。

<include>

インストゥルメントされたコードを挿入できるクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<include>要素を指定できます。指定した場合、インストゥルメンテーションの対象となるには、クラスは<include>パターンに一致する必要があります。

アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>または<exclude>パターンを指定すると、アプリケーション・スコープ全体に適用されます。

注意: 特定の診断モニターに対して<include>パターンおよび<exclude>パターンを指定することもできます。表11-1の<include>および<exclude>の項目を参照してください。

クラスがロードされると、インストゥルメンテーション・コードを挿入する前に、include/excludeのパターン・チェックに成功する必要があります。クラスがinclude/excludeのパターン・チェックに成功した場合でも、インストゥルメントされるかどうかは、構成記述子で定義されている診断モニターによって決まります。ライブラリ内にあるアプリケーション・スコープの委任モニターには、あらかじめ定義されている独自のクラスおよびポイントカットがあります。カスタム・モニターでは、独自のポイントカット式を指定します。そのため、include/excludeのパターン・チェックに成功しても、クラスはインストゥルメントされない場合があります。

注意:インストゥルメンテーションは、クラスのロード時にアプリケーションに挿入されます。サイズの大きなアプリケーションを頻繁にロードする環境では、<include>または<exclude>要素をうまく使用すれば、利便性の向上を期待できます。小さなアプリケーションや、中規模または大規模のアプリケーションでも頻繁にロードしない場合は、この要素を無視してもかまいません。

<exclude>

インストゥルメントされたコードを挿入できないクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<exclude>要素を指定できます。指定した場合、<exclude>パターンに一致するクラスはインストゥルメントされません。

アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>要素の前述の説明を参照してください。

<wldf-instrumentation-monitor> XML要素

診断モニターは、次の記述子の<instrumentation>要素の子である<wldf-instrumentation-monitor>要素で定義されます。

  • サーバー・スコープ・インストゥルメンテーションの場合はDIAG_MODULE.xml記述子

  • アプリケーション・スコープ・インストゥルメンテーションの場合はMETA-INF/weblogic-diagnostics.xml記述子

次のフラグメントは、アプリケーションの委任モニターおよびカスタム・モニターの構成を示しています。(サーバー・スコープのインストゥルメンテーションの場合は、アプリケーション・スコープのモニターをサーバー・スコープのモニターに置き換えれば、このフラグメントを変更できます)。

<instrumentation>
   <enabled>true</enabled>
      <wldf-instrumentation-monitor>
       <name>Servlet_Before_Service</name>
       <enabled>true</enabled>
       <dye-mask>USER1</dye-mask>
       <dye-filtering-enabled>true</dye-filtering-enabled> 
       <action>TraceAction</action>
     </wldf-instrumentation-monitor>
     <wldf-instrumentation-monitor>
       <name>MyCustomMonitor</name>
       <enabled>true</enabled>
       <action>TraceAction</action>
       <location-type>before</location-type>
          <pointcut>call( * com.foo.bar.* get*(...));</pointcut>
     </wldf-instrumentation-monitor>
</instrumentation>

ここでは、Servlet_Before_Serviceモニターが仕分けマスクを設定しており、仕分けフィルタが有効になっています。これは、インストゥルメンテーションがサーバー・レベルで有効になっていて、DyeInjectionモニターが有効化されて適切に構成されている場合にのみ役に立ちます。DyeInjectionモニターの構成は、第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。

表11-3は、<wldf-instrumentation-monitor>要素について説明します。

表11-3 DIAG_MODULE.xmlまたはweblogic-diagnostics.xmlファイル内の<wldf-instrumentation-monitor> XML要素

要素 説明

<wldf-instrumentation-monitor>

診断モニターの構成を開始する要素。

<enabled>

trueの場合、モニターは有効です。falseの場合、モニターは無効です。各モニターを個別に有効または無効にできます。デフォルト値はtrueです。

<name>

モニターの名前。標準モニターと代理モニターの場合は、付録B「WLDFインストゥルメンテーション・ライブラリ」であらかじめ定義されているモニターの名前を使用します。カスタム・モニターの場合は、モニターを識別する任意の文字列です。カスタム・モニターの名前は一意でなければなりません。つまり、ライブラリ内の他のモニターと名前が重複することはできません。

<description>

モニターを説明する要素(オプション)。

<action>

委任モニターとカスタム・モニターに適用される要素(オプション)。少なくともアクションを1つは指定しないと、モニターは情報を生成しません。複数の<action>要素を指定できます。アクションは、モニターのタイプに対応している必要があります。委任モニターとカスタム・モニター用にあらかじめ定義されているアクションのリストは、付録B「WLDFインストゥルメンテーション・ライブラリ」を参照してください。

<dye-filtering-enabled>

省略可能な要素。trueの場合、そのモニターで仕分けフィルタが有効になります。falseの場合、仕分けフィルタは無効です。デフォルト値はfalseです。

仕分けフィルタを使用するには、DyeInjectionモニターをサーバー・レベルで適切に構成する必要があります。

<dye-mask>

省略可能な要素。仕分けフィルタが有効になっている場合、仕分けマスクは、診断コンテキスト内の値と比較して、アクションを起こすかどうかを決定します。仕分けおよび仕分けフィルタの詳細は、第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。

<properties>

省略可能な要素。仕分けフラグ用にname=valueのペアを設定します。

現在はDyeInjectionモニターにのみ適用されます。

<location-type>

before、after、aroundのいずれかの値を持つ要素(オプション)。この要素によって、ポイントカットを基準にアクションがトリガーされるタイミング(ポイントカットの前でトリガーされるか、ポイントカットの後でトリガーされるか、ポイントカットの前後でトリガーされるか)が決まります。

カスタム・モニターの場合にのみ有効。標準モニターおよび代理モニターでは、この値はあらかじめ定義されています。カスタム・モニターでは、診断ロケーションの種類とポイントカットを定義する必要があります。

<pointcut>

省略可能な要素。ポイントカット要素には、診断コードが挿入されるジョインポイントを定義する式が格納されます。

カスタム・モニターの場合にのみ有効です。標準モニターおよび委任モニターでは、この値はあらかじめ定義されています。カスタム・モニターでは、診断ロケーションの種類とポイントカットを定義する必要があります。

ポイントカットの構文については、「カスタム・モニターのポイントカットの定義」を参照してください。

<include>

インストゥルメントされたコードを挿入できるクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<include>要素を指定できます。指定した場合、インストゥルメンテーションの対象となるには、クラスは<include>パターンに一致する必要があります。

アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>または<exclude>パターンを指定すると、親<wldf-instrumentation-monitor>要素で定義されるモニターにのみ適用されます。

注意:インストゥルメントされたアプリケーション・スコープ全体に対して<include>パターンおよび<exclude>パターンを指定することもできます。表11-1の<include>および<exclude>の項目を参照してください。

クラスがロードされると、インストゥルメンテーション・コードを挿入する前に、include/excludeのパターン・チェックに成功する必要があります。クラスがinclude/excludeのパターン・チェックに成功した場合でも、インストゥルメントされるかどうかは、構成記述子で定義されている診断モニターによって決まります。ライブラリ内にあるアプリケーション・スコープの委任モニターには、あらかじめ定義されている独自のクラスおよびポイントカットがあります。カスタム・モニターでは、独自のポイントカット式を指定します。そのため、include/excludeのパターン・チェックに成功しても、クラスはインストゥルメントされない場合があります。

注意:インストゥルメンテーションは、クラスのロード時にアプリケーションに挿入されます。サイズの大きなアプリケーションを頻繁にロードする環境では、<include>または<exclude>要素をうまく使えば、利便性の向上を期待できます。小さなアプリケーションや、中規模または大規模のアプリケーションでも頻繁にロードしない場合は、この要素を無視してもかまいません。

<exclude>

インストゥルメントされたコードを挿入できないクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<exclude>要素を指定できます。指定した場合、<exclude>パターンに一致するクラスはインストゥルメントされません。

アプリケーション・スコープのインストゥルメンテーションの診断モニターにのみ有効です。上記の<include>の説明を参照してください。

<dye-filtering-enabled>と<dye-mask>の各要素については、さらに次の情報があります。

  • DyeInjectionモニターが有効になっており、サーバーまたはクラスタ用に構成されている場合、下流にある委任モニターおよびカスタム・モニターに対して仕分けフィルタを使用し、リクエストの診断コンテキストに対してそのDyeInjectionモニターが実行した仕分けを検査できます。

  • DyeInjectionモニターの構成によって、診断コンテキストに関連付けられた64ビット仕分けベクトルでどのビットが設定されるかが決まります。<dye-filtering-enabled>属性がモニターに対して有効になっていても、リクエストの診断コンテキストの仕分けベクトルが、モニターで構成された仕分けマスクと一致していない場合、診断アクティビティは実行されません。仕分けベクトルが仕分けマスクと一致している場合(ビット単位のANDの場合)、アプリケーションは診断アクションを実行できます。

    (dye_vector & dye_mask == dye_mask)

このうようにして、仕分けフィルタのメカニズムを使用すると、モニターは特定のリクエストに対してのみ診断アクションを実行でき、それによって他のリクエストの処理が遅くなることはありません。診断コンテキストおよび仕分けベクトルの詳細は、第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。

モニター・タイプへの<wldf-instrumentation-monitor>XML要素のマッピング

表11-4に、各モニター・タイプに適用する<wldf-instrumentation-monitor>要素を示します。Xの場合、要素は対応するモニターに適用され、N/Aの場合は適用されません。

表11-4 モニター・タイプへのインストゥルメンテーションXML要素のマッピング

要素 標準 委任 カスタム

<wldf-instrumentation-monitor>

X

X

X

<name>

X

X

X

<description>

X

X

X

<enabled>

X

X

X

<action>

N/A

X

X

<dye-filtering-enabled>

N/A

X

X

<dye-mask>

N/A

X

X

<properties>

X脚注 1 

N/A

N/A

<location-type>

N/A

N/A

X

<pointcut>

N/A

N/A

X

脚注 1 現在は、DyeInjectionモニターで、仕分けフラグにname=valueペアを設定する場合にのみ使用されます。

サーバー・スコープのインストゥルメンテーションの構成

サーバー・レベルでインストゥルメンテーションを有効にし、サーバー・スコープのモニターを構成するには、以下の手順を実行します。

  1. 作成するWLDFシステム・リソースの数を決定します。

    ドメイン内に複数のDIAG_MODULE.xml診断記述子ファイルを持つことができます。ただし、ドメイン内のサーバーまたはクラスタごとにデプロイできるのは、常に1つの診断記述子ファイルのみになります。複数のファイルを作成する理由は、柔軟性です。たとえば、DOMAIN_NAME/config/diagnosticsディレクトリに5つの診断記述子ファイルを保存できます。ファイルごとに異なるインストゥルメンテーション(に加え、おそらくハーベスタおよび監視および通知)の構成を格納できます。アクティブにする特定のモニターに対応する記述子ファイルをデプロイします。

  2. どのサーバー・スコープ・モニターを構成に含めるかを決めます。

    • サーバーまたはそのサーバーにデプロイされているものに対して仕分けフィルタを使用する場合は、DyeInjectionモニターを構成します。

    • 1つまたは複数のサーバー・スコープ委任モニターを使用する場合は、どのモニターを使用し、各モニターにどのアクションを関連付けるかを決めます。

  3. 構成ファイル(複数可)を作成して構成します。

    • 管理コンソールを使用して委任モニター用のDIAG_MODULE.xmlファイルを作成する場合(推奨手順)、コンソールには、そのモニターに対応するアクションのみが表示されます。エディタまたはWebLogic Scripting Tool (WLST)で構成ファイルを作成する場合は、アクションとモニターを正しく関連付ける必要があります。

    • 詳細は、『Oracle WebLogic Serverドメイン構成の理解』のドメイン構成ファイルに関する項を参照してください。

  4. デプロイメント記述子ファイルを検証してデプロイします。サーバー・スコープのインストゥルメンテーションの場合は、サーバーの実行中にモニターを追加および削除したり、モニターを有効または無効にしたりできます。

例11-1に、サーバー・スコープ・インストゥルメンテーションの構成ファイルのサンプルを示します。このサンプルでは、インストゥルメンテーションを有効にし、DyeInjection標準モニターおよびConnector_Before_Work委任モニターを構成します。1つの<instrumentation>要素に、モジュールのすべてのインストゥルメンテーションの構成が格納されます。各診断モニターは、個別の<wldf-instrumentation-monitor>要素で定義されます。

例11-1 サーバー・スコープのインストゥルメンテーションのサンプル(DIAG_MODULE.xml内)

<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd">
  <instrumentation>
    <enabled>true</enabled>
    <wldf-instrumentation-monitor>
      <name>DyeInjection</name>
      <description>Inject USER1 and ADDR1 dyes</description>
      <enabled>true</enabled>
      <properties>USER1=weblogic
       ADDR1=127.0.0.1</properties>
    </wldf-instrumentation-monitor>
    <wldf-instrumentation-monitor>
      <name>Connector_Before_Work</name>
      <enabled>true</enabled>
      <action>TraceAction</action>
      <dye-filtering-enabled>true</dye-filtering-enabled>
      <dye-mask>USER1</dye-mask>
    </wldf-instrumentation-monitor>
  </instrumentation>
</wldf-resource>

アプリケーション・スコープのインストゥルメンテーションの構成

アプリケーション・レベルでは、WLDFのインストゥルメンテーションは、デプロイ可能なモジュールとして構成されます。このモジュールは、アプリケーションの一部としてデプロイされます。

次の項では、アプリケーション・スコープのインストゥルメンテーションの構成で必要な情報について説明します。

システム・スコープのインストゥルメンテーションとアプリケーション・スコープのインストゥルメンテーションの比較

アプリケーションのインストゥルメントは、システム・レベルでのインストゥルメントと似ていますが、以下の点が違います。

  • アプリケーションでは、標準モニター、委任モニター、およびカスタム・モニターが使用できます。

    • サーバー・スコープの標準モニターはDyeInjectionのみです。アプリケーション・スコープの標準モニターはHttpSessionDebugのみです。詳細は、「診断モニター・ライブラリ」のHttpSessionDebugの項目を参照してください。

    • 委任モニターは、サーバー・スコープかアプリケーション・スコープのどちらかです。アプリケーションは、アプリケーション・スコープの委任モニターを使用する必要があります。

    • カスタム・モニターはすべてアプリケーション・スコープです。

  • サーバーのインストゥルメンテーション設定は、アプリケーションに影響します。インストゥルメンテーションをアプリケーションに対して有効にするには、アプリケーションがデプロイされるサーバーでインストゥルメンテーションを有効にする必要があります。デプロイメント時にサーバーのインストゥルメンテーションが有効である場合、アプリケーションでインストゥルメンテーションを利用できます。デプロイメント時にサーバーでインストゥルメンテーションが有効になっていない場合、アプリケーションでインストゥルメンテーションを有効にしても無視されます。

  • アプリケーションのインストゥルメンテーションが、weblogic-diagnostics.xml記述子で構成する必要があります。ユーザーはMETA-INF/weblogic-diagnostics.xmlファイルを作成し、インストゥルメンテーションを構成して、アプリケーションのアーカイブにファイルを格納します。アーカイブがデプロイされると、インストゥルメンテーションは、アプリケーションがロードされたときに自動的に挿入されます。

  • 「デプロイメント・プラン」を使用すると、アプリケーションを再デプロイしなくても、構成要素を動的に更新できます。「インストゥルメンテーション構成を動的に制御するためのデプロイメント・プランの使用」を参照してください。

アプリケーション・スコープ・インストゥルメンテーションのXML記述子は、サーバー・スコープ・インストゥルメンテーションの場合と同じ方法で定義されます。WLDFインストゥルメンテーション・ライブラリで使用可能な委任モニターと診断アクションを使用すると、アプリケーション専用のインストゥルメンテーションを構成できます。また、ユーザー独自のカスタム・モニターも作成できますが、カスタム・モニターにアタッチする診断アクションは、WLDFインストゥルメンテーション・ライブラリから指定する必要があります。

表11-5では、システム・モジュールとアプリケーション・モジュールの機能とスコープを比較します。

表11-5 システム・モジュールとアプリケーション・モジュールの比較

モジュールの種類 オブジェクトの動的な追加または削除 コンソールでのオブジェクトの追加または削除 JMXでのリモート変更 JSR-88での変更(非リモート) コンソールでの変更 仕分けフィルタと仕分けマスクの動的な有効化または無効化

システム・モジュール

はい

はい

はい

いいえ

はい

(JMXから)

はい

アプリケーション・モジュール

可(ホットスワップが有効な場合)

不可(ホットスワップが有効でない場合: モジュールを再デプロイする必要があります)

はい

いいえ

はい

はい

(プランから)

はい

アプリケーションのインストゥルメントに必要な手順の概要


注意:

WLS10.3では、前のWLSリリースにおけるケースのように、アプリケーションのMETA-INFディレクトリのweblogic-diagnostics.xmlファイルを作成する必要はありません。ただし、この方法でアプリケーションの診断モニターを最初に構成することもできます。

アプリケーションの診断モニターを実装するには、以下の手順を実行します。

  1. サーバーでインストゥルメンテーションが有効になっていることを確認します。「サーバー・スコープのインストゥルメンテーションの構成」を参照してください。

  2. 適切な形式のMETA-INF/weblogic-diagnostics.xml記述子ファイルをアプリケーション用に作成します。アプリケーションがデプロイされるたびに自動的に有効化されるモニターを追加する場合、以下のようにします。

    • <instrumentation>要素を有効(<enabled>true</enabled>)にします。

    • 対応可能なアクションがアタッチされた診断モニターを少なくとも1つ追加して有効にします(モニターが有効になっており、イベントを生成するアクションがそのモニターにアタッチされている場合にのみ、モニターは診断イベントを生成します)。

    各モニターのタイプ用に整形された記述子ファイルのサンプルについては、「委任モニターの記述子ファイルの作成」および「カスタム・モニターの記述子ファイルの作成」を参照してください。

    ポイントカット式の作成については、「カスタム・モニターのポイントカットの定義」を参照してください。

  3. アプリケーション・アーカイブに記述子ファイルを格納します。

  4. アプリケーションをデプロイします。第14章「WLDFアプリケーション・モジュールのデプロイメント」を参照してください。

以下の点に注意します。

  • weblogic-diagnostics.xmlで定義された診断モニターは、管理コンソールの「デプロイメント」>「<サーバー名>」>「構成」>「インストゥルメンテーション」ページに表示されます。

  • アプリケーション・アーカイブのMETA-INF/weblogic-diagnostics.xml記述子がモニターを定義する場合、管理コンソールを使用することでそれを取り除くことができません。ただし、無効化や有効化は管理コンソールでも可能です。

  • 管理コンソールから別のモニターを追加できます。管理コンソールから追加したすべてのモニターは、weblogic-diagnostics.xmlには保持されず、アプリケーションのデプロイメント計画に保存されます。この方法で追加したモニターは、管理コンソールで削除できます。

委任モニターの記述子ファイルの作成

次に、アプリケーション・スコープの代理モニター用に整形されたMETA-INF/weblogic-diagnostics.xml記述子ファイルの例を示します。このファイルには少なくとも太字で示す行を含める必要があります。この例では、モニターが1つのみ定義されています(Servlet_Before_Service)。ただし、記述子ファイルに複数のモニターを定義できます。

<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd"> 
   <instrumentation>
      <enabled>true</enabled>
      <wldf-instrumentation-monitor>
         <name>Servlet_Before_Service</name>
         <enabled>true</enabled>
         <dye-mask>USER1</dye-mask>
         <dye-filtering-enabled>true</dye-filtering-enabled> 
         <action>TraceAction</action>
      </wldf-instrumentation-monitor>
   </instrumentation>
</wldf-resource>

Servlet_Before_Serviceモニターは、WLDFモニター・ライブラリから選択したアプリケーション・スコープのモニターです。複数のサーブレット・メソッドまたはJSPメソッドの入口にジョインポイントを設定するポイントカットを使用してハード・コード化されています。アプリケーションは仕分けフィルタを有効にし、仕分けマスクにUSER1フラグを設定しているので、TraceActionアクションは、アプリケーションに渡される診断コンテキスト内の仕分けベクトルにUSER1フラグ・セットがある場合にのみ呼び出されます。

仕分けベクトルは、DyeInjectionモニター構成に従って、リクエストがサーバーに入る時点で、DyeInjectionモニターを介してシステム・レベルで設定されます。たとえば、DyeInjectionモニターがUSER1=weblogicプロパティで構成され、リクエストがユーザーweblogicによって溯源された場合、仕分けベクトルにおけるUSER1仕分けフラグが設定されます。

したがって、このアプリケーションのServlet_Before_Serviceモニターは、仕分けベクトルを検査し、USER1フラグ・セットを見つけるまで、基本的に何も行いません。このフィルタ処理を実行すれば、生成される診断データの量を減らし、その時点で管理者にとって意味のあるデータのみを生成することができます。

カスタム・モニターの記述子ファイルの作成

次に、カスタム・モニターの整形式META-INF/weblogic-diagnostics.xmlファイルの例を示します。このファイルには少なくとも太字で示す行を含める必要があります。

例11-2 カスタム・モニターの構成のサンプル(DIAG_MODULE.xml内)

<?xml version="1.0" encoding="UTF-8"?>
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd"> 
 <instrumentation>
      <enabled>true</enabled>
      <wldf-instrumentation-monitor>
         <name>MyCustomMonitor</name>
         <enabled>true</enabled>
         <action>TraceAction</action>
         <location-type>before</location-type>
         <pointcut>call( * com.foo.bar.* get* (...));</pointcut>
      </wldf-instrumentation-monitor>
   </instrumentation>
</wldf-resource>

カスタム・モニターの場合、<name>は、開発者が指定した任意の文字列です。このモニターはカスタムなので、アクションの呼出し用にあらかじめ定義された診断ロケーションはありません。記述子ファイルでは、診断ロケーションの種類とポイントカット式を定義する必要があります。この例では、TraceActionアクションは、ポイントカット式で定義されたメソッドが呼び出される前(</location-type>の前の<location-type>)に呼び出されます。表11-1は、例11-2からポイントカット式が解析される仕組みを示します。(ワイルドカードの使用に注意してください。)

表11-6 ポイントカット式のサンプルの説明

ポイントカット式 説明

call( * com.foo.bar.* get* (...))

call( ):ジョインポイントがこのポイントカット式の残りで定義されているメソッドが呼び出されたときに、定義されたアクションをトリガーします。

call( * com.foo.bar.* get* (...))

*:戻り値。ワイルドカードは、メソッドの戻り値の型を問わないことを示します。

call( * com.foo.bar.* get* (...))

com.foo.bar.*: com.foo.barクラスとそのサブパッケージのメソッドが当てはまります。

call( * com.foo.bar.* get* (...))

get* : getという文字列で始まる任意のメソッドが当てはまります。

call( * com.foo.bar.* get* (...))

(...) :省略符号は、メソッドで指定できる引数の数に制限がないことを示します。

このポイントカット式は、パッケージcom.foo.barとそのサブパッケージ内にあるすべてのクラスのget*()メソッドに一致します。メソッドは、voidを含む任意の型の値を返すことができます。また、任意の型の引数を、数に制限なく持つことができます。インストゥルメンテーション・コードは、これらのメソッドの前に挿入され、そのメソッドが呼び出される直前に、TraceActionアクションが呼び出されます。

ポイントカットの定義に使用する文法の詳細は、「カスタム・モニターのポイントカットの定義」を参照してください。

カスタム・モニターのポイントカットの定義

カスタム・モニターでは、診断アクションの呼出し場所を指定するポイントカット式をユーザーが作成するので、委任モニターよりも柔軟な操作が可能です。委任モニターの場合は、アクション・ライブラリからアクションを選択する必要があります。

ジョインポイントは、精密に定義された、プログラム内の固有の位置です。ポイントカットは、ジョインポイントのセットを指定する式です。この項では、以下のポイントカット構文を使用して、ポイントカットの式を定義する方法について説明します。

カスタム・モニターでは2種類のポイントカットを指定できます。

  • call :メソッドが呼び出されると、アクションを実行します。

  • execution :メソッドが実行されると、アクションを実行します。

ポイントカット式を定義する構文は次のとおりです。

pointcutExpr  :=  orExpr  ( 'OR' orExpr ) *
orExpr := andExpr ( 'AND' andExpr ) *
andExpr := 'NOT' ? termExpr
termExpr := exec_pointcut | call_pointcut | '(' pointcutExpr ')'
exec_pointcut := 'execution' '(' modifiers? 
                                 returnSpec 
                                 classSpecWithAnnotations
                                 methodSpec '(' parameterList ')'
                              ')'
call_pointcut := 'call' '(' returnSpec
                            classSpec
                            methodSpec '(' parameterList ')'
                         ')'
modifiers := modifier ( 'OR' modifier ) * modifier := 'public' | 'protected' | 'private' | 'static'
returnSpec :=  '*' | typeSpec
classSpecWithAnnotations := '@' IDENTIFIER ( 'OR' IDENTIFIER ) * | classSpec
classSpec := '+' ? classOrMethodPattern | '*'
typeSpec :=  '%' ? ( primitiveType | classSpec ) ( '[]' )*
methodSpec :=  classOrMethodPattern
parameterList := param ( ',' param ) *
param := typeSpec | '...'
primitiveType := 'byte' | 'char' | 'boolean' | 'short' | 'int' | 'float' | 'long' | 'double' | 'void'
classOrMethodPattern :=  '*' ? IDENTIFIER '*'? | '*'

以下のルールが適用されます。

  • ワイルドカード文字(*)を、クラスの型やメソッド名に使用できます。

  • 引数リストの省略符号(...)は、その引数以外に任意の型の引数がいくつか(数は可変)あることを示します。

  • %(パーセント記号)接頭辞は、静的でないクラスのインスタンス化、パラメータまたは戻り値を指定する値が、機密情報を含まないまたは公開しないことを指定します。この演算子は、メソッド引数または戻り値を取得するDisplayArgumentsActionアクションで特に有効です。この接頭辞が明示的に使用されていない場合は、戻される値にアスタリスクが代入されます。この動作によって、インストゥルメンテーション・イベントがジョインポイントの入力引数を取得する場合またはジョインポイントから値を戻す場合に、アプリケーション内の機密データが誤って送信されないことをことを保証します。


    注意:

    %演算子は、ポイントカット式内の省略記号またはワイルドカードには適用できません。

  • クラスの型に付けられた+ (プラス記号)接頭辞は、指定したクラス/インタフェース・パターンを実装しているすべてのサブクラス、サブインタフェース、または具象クラスを示します。

  • ポイントカット式は、適合するジョインポイントを識別するパターンを指定します。パターンに対してジョインポイントを適合させると、有効な適合かどうかを示すブール型の値が返されます。

  • ポイントカット式は、AND、OR、またはNOTブール演算子と組み合わせて、複雑なポイントカット式ツリーを構築できます。

たとえば、次のポイントカットは、パッケージcom.foo.barとそのサブパッケージ内のすべてのクラスのすべてのパブリックなinitializeメソッドのメソッド実行に一致します。initializeメソッドは、voidを含む任意の型の値を返すことができます。また、任意の型の引数を、数に制限なく持つことができます。

  execution(public * com.foo.bar.* initialize(...))

次のポイントカットは、com.foo.bar.MyInterfaceインタフェース(または、クラスの場合はサブクラス)を直接または間接的に実装するすべてのクラスのメソッド・コール(コール・サイト)に一致します。メソッド名はgetで始まり、int値を戻すパブリック・メソッドである必要があります。また、メソッドは、java.lang.String型の引数1つを受け取る必要があります。

call(int +com.foo.bar.MyInterface get*(java.lang.String))

次の例では、ブール演算子を使用してポイントカット式ツリーを構築する方法を示します。

  call(void com.foo.bar.* set*(java.lang.String)) OR
  call( * com.foo.bar.* get*())

次の例では、前の式ツリーが、構成ファイルでどのように<pointcut>要素として変換されるかを示します。

  <pointcut>call(void com.foo.bar.* set*(java.lang.String)) OR
  call( * com.foo.bar.* get*())</pointcut>

アノテーション・ベースのポイントカット

実行ポイントのクラス指定子やメソッド指定子でJDKスタイルのアノテーションを使用することができます。アスタリスク(@)で始まるクラス指定子またはメソッド指定子はアノテーション名として解釈されます。

クラス指定子として使用したアノテーションは、@が付けられたすべてのクラスに一致します。照合の実行中には、アノテーション名のみが考慮されます。アノテーション属性は無視されます。

例:

  execution(public void @Service @Invocation (...)

前述のポイントカットは次のメソッドと一致します。

  • パブリック・メソッド

  • voidを戻すメソッド

  • @Serviceのアノテーションが付けられたクラスに含まれるメソッド

  • @Invocationのアノテーションが付けられたメソッドを持つメソッド

  • 任意の数の引数を持つメソッド


    注意:

    アノテーション・ベースの指定子は、実行ポイントカットでのみ使用できます。呼出しポポイントカットでは使用できません。

アノテーション・ベースのクラス指定子およびメソッド指定子では、次のワイルドカードを使用できます。

  • * :あらゆるものに一致します。

  • 先頭の* :指定した文字列で終わるクラス/インタフェースまたはメソッドの名前に一致します。たとえば、「*Bean」は、weblogic.management.configuration.ServerMBeanに一致します。

  • 最後の* :指定した文字列で始まるクラス/インタフェースまたはメソッドの名前に一致します。たとえば、「weblogic.*」は、weblogicおよびそのサブパッケージ内のすべてのクラスおよびインタフェースに一致します。

  • ポイントカットは、内部クラスの名前に基づいて指定できます。例:

       public class Foo {
      class Bar {
         public int getValue() {...}
      }
   }

    内部クラスBarのgetValueメソッドをカバーするポイントカットは、次の指定で定義できます。

   execution (public int Foo$Bar getValue(...));



ワイルドカードを使うこともできます。例:


   execution ( * Foo$Bar get*(...));



前述のポイントカットは、クラスFooの内部クラスBarのgetterメソッドとのみ一致します。


次のように先頭と末尾にワイルドカードを使用することもできます。例:


   execution ( * Foo$Ba* get*(...));
   execution ( * *oo$Bar get*(...));
   execution ( * *oo$Ba* get*(...));



前述のポイントカットは、クラスFoo$Barのgetterメソッドとも一致します。












リクエスト・パフォーマンス・データの作成


サーバー・スコープまたはアプリケーション・スコープのインストゥルメントを構成している場合、リクエスト・パフォーマンス・データをWebLogic Server管理コンソールに表示できます。「リクエスト・パフォーマンス」ページには、Weblogic診断フレームワーク・インストゥルメンテーション機能で取得するメソッド・パフォーマンスのリアルタイムと履歴ビューの情報が表示されます。


リクエスト・パフォーマンス・データを作成するには、次の基準が満たされる必要があります。



Weblogic Server管理コンソールでのリクエスト・パフォーマンス・データの作成と分析の詳細は、Oracle WebLogic Server管理コンソール・ヘルプのリクエスト・パフォーマンスの分析に関する項を参照してください。


























 
前
 前 		
次
 次		











 
ドキュメント・ライブラリへ移動
 ライブラリ		
製品リストヘ移動
 製品		
目次へ移動
 目次