ProbeBuilder ディレクティブ

 
apmdevops104jp
 
.
ProbeBuilder ディレクティブの概要
ProbeBuilder ディレクティブ(PBD)ファイルによって、アプリケーションをインスツルメントするために、Introscope ProbeBuilder がどのようにタイマやカウンタなどのプローブを追加するかが指定されます。PBD ファイルにより、エージェントが Enterprise Manager にレポートするメトリックを管理します。
注:
すべてのメトリックは、システム クロックに設定された時刻を使用して計算されます。システム クロックがトランザクション処理中にリセットされた場合、そのトランザクションでレポートされた経過時間は誤っている可能性があります。
CA APM には、デフォルトの PBD ファイルのセットが含まれています。また、アプリケーション固有の情報を取得するために、クラスまたはメソッドを追跡するカスタムの PBD を作成できます。
ProbeBuilder ディレクティブは 2 種類のファイルによって指定されます。
  • ProbeBuilder ディレクティブ(PBD)ファイル
    ProbeBuilder ディレクティブ(PBD)ファイルには、アプリケーションをインスツルメントする際に ProbeBuilder が使用するディレクティブが含まれています。このファイルによって、エージェントが Enterprise Manager にレポートするメトリックが決定されます。
  • ProbeBuilder リスト(PBL)ファイル
    ProbeBuilder リスト(PBL)ファイルには、複数の PBD ファイル名のリストが含まれます。異なる PBL ファイルで同じ PBD ファイルを参照できます。
     
重要:
PBD と PBL は ASCII 文字のみをサポートしています。PBD または PBL にほかの文字(Unicode 文字など)を挿入すると、AutoProbe で問題が発生する可能性があります。
AutoProbe を使用してアプリケーションをインスツルメントする場合、特定のアプリケーション サーバに関連するファイルは、Java エージェントをインストールするときに追加されます。これらの PBD
および PBL ファイルは
<Agent_Home>
\core\config ディレクトリに配置されます。
デフォルト PBD のコンポーネント追跡
デフォルト PBD ファイルは、以下の Java コンポーネントの追跡を実装します。
  • Oracle JDBC
  • JSP タグ ライブラリ
  • JSP IO タグ ライブラリ
  • JSP DB タグ ライブラリ
  • Struts
  • Servlets
  • JavaServer Faces (JSF)
  • JavaServer Pages (JSP)
  • Enterprise JavaBeans (EJB)
  • Java Database Connectivity (JDBC)
  • ネットワーク ソケット
  • リモート メソッド呼び出し(RMI)
  • 拡張可能マークアップ言語(XML)
  • Java Transaction API (JTA)
  • Java Naming and Directory Interface (JNDI)
  • JMS(Java Message Service)
  • Common Object Request Broker Architecture (CORBA)
  • User Datagram Protocol (UDP)
  • ファイル システム
  • Threads
  • システム ログ
  • スローおよびキャッチされた例外(デフォルトではオフ)
場合によっては、管理者は非常に多くの Java クラスを PBD の中で監視対象として選択します。あまりにも多くの Java クラスを持つと、Java エージェントの起動が正常に行われなかったり、ハング状態になってしまうことがあります。このような場合、問題のあるクラスをスキップするように PBD ファイルを設定することができます。
以下の手順に従います。
  1. エージェントの起動が正しく行われないことまたはハング状態になったことを確認したら、
    AutoProbe.log
    ファイルを開きます。
  2. Java エージェントをハングさせているクラスを特定します。
  3. 問題の原因となったクラスをスキップして、PBD ファイルにスキップ ディレクティブを追加します。
  4. PBD を保存します。
