診断モニター。診断モニターは、サーバーまたはアプリケーション・コードの特定の場所に挿入され、動的に管理できるひとまとまりの診断コードです。モニターは、スコープ(システム、アプリケーション)および種類(標準、委任、カスタム)を基に定義します。
診断アクション。診断アクションは、プログラムの実行中にトリガーされたモニターが行うアクションです。
診断コンテキスト。診断コンテキストは、送信元のIPアドレスやユーザーIDなど、特定のリクエスト・プロパティの存在を示すフラグや固有のリクエスト識別子などのコンテキスト情報です。診断コンテキストでは、プログラムの実行を追跡したり、モニターが診断アクションをトリガーするタイミングを制御したりすることができます。診断コンテキストを管理するためのDyeInjection監視の構成を参照してください。
WLDFには、あらかじめ定義された診断モニターと診断アクションのライブラリが用意されています。また、アプリケーション・スコープのカスタム・モニターを作成し、診断コードが挿入されるアプリケーション内の位置をユーザーが決めることもできます。
この章の内容は次のとおりです。
この項では、インストゥルメンテーションの概念と用語について説明します。この項の内容は、次のとおりです。
実行可能なインストゥルメンテーション・サービスには、システム・レベル(サーバーおよびクラスタ)のものとアプリケーション・レベルのものがあります。概念、サービス、構成オプション、および実装機能の多くは両者とも同じです。ただし、相違点もいくつかあります。それらについては、このドキュメントで説明しています。サーバー・スコープ・インストゥルメンテーションは、WebLogic Serverインスタンスおよびクラスタ固有のインストゥルメンテーションの構成と機能を指します。これに対して、アプリケーション・スコープ・インストゥルメンテーションは、WebLogic Serverインスタンスにデプロイされているアプリケーション固有の構成と機能を指します。スコープは各診断モニターに組み込まれており、ユーザーがモニターのスコープを変更することはできません。
サーバーまたはクラスタ向けのサーバー・スコープ・インストゥルメンテーションは、診断モジュールの一部として、DOMAIN_HOME
/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モニターのみです。このモニターはサーバー・スコープ・モニターであり、サーバー・レベルで診断コンテキストを作成して仕分けの注入を構成するために使用します。詳細は、「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。
標準のアプリケーション・スコープ・モニターはHttpSessionDebugのみです。このモニターは、HTTP Sessionオブジェクトを検査するために使用します。
委任モニターでは、スコープ、ポイントカットおよびロケーションがハード・コード化されていますが、モニターで実行するアクションは、ユーザーが選択します。つまり、このモニターでは、あらかじめ定義されているアクションにかわって、ユーザーが選択したアクションが実行されます。委任モニターは、サーバー・スコープかアプリケーション・スコープのどちらかです。
委任モニターは、それ自体では完成していません。委任モニターが意味のある処理を行うには、少なくとも1つのアクションをモニターに割り当てる必要があります。
すべてのアクションがどのモニターにも割当て可能なわけではありません。WebLogic Server管理コンソールで委任モニターを構成する場合、選択したモニターで対応可能なアクションのみを指定できます。WLSTを使用するか記述子ファイルを手動で編集して委任モニターを構成する場合、アクションはそのモニターに対応する必要があります。WLDFは、委任モニターのXML構成ファイルがデプロイ時にロードされるときにその委任モニターを検証します。
WLDFインストゥルメンテーション・ライブラリで利用可能な委任モニターとアクションについては「WLDFインストゥルメンテーション・ライブラリ」を参照してください。
カスタム・モニターは、次の特徴を持つ特殊な委任モニターです。
アプリケーション・スコープ・インストゥルメンテーションにのみ利用できます。
あらかじめ定義されたポイントカットやロケーションがありません。
カスタム・モニターを構成するには、カスタム・モニターに名前を付け、モニターで使用するポイントカットと診断ロケーションを定義し、あらかじめ定義されている診断アクションのセットからアクションを割り当てます。<pointcut>要素と<location type>要素はカスタム・モニターでは必須です。
表12-1に、各種類のモニターの違いを簡単に示します。
表12-1 診断モニターのタイプ
モニター・タイプ | スコープ | ポイントカット | ロケーション | アクション |
---|---|---|---|---|
標準モニター |
サーバー |
固定 |
固定 |
固定 |
委任モニター |
サーバーまたはアプリケーション |
固定 |
固定 |
構成可能 |
カスタム・モニター |
アプリケーション |
構成可能 |
構成可能 |
構成可能 |
モニターに対して「仕分けマスク」を設定すると、診断アクションがトリガーされるタイミングを制限できます。このマスクによって、診断コンテキストのどの仕分けフラグがアクションをトリガーするかが決まります。モニターの仕分けマスクの設定については、「<wldf-instrumentation-monitor> XML要素」を参照してください。
注意:
診断コンテキスト、仕分けの注入、および仕分けフィルタについては、「診断コンテキストを管理するためのDyeInjectionモニターの構成」で説明します。
診断アクションは、関連する委任モニターまたはカスタム・モニターに対応する診断コードを実行します(標準モニターの場合、アクションはあらかじめ定義されています)。委任モニターまたはカスタム・モニターがなんらかの意味のある処理を行うには、モニターに対して少なくとも1つのアクションを構成する必要があります。
WLDF診断ライブラリでは、次のアクションを利用できます。アクションをモニターにアタッチするには、DIAG_MODULE
.xml
構成ファイルの<action>要素でアクション名を指定します。
DisplayArgumentsAction
MethodInvocationStatisticsAction
MemoryAllocationStatisticsAction
StackDumpAction
ThreadDumpAction
TraceAction
TraceElapsedTimeAction
TraceMemoryAllocationAction
アクションは、モニターに正しく対応している必要があります。たとえば、TraceElapsedTimeアクションは、診断ロケーションの種類がAroundのカスタム・モニター、または委任モニターで使用できます。詳細は、「WLDFインストゥルメンテーション・ライブラリ」を参照してください。
インストゥルメンテーションは、診断記述子の一部としてXML構成ファイルで構成されます。このファイルの名前と格納場所は、システム・レベル(サーバー・スコープ)のインストゥルメンテーションを実装しているか、アプリケーション・レベル(アプリケーション・スコープ)のインストゥルメンテーションを実装しているかによって異なります。
システム・レベルのインストゥルメンテーション構成は、次のディレクトリの1つ以上の診断記述子に格納されます。
DOMAIN_HOME/config/diagnostics
このディレクトリには、複数のシステム・レベルの診断記述子ファイルを格納できます。ファイル名は任意ですが、myDiag.xml
のように.xml
で終わる必要があります。各ファイルには、次のうち、1つまたは複数のデプロイ可能な診断コンポーネントの構成情報を格納できます。
ハーベスタ
インストゥルメンテーション
監視および通知
1つ以上の診断モニターの構成は、記述子ファイルの <instrumentation>セクションに定義できます。サーバー・スコープのインストゥルメンテーションは、サーバーを再起動しなくても有効化および無効化でき、再構成も可能です。
サーバー(またはクラスタ)では、いつでも1つのWLDFシステム・リソース(つまり、1つのシステム・レベルの診断記述子ファイル)のみをアクティブにできます。アクティブな記述子は、次の構成ファイルからリンクおよびターゲット指定されます。
DOMAIN_HOME/config/config.xml
診断システム・モジュールの構成の詳細は、診断システム・モジュールの構成を参照してください。WebLogic Serverの構成ファイルの作成、コンテンツおよび解析の一般情報については、『Oracle WebLogic Serverドメイン構成の理解』を参照してください。
アプリケーション・レベルのインストゥルメンテーション構成は、以下の場所にあるアプリケーションのアーカイブ内にパッケージ化されます。
META-INF/weblogic-diagnostics.xml
アプリケーションにデプロイ可能な診断コンポーネントはインストゥルメンテーションだけです。したがって、この記述子には、インストゥルメンテーションの構成情報のみを格納できます。
注意:
インストゥルメンテーションをアプリケーションで使用できるようにするには、アプリケーションがデプロイされるサーバーでインストゥルメンテーションを有効にする必要があります。(サーバー・スコープ・インストゥルメンテーションは、サーバーの診断記述子の<instrumentation>要素で有効にしたり無効にしたりできます)。
アプリケーションを再デプロイせずに診断モニターを有効にしたり無効にしたりできます。ただし、ポイントカットの定義やモニターの追加または削除など、他のインストゥルメンテーション機能を変更した後には、アプリケーションを再デプロイする必要があります。再デプロイする必要があるかどうかは、インストゥルメンテーションの構成方法とアプリケーションのデプロイ方法によって異なります。3つのオプションがあります。
JSR-88デプロイメント・プランを使用しないで、アプリケーションのインストゥルメンテーション構成を直接定義および変更します。
インストゥルメンテーション設定のプレースホルダーを含むデプロイメント・プランを使用して、アプリケーションを構成およびデプロイします。
サーバーの起動時にホットスワップ機能を有効にし、インストゥルメンテーション設定のプレースホルダーを含むデプロイメント・プランを使用してデプロイします。
これらの選択肢の詳細は、「インストゥルメンテーション構成を動的に制御するためのデプロイメント・プランの使用」を参照してください。
診断アプリケーション・モジュールのデプロイと変更の詳細は、「WLDFアプリケーション・モジュールのデプロイメント」を参照してください。
診断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リソースの構成の概要は、「WLDFの構成の理解」を参照してください。
この項では、記述子のコード・フラグメント、インストゥルメンテーションの構成に使用するXML要素をまとめた表、および診断モニターについて簡単に説明した表を示します。
「<Instrumentation> XML要素」,では、<instrumentation>要素内で使用する最上位の各要素について説明します。
「<wldf-instrumentation-monitor> XML要素」,では、<wldf-instrumentation-monitor>要素内で使用する各要素について説明します。
「各モニター・タイプへの<wldf-instrumentation-monitor>のXML要素のマッピング」,では、どのインストゥルメンテーション要素をどのモニターに適用するかについて説明します。
表12-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> <!-- <wldf-instrumentation-monitor> elements to define diagnostic monitors for this diagnostic module --> </instrumentation> <!-- Other elements to configure this diagnostic module --> </wldf-resource>
表12-2 DIAG_MODULE.xml構成ファイル内の<instrumentation> XML要素
要素 | 説明 |
---|---|
<instrumentation> |
インストゥルメンテーション構成を開始する要素。 |
<enabled> |
trueの場合、インストゥルメンテーションは有効です。falseの場合、インストゥルメントされたコードは、このインストゥルメンテーション・スコープのクラスに挿入されておらず、このスコープ内のすべての診断モニターは無効です。デフォルト値はfalseです。 サーバーとそこにデプロイされているアプリケーションに対するインストゥルメンテーションを有効にするには、サーバー・レベルでインストゥルメンテーションを有効にする必要があります。さらに、(サーバー・スコープのインストゥルメンテーションの有効化に加えて)アプリケーションに対するインストゥルメンテーションを有効にするには、アプリケーション・レベルでインストゥルメンテーションを有効にする必要があります。 |
<include> |
インストゥルメントされたコードを挿入できるクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<include>要素を指定できます。指定した場合、インストゥルメンテーションの対象となるには、クラスは<include>パターンに一致する必要があります。 アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>または<exclude>パターンを指定すると、アプリケーション・スコープ全体に適用されます。 注意: 特定の診断モニターに対して<include>パターンおよび<exclude>パターンを指定することもできます。表12-1の<include>および<exclude>の項目を参照してください。 クラスがロードされると、インストゥルメンテーション・コードを挿入する前に、include/excludeのパターン・チェックに成功する必要があります。クラスがinclude/excludeのパターン・チェックに成功した場合でも、インストゥルメントされるかどうかは、構成記述子で定義されている診断モニターによって決まります。ライブラリ内にあるアプリケーション・スコープの委任モニターには、あらかじめ定義されている独自のクラスおよびポイントカットがあります。カスタム・モニターでは、独自のポイントカット式を指定します。そのため、include/excludeのパターン・チェックに成功しても、クラスはインストゥルメントされない場合があります。 注意:インストゥルメンテーションは、クラスのロード時にアプリケーションに挿入されます。サイズの大きなアプリケーションを頻繁にロードする環境では、<include>または<exclude>要素をうまく使用すれば、利便性の向上を期待できます。小さなアプリケーションや、中規模または大規模のアプリケーションでも頻繁にロードしない場合は、この要素を無視してもかまいません。 |
<exclude> |
インストゥルメントされたコードを挿入できないクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<exclude>要素を指定できます。指定した場合、<exclude>パターンに一致するクラスはインストゥルメントされません。 アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>要素の前述の説明を参照してください。 |
診断モニターは、次の記述子の<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モニターの構成は、「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。
表12-3は、<wldf-instrumentation-monitor>要素について説明します。
表12-3 DIAG_MODULE.xmlまたはweblogic-diagnostics.xmlファイル内の<wldf-instrumentation-monitor> XML要素
要素 | 説明 |
---|---|
<wldf-instrumentation-monitor> |
診断モニターの構成を開始する要素。 |
<enabled> |
trueの場合、モニターは有効です。falseの場合、モニターは無効です。各モニターを個別に有効または無効にできます。デフォルト値はtrueです。 |
<name> |
モニターの名前。標準モニターと委任モニターの場合は、「WLDFインストゥルメンテーション・ライブラリ」であらかじめ定義されているモニターの名前を使用します。カスタム・モニターの場合は、モニターを識別する任意の文字列です。カスタム・モニターの名前は一意でなければなりません。つまり、ライブラリ内の他のモニターと名前が重複することはできません。 |
<description> |
モニターを説明する要素(オプション)。 |
<action> |
委任モニターとカスタム・モニターに適用される要素(オプション)。少なくともアクションを1つは指定しないと、モニターは情報を生成しません。複数の<action>要素を指定できます。アクションは、モニターのタイプに対応している必要があります。委任モニターとカスタム・モニター用にあらかじめ定義されているアクションのリストは、「WLDFインストゥルメンテーション・ライブラリ」を参照してください。 |
<dye-filtering-enabled> |
省略可能な要素。trueの場合、そのモニターで仕分けフィルタが有効になります。falseの場合、仕分けフィルタは無効です。デフォルト値はfalseです。 仕分けフィルタを使用するには、DyeInjectionモニターをサーバー・レベルで適切に構成する必要があります。 |
<dye-mask> |
省略可能な要素。仕分けフィルタが有効になっている場合、仕分けマスクは、診断コンテキスト内の値と比較して、アクションを起こすかどうかを決定します。仕分けおよび仕分けフィルタの詳細は、「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。 |
<properties> |
省略可能な要素。仕分けフラグ用にname=valueのペアを設定します。 現在はDyeInjectionモニターにのみ適用されます。 |
<location-type> |
before、after、aroundのいずれかの値を持つ要素(オプション)。この要素によって、ポイントカットを基準にアクションがトリガーされるタイミング(ポイントカットの前でトリガーされるか、ポイントカットの後でトリガーされるか、ポイントカットの前後でトリガーされるか)が決まります。 カスタム・モニターの場合にのみ有効。標準モニターおよび代理モニターでは、この値はあらかじめ定義されています。カスタム・モニターでは、診断ロケーションの種類とポイントカットを定義する必要があります。 |
<pointcut> |
省略可能な要素。ポイントカット要素には、診断コードが挿入されるジョインポイントを定義する式が格納されます。 カスタム・モニターの場合にのみ有効です。標準モニターおよび委任モニターでは、この値はあらかじめ定義されています。カスタム・モニターでは、診断ロケーションの種類とポイントカットを定義する必要があります。 ポイントカットの構文については、「カスタム・モニターのポイントカットの定義」を参照してください。 |
<include> |
インストゥルメントされたコードを挿入できるクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<include>要素を指定できます。指定した場合、インストゥルメンテーションの対象となるには、クラスは<include>パターンに一致する必要があります。 アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>または<exclude>パターンを指定すると、親<wldf-instrumentation-monitor>要素で定義されるモニターにのみ適用されます。 注意:インストゥルメントされたアプリケーション・スコープ全体に対して<include>パターンおよび<exclude>パターンを指定することもできます。表12-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)
このうようにして、仕分けフィルタのメカニズムを使用すると、モニターは特定のリクエストに対してのみ診断アクションを実行でき、それによって他のリクエストの処理が遅くなることはありません。診断コンテキストおよび仕分けベクトルの詳細は、「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。
表12-4に、各モニター・タイプに適用する<wldf-instrumentation-monitor>要素を示します。Xの場合、要素は対応するモニターに適用され、N/Aの場合は適用されません。
表12-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ペアを設定する場合にのみ使用されます。
サーバー・レベルでインストゥルメンテーションを有効にし、サーバー・スコープのモニターを構成するには、以下の手順を実行します。
例12-1に、サーバー・スコープ・インストゥルメンテーションの構成ファイルのサンプルを示します。このサンプルでは、インストゥルメンテーションを有効にし、DyeInjection標準モニターおよびConnector_Before_Work委任モニターを構成します。1つの<instrumentation>要素に、モジュールのすべてのインストゥルメンテーションの構成が格納されます。各診断モニターは、個別の<wldf-instrumentation-monitor>要素で定義されます。
例12-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のみです。詳細は、「診断モニター・ライブラリ」のHttpSessionDebugMonitorの項目を参照してください。
委任モニターは、サーバー・スコープかアプリケーション・スコープのどちらかです。アプリケーションは、アプリケーション・スコープの委任モニターを使用する必要があります。
カスタム・モニターはすべてアプリケーション・スコープです。
サーバーのインストゥルメンテーション設定は、アプリケーションに影響します。インストゥルメンテーションをアプリケーションに対して有効にするには、アプリケーションがデプロイされるサーバーでインストゥルメンテーションを有効にする必要があります。デプロイメント時にサーバーのインストゥルメンテーションが有効である場合、アプリケーションでインストゥルメンテーションを利用できます。デプロイメント時にサーバーでインストゥルメンテーションが有効になっていない場合、アプリケーションでインストゥルメンテーションを有効にしても無視されます。
アプリケーションのインストゥルメンテーションは、weblogic-diagnostics.xml
記述子ファイルで構成されます。ユーザーはMETA-INF/weblogic-diagnostics.xml
ファイルを作成し、インストゥルメンテーションを構成して、アプリケーションのアーカイブにファイルを格納します。アーカイブがデプロイされると、インストゥルメンテーションは、アプリケーションがロードされたときに自動的に挿入されます。
「デプロイメント・プラン」を使用すると、アプリケーションを再デプロイしなくても、構成要素を動的に更新できます。「インストゥルメンテーション構成を動的に制御するためのデプロイメント・プランの使用」を参照してください
アプリケーション・スコープ・インストゥルメンテーションのXML記述子は、サーバー・スコープ・インストゥルメンテーションの場合と同じ方法で定義されます。WLDFインストゥルメンテーション・ライブラリで使用可能な委任モニターと診断アクションを使用すると、アプリケーション専用のインストゥルメンテーションを構成できます。また、ユーザー独自のカスタム・モニターも作成できますが、カスタム・モニターにアタッチする診断アクションは、WLDFインストゥルメンテーション・ライブラリから指定する必要があります。
表12-5では、システム・モジュールとアプリケーション・モジュールの機能とスコープを比較します。
表12-5 システム・モジュールとアプリケーション・モジュールの比較
モジュールの種類 | オブジェクトの動的な追加または削除 | コンソールでのオブジェクトの追加または削除 | JMXでのリモート変更 | JSR-88での変更(非リモート) | コンソールでの変更 | 仕分けフィルタと仕分けマスクの動的な有効化または無効化 |
---|---|---|---|---|---|---|
システム・モジュール |
はい |
はい |
はい |
いいえ |
はい (JMXから) |
はい |
アプリケーション・モジュール |
可(ホットスワップが有効な場合) 不可(ホットスワップが有効でない場合: モジュールを再デプロイする必要があります) |
はい |
いいえ |
はい |
はい (プランから) |
はい |
注意:
WebLogic Server 10.3以降では、前のWebLogic Serverリリースと同様に、アプリケーションのMETA-INF
ディレクトリにweblogic-diagnostics.xml
ファイルを作成する必要ありません。ただし、この方法でアプリケーションの診断モニターを最初に構成することもできます。
アプリケーションの診断モニターを実装するには、以下の手順を実行します。
以下の点に注意します。
weblogic-diagnostics.xml
で定義された診断モニターは、WebLogic Server管理コンソールのデプロイメント: <server_name>: 構成: インストゥルメンテーション・ページにリストされます。
アプリケーション・アーカイブ内のMETA-INF/weblogic-diagnostics.xml
記述子でモニターが定義されている場合、そのモニターはWebLogic Server管理コンソールを使用して削除できません。ただし、その無効化や有効化はWebLogic Server管理コンソールを使用して実行できます。
WebLogic Server管理コンソールから別のモニターを追加できます。WebLogic Server管理コンソールから追加したモニターは、weblogic-diagnostics.xml
には保持されず、アプリケーションのデプロイメント計画に保存されます。この方法で追加したモニターは、WebLogic Server管理コンソールで削除できます。
サーバーのクラスパスに配置されているアプリケーション・クラスおよびライブラリはインストゥルメントされません。アプリケーション・クラスのインストゥルメンテーションは、アプリケーション・クラスローダーによりロードされるクラスに対してのみ動作します。
アプリケーション・クラスがシステム・クラスパスに(意図的または偶発的に)配置されている場合、それらのクラスはシステム・クラスローダーによりロードされます。このため、これらのクラスに対してはデプロイメント時間のウィービングは実行されません。
次に、アプリケーション・スコープの代理モニター用に整形された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
ファイルの例を示します。このファイルには少なくとも太字で示す行を含める必要があります。
例12-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>)に呼び出されます。表12-6に、例12-2のポイントカット式が解析される仕組みを示します。(ワイルドカード文字の使用に注意してください。)
表12-6 ポイントカット式のサンプルの説明
ポイントカット式 | 説明 |
---|---|
call( * com.foo.bar.* get* (...)) |
|
call( * com.foo.bar.* get* (...))
|
|
call( * com.foo.bar.* get* (...))
|
|
call( * com.foo.bar.* get* (...))
|
|
call( * com.foo.bar.* get* (...))
|
|
このポイントカット式は、パッケージcom.foo.barとそのサブパッケージ内にあるすべてのクラスのすべてのメソッドを一致対象にします。メソッドは、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(...));
また、次のようにワイルドカード文字を使用することもできます。次のポイントカットは、クラスFoo
の内部クラスBar
のgetterメソッドとのみ一致します。
execution ( * Foo$Bar get*(...));
先頭および末尾のワイルドカード文字を使用することもできます。次の例も、クラスFoo$Bar
のgetterメソッドと一致します。
execution ( * Foo$Ba* get*(...)); execution ( * *oo$Bar get*(...)); execution ( * *oo$Ba* get*(...));
サーバー・スコープまたはアプリケーション・スコープのインストゥルメントを構成している場合、リクエスト・パフォーマンス・データをWebLogic Server管理コンソールに表示できます。「リクエスト・パフォーマンス」ページには、Weblogic診断フレームワーク・インストゥルメンテーション機能で取得するメソッド・パフォーマンスのリアルタイムと履歴ビューの情報が表示されます。
リクエスト・パフォーマンス・データを作成するには、次の基準が満たされる必要があります。
WLDFシステム・リソースを作成し、サーバーにターゲット指定する必要があります。「インストゥルメンテーション構成ファイル」 に説明されているとおりに、システム・リソースを作成してくださいこれは、WebLogic Server管理コンソールまたはWebLogic Scripting Tool (WLST)を使用して行います。
ターゲットとなるWLDFシステム・リソースで、インストゥルメンテーションが有効になっている必要があります。
アプリケーション・インストゥルメンテーションは、「インストゥルメンテーション構成ファイル」
に説明されているとおりに、アプリケーションのMETA-INF
ディレクトリ内に作成するweblogic-diagnostics.xml 記述子で有効にする必要があります
アプリケーション・インストゥルメンテーションの記述子では、Aroundタイプの診断モニターにアタッチされたTraceElapsedTimeAction診断アクションを使用する必要があります。たとえば、次のような記述が含まれる記述子を使用します。
<instrumentation> <enabled>true</enabled> <wldf-instrumentation-monitor> <name>Connector_Around_Inbound</name> <action>TraceElapsedTimeAction</action> </wldf-instrumentation-monitor> </instrumentation>
注意:
WebLogic Serverでは、デプロイ済アプリケーションのインストゥルメンテーションを変更をするために、weblogic-diagnostics.xml
記述子がアプリケーションのアーカイブにバンドルされている必要はありません。
アプリケーションでデプロイメント・プランを使用している場合、アプリケーションをデプロイする前にOracleホットスワップを有効にすると、アプリケーションを再デプロイせずに実行時にインストゥルメンテーションを変更できます。
デプロイされたアプリケーションにデプロイメント計画がない場合、アプリケーションのインストゥルメンテーション構成を変更すると、WebLogic Server管理コンソールによって自動的にデプロイメント計画が作成され、その保存場所を入力するよう求められます。
デプロイメント・プランでOracleホットスワップが有効になっていない場合またはデプロイメント・プランを使用しない場合、いくつかのインストゥルメンテーション設定を再デプロイする必要があります。
詳細は、「WLDFアプリケーション・モジュールのデプロイ」を参照してください。
「前後」タイプ・モニターのリストは、「WLDFインストゥルメンテーション・ライブラリ」を参照してください。
WebLogic Server管理コンソールでのリクエスト・パフォーマンス・データの作成と分析の詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのリクエスト・パフォーマンスの分析を参照してください。