一般的に使用される PBD ファイル
Java エージェントには、以下の一般的に使用される PBD ファイルが含まれます。
  • appmap.pbd
    この PBD は、アプリケーション問題切り分けマップのインスツルメンテーションに使用するトレーサ ディレクティブを提供します。
  • appmap-ejb.pbd
    この PBD はアプリケーション問題切り分けマップの EJB インスツルメンテーションに使用するトレーサ ディレクティブを提供します。
  • appmap-soa.pbd
    この PBD は Java SOAP スタックをサポートする SOA Performance Management のために、アプリケーション問題切り分けマップの SOA インスツルメンテーションに使用するトレーサ ディレクティブを提供します。
  • AutoPersist.pbd
    この PBD は、自動エントリ ポイント検出で検出される監視対象エントリ ポイントおよびエントリ ポイントとしてスキップされるクラスを保持します。
  • bizrecording.pbd
    この PBD はエージェント ビジネス記録をセットアップするトレーサ定義およびディレクティブを提供します。
  • biz-trx-http.pbd
    この PBD は、ビジネス セントリックの HTTP インスツルメンテーションに使用するトレーサ ディレクティブを提供します。
  • di.pbd
    この PBD は、エージェントが動的インスツルメンテーションで内部的に使用する Apache Derby 実装クラスをスキップする ProbeBuilder ディレクティブを提供します。
  • endUserEndpoints.pbd
    ワイヤレス プロバイダの属性を集計し、各モバイル ビジネス トランザクションの下のメトリックとしてそれらを発行します。
  • errors.pbd
     この PBD は、重大なエラーを発生させるコード レベルのイベントを指定して、ErrorDetector を設定します。デフォルトでは、フロントエンドおよびバックエンドのエラーのみが重大と見なされます。重大なエラーは、ユーザにエラー ページとして表示されるエラーやバックエンド システムの問題を示します。バックエンド システムには、ADO.NET、メッセージングなどが含まれます。
  • j2ee.pbd
    この PBD は、一般的な Java Enterprise Edition コンポーネント用のトレーサ グループを提供します。特定の追跡を TurnOn にするには、
    toggles-full.pbd
    または
    toggles-typical.pbd
    を使用します。
  • java2.pbd
    この PBD は、一般的な Java 2 コンポーネント用のトレーサ グループを提供します。特定の追跡を
    TurnOn
    にするには、
    toggles-full.pbd
    または
    toggles-typical.pbd
    を使用します。
  • jsf.pbd
    この PBD は、Java Server Face (JSF)コンポーネント用のトレーサ グループを提供します。
  • jsf-toggles-full.pbd
    この PBD は、
    jsf.pbd
    で提供されている追跡に対して、
    TurnOn
    ディレクティブの形式でオン/オフを切り替えます。ほとんどのトレーサ グループがオンになります。
  • jsf-toggles-typical.pbd
    この PBD は、
    jsf.pbd
    で提供されている追跡に対して、
    TurnOn
    ディレクティブの形式でオン/オフを切り替えます。
  • jvm.pbd
    この PBD は、さまざまな Java 仮想マシンに対するサポートを実装するディレクティブを提供します。Introscope デフォルト ファイルと一緒に使用します。
  • leakhunter.pbd
    この PBD は、リーク検出ユーティリティである CA APM LeakHunter のインスツルメンテーション設定を提供します。通常、このファイルの内容を変更することはありません。
  • oraclejdbc.pbd
    この PBD は、Oracle JDBC コンポーネント用のトレーサ グループを提供します。
    TurnOn
    ディレクティブをコメント化またはコメント化を解除して、追跡対象の Oracle JDBC コンポーネントのセットを変更できます。
  • ServletHeaderDecorator.pbd
     この PBD は、CA CEM 製品との統合の一部であるサーブレット ヘッダ デコレータを有効にします。
  • smwebagentext.pbd
    この PBD は、SiteMinder Web エージェント Introscope プラグイン用のトレーサを提供します。
  • soaagent.pbd
    この PBD は、CA SOA セキュリティ マネージャの一部である TransactionMinder エージェント用のトレーサを提供します。(Web サーバおよびアプリケーション サーバの SOA エージェント)
  • struts.pbd
    この PBD は、Apache Struts を監視するディレクティブを提供します。Introscope デフォルト ファイルと一緒に使用します。
  • taglibs.pbd
    この PBD は、JSP タグ ライブラリ、Jakarta I/O ライブラリ、および 
    DGTags
     タグ ライブラリとして追跡されるべきクラスを監視するディレクティブを提供します。
  • TIBCO.pbd
    Java エージェントは、CA APM for SOA Performance Management を使用した TIBCO の監視に関連するいくつかの PBD と一緒にインストールされます。
  • toggles-full.pbd
    この PBD は、他のディレクティブ ファイルで指定されている追跡について、
    TurnOn
    ディレクティブの形式でオン/オフを切り替えます。ほとんどのトレーサ グループがオンになります。
  • toggles-typical.pbd
    この PBD は、他のディレクティブ ファイルで指定されている追跡について、
    TurnOn
    ディレクティブの形式でオン/オフを切り替えます。トレーサ グループのごく一部のみがオンになります。
  • webMethod の PBD
    Java エージェントは、CA APM for webMethods Broker を使用した webMethods の監視に関連するいくつかの PBD と一緒にインストールされます。
  • WebSphere MQ の PBD
    Java Agent は、IBM WebSphere MQ コネクタおよびメッセージング システムの監視に関連するいくつかの PBD と一緒にインストールされます。この監視は CA APM for IBM websphere_mq を使用して実施されます。
Java エージェントは、アプリケーション サーバ特有の PBD もインストールします。これは監視しているアプリケーション サーバによって異なります。
デフォルトの PBL ファイル
各エージェントで利用できる PBL ファイルは、以下の 2 つです。
  • default-full.pbl
    ほとんどのトレーサ グループがオンに設定されている PBD ファイルを参照します。Introscope は、このセットをデフォルトで使用して、Introscope のフル機能を発揮します。
  • default-typical.pbl (デフォルト)
    参照される PBD ファイル内のトレーサ グループのサブセットがオンになります。標準セットには共通の設定が含まれます。これは、特定の環境に合わせてカスタマイズできるセットです。
また、Java エージェントは、アプリケーション サーバ特有の PBL もインストールします。これは監視しているアプリケーション サーバによって異なります。
デフォルトのトレーサ グループおよびトグル ファイル
トレーサ グループは PBD ファイルに定義します。トレーサ グループによって、クラス セットについての情報がレポートされます。PBD ファイルでは、トレーサ グループは用語
flag
によって参照されます。たとえば、
TraceOneMethodIfFlagged
または
SetFlag
は、トレーサ グループの情報を定義します。
トレーサ グループは、クラスのセットに適用されるトレーサのセットで構成されます。たとえば、すべての RMI クラスの応答時間および速度をレポートするトレーサ グループがあります。
特定のトレーサ グループをオンまたはオフにして、システムでのメトリックの収集を細かく設定することができます。この方法は、トレーサ グループの設定方法によって、オーバーヘッドの増減に影響を与えます。
トレーサ グループは、
default-full.pbl
ファイルと
default-typical.
pb
l ファイルによって参照される
toggles-full.pbd
ファイルと
toggles-typical.pbd
ファイルで変更されます。以下に、デフォルトのトレーサ グループおよびそれらのデフォルト設定のリストを示します。
  • AgentInitialization
    エージェントの初期化設定
    フル: オン
    標準: オン
  • ApacheStandardSessionTracing
    HTTP セッションの設定
    フル: オン
    標準: オン
  • AuthenticationTracing
    認証の設定
    フル: オン
    標準: オン
  • CorbaTracing
    CORBA メソッド呼び出し
    フル: オン
    標準: オン
  • DBCPTracing
    DBCP 設定
    フル: オン
    標準: オン
  • DBCPv55Tracing
    DBCP 設定
    フル: オン
    標準: オン
  • EJB2StubTracing
    EJB 2.0 の設定
    フル: オン
    標準: オン
  • EJB3StubTracing
    EJB 3.0 の設定
    フル: オン
    標準: オン
  • EntityBean3Tracing
    エンティティ EJB 3.0 メソッド呼び出し
    フル: オン
    標準: オン
  • EntityBeanTracing
    エンティティ EJB メソッド呼び出し
    フル: オン
    標準: オン
  • HTTPServletTracing
    HTTP サーブレット サービス応答
    フル: オン
    標準: オン
    アプリケーション サーバ AutoProbe を使用している場合、
    HTTPAppServerAutoProbeServletTracing
    トレーサ グループをオンにします。
  • InstanceCounts
    トレーサ グループで識別されるオブジェクト タイプのインスタンスの数をカウントします。
    フル: オン
    標準: オン
    このトレーサ グループでクラスが特定されるまで、どのグループの追跡も行われません。
  • J2eeConnectorTracing
    J2EE 接続情報
    フル: オン
    標準: オン
  • JavaMailTransportTracing
    メール送信回数
    フル: オン
    標準: オン
  • JDBCQueryTracing
    JDBC クエリ
    フル: オン
    標準: オン
  • JDBCUpdateTracing
    JDBC 更新
    フル: オン
    標準: オン
  • JMSConsumerTracing
    JMS メッセージ処理回数
    フル: オン
    標準: オン
  • JMSListenerTracing
    JMS メッセージ処理回数
    フル: オン
    標準: オン
  • JMSPublisherTracing
    JMS メッセージ ブロードキャスト回数
    フル: オン
    標準: オン
  • JMSSenderTracing
    JMS メッセージ ブロードキャスト回数
    フル: オン
    標準: オン
  • JSPTracing
    JSP サービス応答
    フル: オン
    標準: オン
  • MessageDrivenBean3Tracing
    メッセージ駆動型の EJB 3.0 メソッド呼び出し
    フル: オン
    標準: オン
  • MessageDrivenBeanTracing
    メッセージ駆動型の EJB メソッド呼び出し
    フル: オン
    標準: オン
  • NIOSocketTracing
    このトレーサ グループは、
    NIO|Channels|Sockets
    ノードの下の各ソケット接続に一連のメトリックを生成し、[Backends]ノードの下にメトリックを追加します。
    フル: オン
    標準: オン
  • NIOSocketSummaryTracing
    すべての NIO ソケット接続を対象とする 1 つのセットのメトリックを生成します。
    フル: オン
    標準: オン
    これらのメトリックには、エージェント プロパティによって
    NIOSocketTracing
    メトリックから除外される接続が含まれます。これらのメトリックには、
    NIOSocketTracing
    メトリックから常に除外される内部 NIO ソケットも含まれます。
  • NIOSelectorTracing
    このトレーサ グループは、特定の内部 JVM による NIO チャンネルの使用が、NIO チャネル メトリックにカウントされないようにします。
    ユーザは、このオプションを変更することはできません。
  • NIODatagramTracing
    このトレーサ グループは、各データグラムの接続用の一連のメトリックを生成します。
    フル: オン
    標準: オン
  • NIODatagramSummaryTracing
    この Tracer グループはすべての NIO データグラム アクティビティをすべて測定する 1 つのセットのメトリックを生成します。
    フル: オン
    標準: オン
    これらのメトリックには、エージェント プロパティによって
    NIODatagramTracing
    メトリックから除外される接続が含まれます。これらのメトリックには、
    NIODatagramTracing
    メトリックから常に除外される内部 NIO ソケットも含まれます。
  • PersistentSessionTracing
    HTTP セッションの設定
    フル: オン
    標準: オン
  • RMIClientTracing
    RMI クライアント メソッド呼び出し
    フル: オン
    標準: オン
  • RMIServerTracing
    RMI サーバ メソッド呼び出し
    フル: オン
    標準: オン
  • ServerInfoTracing
    サーバ情報の設定
    フル: オン
    標準: オン
  • SessionBean3Tracing
    セッション EJB 3.0 メソッド呼び出し
    フル: オン
    標準: オン
  • SessionBeanTracing
    セッション EJB メソッド呼び出し
    フル: オン
    標準: オン
  • SocketTracing
    ネットワーク ソケット帯域幅および SSL トラッキング
    フル: オン
    標準: オン
  • StrutsTracing
    Struts フレームワークのアクションの実行回数
    フル: オン
    標準: オン
  • SuperpagesSessionTracing
    HTTP セッションの設定
    フル: オン
    標準: オン
  • ThreadPoolTracing
    スレッド プールの設定
    フル: オン
    標準: オン
  • UDPTracing
    ユーザ データグラム プロトコル(UDP)ソケット帯域幅
    フル: オン
    標準: オン
  • UnformattedSessionTracing
    HTTP セッションの設定
    フル: オン
    標準: オン
  • EJB3MethodLevelTracing
    メソッド レベルでの EJB 3.0 アクティビティ
    フル: オン
    標準: オフ
  • EJBMethodLevelTracing
    メソッド レベルでの EJB アクティビティ
    フル: オン
    標準: オフ
  • FileSystemTracing
    書き込みおよび読み取りされたファイル システムのバイト数
    フル: オン
    標準: オフ
  • JAXMListenerTracing
    JAXM メッセージの送信
    フル: オン
    標準: オフ
  • JNDITracing
    JNDI の参照回数
    フル: オン
    標準: オフ
  • JSPDBTagsTagLibraryTracing
    SQL データベースとの間で読み書きするための Jakarta DB タグのカスタム タブ ライブラリ
    フル: オン
    標準: オフ
  • JSPIOTagLibraryTracing
    さまざまな入出力タスクの Jakarta IO カスタム タグ ライブラリ
    フル: オン
    標準: オフ
  • JTACommitTracing
    JTA を使用するコミット回数
    フル: オン
    標準: オフ
  • ThreadTracing
    クラス別のアクティブ スレッド数
    フル: オン
    標準: オフ
  • XMLSAXTracing
    XML ドキュメントの解析にかかる時間
    フル: オン
    標準: オフ
  • XSLTTracing
    XML 変換時間
    フル: オン
    標準: オフ
  • CatchException
    例外の設定
    フル: オフ
    標準: オフ
  • FormattedSessionTracing
    HTTP セッションの設定
    フル: オフ
    標準: オフ
  • HTTPAppServerAutoProbeServletTracing
    HTTP サーブレットの設定
    フル: オフ
    標準: オフ
  • HTTPSessionTracing
    HTTP セッションの設定
    フル: オフ
    標準: オフ
  • JSPTagLibraryTracing
    カスタム JSP タグの処理時間
    フル: オフ
    標準: オフ
  • ManagedSocketTracing
    ネットワークの設定
    フル: オフ
    標準: オフ
  • ThrowException
    例外の設定
    フル: オフ
    標準: オフ
通常は、デフォルトのトグル PBD ファイルを編集しないでください。 しかし、特定のトレーサ グループをオンまたはオフにすることによって、メトリックの収集を細かく指定することができます。Tracer グループは、トグル ファイルで以下の方法によって変更できます。
  • システム オーバーヘッドを低減するためにトレーサ グループをオン/オフにする
  • トレーサ グループへのクラスの追加
トレーサ グループは、オンに設定されており
TurnOn
キーワードによってアクティブ化されている(コメント解除されている)場合のみ情報をレポートします。
注:
Java エージェントは EJB (2.0 以降)のインスツルメンテーションをサポートしています。EJB と関連付けられたトレーサ グループをオンまたはオフにして、メトリック コレクションを調整します。アプリケーション問題切り分けマップでの EJB のサポートは、セッション Bean とエンティティ Bean のみを対象とします。メッセージ駆動型 Bean はサポートされていません。
さらなるメトリック情報を収集するためのトグルの設定
以下のトグルがオンになると、エージェントはすべての API で、有効になっている CA APM で提供されるトレーサ グループの追加メトリックを収集します。設定を変更するには、
toggles-full.pbd
および
toggles-typical.pbd
ファイルに以下のトグルを追加する必要があります。
  • DefaultStalledMethodTracing
    停止したメソッド追跡
    フル: オン
    標準: オン
  • DefaultConcurrentInvocationTracing
    同時進行中の呼び出し情報
    フル: オン
    標準: オフ
  • DefaultRateMetrics
    呼び出し速度のメトリック
    フル: オフ
    標準: オフ
トレーサ グループのオンまたはオフ
特定のトレーサ グループをオンまたはオフにして、システムでのメトリックの収集を細かく設定することができます。トレーサ グループのディレクティブのコメント化を解除する(ディレクティブをオンにする)と、そのトレーサ グループが使用されます。
トレーサ グループのオン
以下の手順に従います。
  1. toggles-full.pbd ファイルまたは toggles-typical.pbd ファイルを見つけます(AutoProbe または Java エージェントが <appserver>-full.pbl と <appserver>-typical.pbl のどちらの種類のファイルを使用しているかによって決まります)。これらのファイルは、
    <Agent_Home>
    /core/config または
    <EM_Home>
    /config/systempbd ディレクトリにあります。
     
  2. オンにするトレーサ グループを見つけます。行頭のシャープ記号を削除して、その行のコメント化を解除します。以下の例のディレクティブをオンにすると、すべての HTTP サーブレットが追跡されます。
    TurnOn: HTTPServletTracing
トレーサ グループのオフ
  • トレーサ グループをオフにするには、以下の例のように行頭にシャープ記号を挿入することによって、その行をコメントにします。
    #TurnOn: HTTPServletTracing
トレーサ グループへのクラスの追加
特定のクラスの追跡をオンにするには、そのクラスを既存のトレーサ グループに追加します。クラスをトレーサ グループに含めるには、いずれかの「Identify」キーワードを使用します。
たとえば、クラス
com.myCo.ejbentity.myEJB1
をトレーサ グループ
EntityBeanTracing
に追加するには、以下のように指定します。
IdentifyClassAs: com.myCo.ejbentity.myEJB1 EntityBeanTracing
「Identify」キーワードは以下のとおりです。
  • IdentifyInheritedAs
  • IdentifyClassAs
  • IdentifyCorbaAs
EJB サブクラスの追跡
デフォルトで、エンティティの EJB に関連するディレクティブは、エンティティの EJB インターフェースを直接、明示的に実装する EJB のみに Probe を追加します。セッション、およびメッセージ駆動型の EJB に関連するディレクティブも、セッション、またはメッセージ駆動型の EJB インターフェースを直接、明示的に実装する EJB に Probe を追加します。
通常、アプリケーションの EJB は、エンティティまたはセッション EJB インターフェースを直接、明示的に実装するクラスのサブクラスです。Introscope では、これらのサブクラスはデフォルトでは追加されません。
EJB サブクラスを追跡する Introscope のために、そのサブクラスを適切なトレーサ グループに追加します。Introscope が追跡する EJB サブクラスの直接の上位クラスを参照するエントリを追加します。
以下のモデルで、
<entity.bean.ancestor.class>
または
<session.bean.ancestor.class>
をインスツルメントされる EJB の直接の上位クラスの完全修飾名に置き換えます。
エンティティ EJB の場合:
IdentifyInheritedAs: <entity.bean.ancestor.class> EntityBeanTracing
セッション EJB の場合:
IdentifyInheritedAs: <session.bean.ancestor.class> SessionBeanTracing
以下の例は、次のクラス階層に基づいています。
mySessionEJB implements javax.ejb.SessionBean
   mySessionEJBsubclass1 extends mySessionEJB
mySessionEJBsubclass1a extends mySessionEJBsubclass1
mySessionEJBsubclass1b extends mySessionEJBsubclass1
mySessionEJBsubclass2 extends mySessionEJB
トレーサ グループ
SessionBeanTracing
では、
mySessionEJB
が追跡されます。
以下のトレーサは、
mySessionEJBsubclass1
および
mySessionEJBsubclass2
を追跡します。
:IdentifyInheritedAs:
mySessionEJB SessionBeanTracing
以下のトレーサは、
mySessionEJBsubclass1a
および
mySessionEJBsubclass1b
を追跡します。
IdentifyInheritedAs: mySessionEJBsubclass1 SessionBeanTracing
注:
この例では、パッケージを使用していません。コードがパッケージ内にある場合は、パッケージ名をクラス名に含めます。
EJB 3.0 アノテーション
IdentifyAnnotatedClass
ディレクティブを使用すると、Tracer グループに指定されたクラス レベルのアノテーションが含まれている任意のクラスをグループ化することができます。このディレクティブは EJB 3.0 をサポートしています。3.0 仕様に準拠する EJB は明示的に既知のインターフェースを実装しませんが、代わりにアノテーションを使用することによって完全に識別可能になっています。このディレクティブは、メソッドレベルのアノテーションはサポート
していません
以下の例に示すように、EJB 3.0 クラスを簡単に識別するには、
IdentifyAnnotatedClass
ディレクティブを使用します。
IdentifyAnnotatedClass <annotation-name> <flag-name>
PBD に IdentifyAnnotatedClass ディレクティブを追加するには
  1. 新しいディレクティブに対してディレクティブ クラスおよびディレクティブ パーサ クラスを作成します。
  2. クラスのバイトコードを検査するために matcher クラスを追加することで、クラスが指定のアノテーションを含むかどうかを判別します。
アプリケーション問題切り分けマップでの EJB のサポート
Introscope では、EJB (2.0 以降)のセッション Bean およびエンティティ Bean の付属の追跡機能をサポートしています。具体的には、アプリケーション問題切り分けマップで使用します。付属の機能を設定するとエージェントの起動時間に影響するため、この機能をテスト環境のみで使用することをお勧めします。
実稼働環境にこの機能をデプロイする場合は、EJB トレーサの対象を特定して設定します。これはデフォルトの機能では対象範囲が広すぎる場合があるためです。
スーパークラスまたはインターフェースを継承または実装しているクラスにフラグを設定するように ProbeBuilder に指示するには、このディレクティブを使用します。
IdentifyDeepInheritedAs
EJB 2.0 のアプリケーション問題切り分けマップをサポートするために、ディレクティブが
 j2ee.pbd
ファイルにあります。アプリケーション問題切り分けマップでは、EJB スタブおよび Bean を使用します。以下のディレクティブを使用すると、ProbeBuilder は、クライアント側の EJB スタブと、サーバ側の Bean を識別することができます。
IdentifyDeepInheritedAs: javax.ejb.EJBObject EJB2StubTracing
IdentifyDeepInheritedAs: javax.ejb.SessionBean SessionBeanTracing
IdentifyDeepInheritedAs: javax.ejb.EntityBean EntityBeanTracing
IdentifyDeepInheritedAs: javax.ejb.MessageBean MessageBeanTracing
EJB 3.0 のアプリケーション問題切り分けマップをサポートするために、以下のディレクティブが
j2ee.pbd
ファイルにあります。
IdentifyInheritedAnnotatedClassAs
このディレクティブは、インターフェースを直接実装するすべてのクラス、またはスーパー インターフェースを通して実装するすべてのクラスを照合します。
アプリケーション問題切り分けマップのコンテキストでは、以下の追加のディレクティブが
j2ee.pbd
内に設定されます。
IdentifyInheritedAnnotatedClassAs: javax.ejb.Remote EJB3StubTracing
EJB の名前付け
呼び出されたバックエンド、汎用フロントエンド、および EJB を処理する監視対象コンポーネントには名前を付けることができます。名前付けのフォーマッタを使用すると、EJB (2.0 以降)のクライアント スタブや Bean の実装にふさわしい名前を設定できます。
EjbNameFormatter
クラスでは、EJB 関連のメトリック名、アプリケーション問題切り分けマップのアプリケーション名、またはノード名を定義します。以下のプレースホルダを使用します。
  • EJB クライアント スタブの場合:
    {classname}
    {interface}
    、および
    {method}
  • EJB bean の場合:
    {classname}
    {bean}
    {interface}
    、および
    {method}
以下のメトリック名がデフォルトで使用されます。
  • EJB Bean フロントエンド:
    EJB|{interface}
  • EJB クライアント スタブ バックエンド:
    EJB|{interface}
  • EJB Bean 用のアプリケーション問題切り分けマップの所有者名:
    {interface}
  • EJB クライアント スタブ用のアプリケーション問題切り分けマップのノード名:
    Client {interface}
  • EJB Bean 用のアプリケーション問題切り分けマップのノード名:
    Server {interface}
これらの名前はデフォルトの EJB 名フォーマッタです。これらは、
j2ee.pbd
および
appmap-ejb.pbd
ファイルで使用されます。同じ名前フォーマッタで別のメトリック名を使用します。たとえば、既存のトレーサ ディレクティブを変更してより適切な名前を使用しますが、同じフラグを維持したい場合は、以下のように実行します。
...
# Default commented out:
#TraceComplexMethodsIfFlagged: EJB2StubTracing EJB2BackendTracer "{interface}"
#Add the EJB application name to backend marker as well as called method
TraceComplexMethodsIfFlagged: EJB2StubTracing EJB2BackendTracer "MyCustomerBeanApp-{interface}-{method}"
...
SetTracerClassMapping: EJB2BackendTracer com.wily.introscope.agent.trace.BackendTracer com.wily.introscope.probebuilder.validate.ResourceNameValidator
SetTracerParameter: EJB2BackendTracer nameformatter com.wily.introscope.agent.trace.ejb.Ejb2StubNameFormatter
注:
EJB コンテキストのトレーサは、EJB 2.0 Bean の
setContext()
メソッドで設定されます。これは、EJB 2.0 Bean の名前フォーマッタ用の Introscope 内部トレーサです。これにより、名前フォーマッタが正しく機能できます。
IntroscopeAgent.profile、PBL、および PBD の同時使用
Java エージェントを最初にインストールするときに、インスツルメンテーションのレベルをフルまたは標準に設定します。この設定では、ProbeBuilder リスト(PBL)ファイル
default-typical.pbl
および
default-full.pbl
を参照します。
ProbeBuilder ディレクティブの適用
PBD を適用する方法は、使用するメソッドによって異なります。JVM AutoProbe を使用して PBD を実装することを勧めします。コマンド ライン ProbeBuilder を使用して、PBD を実装することもできます。
JVM AutoProbe の使用
以下のいずれかの方法を使用して、PBD ファイルを実装することができます。
  • hotdeploy
    ディレクトリにファイルを追加します。
    AutoProbe は、
    IntroscopeAgent.profile
    ファイルが含まれるディレクトリで PBD ファイルを検索します。デフォルトでは、AutoProbe は、<
    Agent_Home
    >/core/config および <
    Agent_Home
    >/core/config/hotdeploy ディレクトリで検索します。AutoProbe は、これらのディレクトリに対する相対パスによってファイル名を解決します。wily ディレクトリの場所を移動した場合は、ファイル パスを正しいディレクトリにマッピングします。
  • introscope.autoprobe.directivesFile
    プロパティにファイル名を追加します。
    AutoProbe は、自動的にプロパティから PBD のリストを再ロードします。
以下の手順に従います。
  1. 変更済みの標準の PBD または PBL を
    /core/confi
    g ディレクトリに保存します。
  2. カスタムの PBD
    /config/hot
    deploy ディレクトリにコピーします。Introscope は、エージェント プロファイルの
    introscope.autoprobe.directivesFile
    プロパティを更新または変更しなくても、このディレクトリに追加するすべての PBD を実装します。
    注:
    動的 ProbeBuilding を有効にしている場合、hotdeploy ディレクトリ内の PBD はフォルダからそのままピックアップされます。再起動は必要ありません。
  3. IntroscopeAgent.profile を保存します。
  4. 動的インスツルメンテーションが有効でない場合は、アプリケーションを再起動します。
コマンドライン ProbeBuilder の使用
PBD ファイルの実装の準備が整ったら、これを hotdeploy ディレクトリに追加します。コマンドライン ProbeBuilder は、Introscope が ProbeBuilder を実行しているディレクトリ、および
<Agent_Home>
/core/config/hotdeploy ディレクトリで、カスタム PBD を検索します。コマンド ライン ProbeBuilder は、これらのディレクトリに対する相対パスによってファイル名を解決します。
コマンド ライン ProbeBuilder を使用して ProbeBuilder ディレクティブを実装する手順は、JVM AutoProbe を使用する場合と同じです。
新規および変更済みの PBD を使用したインスツルメント
新規および変更済みのディレクティブを有効にするには、最新の PBD を使用して、アプリケーションをインスツルメントする必要があります。この手順は、使用している ProbeBuilding メソッドによって異なります。
-javaagent を介して JVM AutoProbe を使用する JVM 1.5 システム
動的 ProbeBuilding を設定すると、アプリケーションまたは Java エージェントを再起動しなくても変更済みの PBD を有効にできます。Dynamic ProbeBuilding によって、アプリケーションのサービスを中断しなくても、PBD の修正や切り分け駆動型(triage-driven)のインスツルメンテーションを実行できます。
新規および変更済みの ProbeBuilder ファイル
対象: -Xbootclasspath を使用するインストール
次回アプリケーション サーバがアプリケーション クラスをロードしたときに、新規および変更済みの PBD または PBL が有効になります。クラスのロードは、アプリケーションの開始や再起動を必要とする場合があります。
管理対象アプリケーションが実行されていない場合、更新済みのディレクティブは起動後にアプリケーションをインスツルメントします。
管理対象アプリケーションが実行されている場合は、管理対象アプリケーション クラスをロードまたは再ロードする必要があります。クラスを再ロードする方法は、使用するアプリケーション サーバによって異なります。ほとんどのアプリケーション サーバでは再起動する必要があります。
コマンドライン ProbeBuilder の使用
 
重要:
最新の PBD を使用できるように、コマンドライン ProbeBuilder を最終的なオプションとして使用することをお勧めします。
コマンド ライン ProbeBuilder を使用する方法
  1. 管理対象アプリケーションを停止します。
  2. コマンドライン ProbeBuilder を実行し、カスタムの PBD および PBL ファイルをコマンド ラインに入力します。
  3. 新規ファイルを使用できるようにアプリケーションを設定します。
  4. 管理対象アプリケーションを起動します。
  5. Enterprise Manager および Workstation を実行していない場合は実行します。
Blame トレーサを使用した Blame ポイントのマーク付け
Introscope の Blame テクノロジを管理対象 Java アプリケーションで使用すると、アプリケーション層(アプリケーションのフロントエンドおよびバックエンド)でのメトリックを表示できるようになります。この Boundary Blame と呼ばれる機能を使用すると、問題をアプリケーションのフロントエンドかバックエンドに切り分けることができます。この情報は、アプリケーションの境界線をマーク付けするために Workstation のアプリケーション問題切り分けマップで使用されます。
以下のセクションでは、トレーサを使用してアプリケーションのフロントエンドおよびバックエンドに明示的にマークを付ける方法について説明します。
Blame トレーサ
Introscope は、明示的にフロントエンドおよびバックエンドのトランザクションをマークすることでフロントエンドおよびバックエンドのメトリックをキャプチャするためのトレーサ(
FrontendMarker
および
BackendMarker 
)を提供しています。Introscope は
FrontendMarker
トレーサは、またはそのサブクラス
Http
ServletTracer および
PageInfoTracer
を使用してフロントエンド コンポーネントをインスツルメントすることができます。
FrontendMarker
および
BackendMarker
を使用して、独自のコードをインスツルメントすることができます。たとえば、バックエンドにアクセスするコードです。トレーサは、Introscope でカスタム コンポーネントのメトリックをキャプチャしたり Investigator ツリーに表示したりします。
FrontendMarker
トレーサまたはそのサブクラスでコンポーネントをインスツルメントする必要があり、そうでない場合、エージェントはフロントエンドのメトリックの生成せず、任意のコンポーネント トランザクションのフロントエンドとしてマークしません。
1 つのトランザクションで複数のコンポーネントが
FrontendMarker
トレーサまたはそのサブクラスを使用してインスツルメントされる場合、最初に指定されたコンポーネントのみがフロントエンド メトリックを生成します。
注:
フロントエンド トレーサを使用する場合、フロントエンド トレーサに指定されたアプリケーション名は、アプリケーション問題切り分けマップのトレーサに指定された名前と一致する
必要があります
。これらのトレーサ名では両方とも、大文字小文字が区別されます。たとえば、フロントエンド トレーサに
AppOne
という名前を付け、アプリケーション問題切り分けマップのトレーサがこのトレーサを APPONE として参照した場合、アプリケーション問題切り分けマップでは
AppOne
についての情報が正しく表示されません。
特定のクラスがフロントエンドとしてマークされないようにするために、PBD パラメータ
 
を指定することができます。
BackendMarker
が設定されていない場合、Introscope はバックエンドを推測します。バックエンドが明示的にマークされていない場合、クライアント ソケットを開くコンポーネントがデフォルト バックエンドになります。
BackendMarker
を使用して、以下の目標を達成します。
  • エージェントがバックエンドとして検出する項目に、適切な名前を割り当てる。
  • Introscope がインスツルメントしないカスタムの Java ソケットにマークを付ける。
  • Java/Java Native Interface (JNI)ブリッジ メソッドを、JNI を通じて呼び出されるネイティブ ソケットのためのバックエンドとして識別する。
FrontendMarker
および
BackendMarker
は、追跡対象のコンポーネントの間隔カウント、並行処理、ストール、およびエラーあたりの平均応答時間などのメトリックを提供する
BlamePointTracer, 
のインスタンスです。
BlamePointTracer
を「中間」コンポーネントに適用すれば、より細かく Blame スタックを調整できます。
複雑にネストされたフロントエンド トランザクションによるエージェント CPU の高オーバーヘッド
Introscope では、サーブレットをフロントエンドとみなすよう設定することができます。標準的なトランザクションは、サーブレットで開始します。これは、EJB を呼び出すことがあり、さらにこれがバックエンドを呼び出します。サーブレットは、ほかのサーブレットをネストする形で呼び出すことができます。このような場合、Introscope からはネストされたフロントエンドとして見えます。大抵の場合、この状況によって Agent CPU のオーバーヘッドが増加することはありません。
ただし、フロントエンド レベルでネストされた複雑なトランザクション(例:階層が 40 レベル)は、CPU に大きなオーバーヘッドをもたらす可能性があります。
以下の状況は、エージェント CPU のオーバーヘッドを増加させる、ネストされたフロントエンドの例です。
  • サーブレットがトランザクションでサーブレット自身を繰り返し呼び出す(連続的な再帰呼び出し)場合
  • サーブレットが他のサーブレットを複数の呼び出す場合
オーバーヘッドが許容範囲を超えた場合は、CA サポートにご連絡ください。
新しい PBD の作成によるエントリ ポイントのフロントエンドへの変換
自動エントリ ポイント検出を有効にした場合、エージェントは検出したエントリ ポイントを AutoPersist.pbd に書き込みます。新しい PBD を作成して、エントリ ポイントを、メトリックをレポートする監視対象フロントエンドに変換できます。
以下の手順に従います。
  1.  
    <
    Agent_Home
    >/core/config/hotdeploy ディレクトリの
    AutoPersist.pbd
     をテキスト エディタで開きます。
  2. TraceOneMethodOfClass
    ディレクティブで始まる行を見つけます。たとえば、以下の通りです。
    TraceOneMethodOfClass: org.springframework.aop.framework.ReflectiveMethodInvocation invokeJoinpoint()Ljava/lang/Object; AutoPersistTracer "Automatic Entry Points|{classname}|{method}
  3. 以下のディレクティブをコピーしてコメント アウトします。
    #TraceOneMethodOfClass: org.springframework.aop.framework.ReflectiveMethodInvocation invokeJoinpoint()Ljava/lang/Object; AutoPersistTracer "Automatic Entry Points|{classname}|{method}
  4. コピーしたディレクティブを新しいテキスト ファイルに貼り付けます。
  5. AutoPersistTracer
     を 
    FrontendMarker
     および目的のメトリック パスで置き換えます。たとえば、以下の通りです。
    TraceOneMethodOfClass: org.springframework.aop.framework.ReflectiveMethodInvocation invokeJoinpoint()Ljava/lang/Object; AutoPersistTracer "Automatic Entry Points|{classname}|{method}
    Becomes
    TraceOneMethodOfClass: org.springframework.aop.framework.ReflectiveMethodInvocation invokeJoinpoint()Ljava/lang/Object; FrontendMarker "Apps|CustomFrontend|{classname}|{method}"
  6. 新しい PBD 名、例えば
    custom_frontend.pbd
    で新しいテキスト ファイルを保存します。
  7. 新しい PBD ファイルを <
    Agent_Home
    >/wily/core/config/hotdeploy ディレクトリにコピーします。
    数分以内に、Investigator の[Frontends]ノードの下に新しいフロントエンドのメトリックが表示されます。
カスタム FrontendMarker ディレクティブ
PBD パラメータ
is.frontend.unless
は、一部のクラスがフロントエンド コンポーネントとしてマークされないように有効になります。そうでない場合、
FrontendMarker
(または
HttpServletTracer
などのサブクラス)がこれらのクラスをインスツルメントします。
is.frontend.unless
を、絶対クラス名のカンマ区切りリストとして設定します。初期コンポーネントが一般的なディスパッチャである場合、このパラメータが役立ちます。このディスパッチャは、受信した要求タイプを処理する特定のコンポーネントに要求を転送します。そのため、2 番目のコンポーネントの方がフロントエンドにより適したマーカになります。デフォルトは空のリストです。PBD パラメータは動的ではありません。
is.frontend.unless
の値を変更した後に、インスツルメントされたアプリケーション サーバを再起動します。
重要:
スペースではなくカンマでクラス名を区切ります。スペースを使用すると
SetTracerParameter
ディレクティブが無効になります。
トレーサがインスツルメントし、
is.frontend.unless
が適用される
is.frontend.unless
リストで指定されたクラスは、以下の性質を持っています。
  • フロントエンドとして指定されます。
  • Investigator の[Frontends]ノードの下にメトリックを生成しません。
たとえば、
NotAFrontend
および
AnotherNonFrontend
というクラスが、
com.ABCCorp
パッケージでフロントエンドとして扱われないようにするとします。これらのクラスは
MyFrontendTracer
という名前の
FrontendMarker
によってインスツルメントされます。以下の PBD ディレクティブを使用します。
SetTracerParameter: MyFrontendTracer 
is.frontend.unless
 com.
ABCCorp
.NotAFrontend,com.
ABCCorp
.AnotherNonFrontend
標準 PBD での Blame トレーサ
Introscope で提供されている 2 つの標準 PBD (
j2ee.pbd
および
sqlagent.pbd
)は、Boundary Blame の追跡を実装しています。
  • j2ee.pbd
    内の
    H
    ttpServletTracer は、
    FrontendMarker
    のインスタンスです。
  • sqlagent.pbd
    内の
    SQLBackendTracer
    は、
    BackendMarker
    のインスタンスです。
以前のバージョンの Introscope で使用されていた以下の
BlamePoint
トレーサは引き続き存在します。ただし、これらのトレーサは Introscope PBD ではあまり使用されません。
  • BlamedMethodTimer
  • BlamedMethodRateTracer
  • BlamedMethodTraceIncrementor
  • BlamedMethodTraceDecrementor
Boundary Blame および Oracle バックエンド
Introscope では、ソケット接続に基づいた Oracle データベースは検出されません。Oracle バックエンドを自動検出するには、Introscope で SQL エージェントを使用可能にする必要があります。
SQL エージェントがない場合に Introscope で Oracle バックエンドを検出できるようにするには、
oraclejdbc.pbd
を以下のように設定します。
o
raclejdbc.pbd
の以下の部分:
#Socket data from the Oracle driver reports too many metrics
SkipPackagePrefixForFlag: oracle.jdbc. SocketTracing
SkipPackagePrefixForFlag: oracle.net. SocketTracing
以下の例のようにスキップをコメント化します。
#Socket data from the Oracle driver reports too many metrics
#SkipPackagePrefixForFlag: oracle.jdbc. SocketTracing
#SkipPackagePrefixForFlag: oracle.net. SocketTracing