カスタム トレーサの作成

内容
apmdevops96jp
内容
カスタム PBD ファイルを作成して、メトリック コレクションを細かく設定することができます。 アプリケーション特有の情報を取得するため追跡を作成して、カスタム ディレクティブを作成するには、特定の構文およびキーワードを使用する必要があります。 カスタム追跡を作成するには、以下のことを定義する必要があります。
  • ディレクティブの タイプ(通常は、追跡するクラスまたはまたはメソッドの数を示します)
  • 追跡する特定のクラスまたはメソッド
  • クラスまたはメソッドで追跡する情報の種類(時間、レート、またはカウントなど)
  • この情報を示すメトリックの完全修飾名(リソース パスを含む)
カスタム PBD は、
<Agent_Home>
/core/config/hotdeploy ディレクトリに保存されます。 このディレクトリに追加された PBD はすべて、IntroscopeAgent.profile の
introscope.autoprobe.directivesFile
プロパティを更新または変更する必要なく実装されます。 動的 ProbeBuilding を有効にしている場合、
hotdeploy
ディレクトリ内の PBD はフォルダからそのままピックアップされます。 再起動は必要ありません。
カスタム PBD が作成されると、Introscope はこれをすぐに使える PBD として扱います。 作成したメトリックにアラートを設定して SmartStor に保存したり、Introscope Workstation でカスタム ダッシュボードを作成するときに使用したりすることができます。
注:
追跡するメソッドが多くなるとオーバーヘッドが増加するため、追跡するメソッドは慎重に選択します。
共通メトリック用のカスタム BlamePointTracer トレーサの使用
BlamePointTracer
は、最も一般的に使用されるトレーサです。 このトレーサは、関連付けられているメソッドまたはクラス用に個々に 5 つのメトリックを生成します。
  • Average Response Time (ms) (平均応答時間(ミリ秒))
  • Concurrent Invocations
  • Errors Per Interval
  • Responses per Interval
  • Stall Count (ストール数)
以下に、
BlamePointTracer
の例を示します。
BlamePointTracer
は、クラス
petshop.catalog.Catalog
search
と呼ばれるメソッド用に設定されています。
PetShop|Catalog|search
は、Introscope Investigator で BlamePoint メトリックが表示されるノードの名前です。
TraceOneMethodOfClass: petshop.catalog.Catalog search BlamePointTracer "PetShop|Catalog|search"
トレーサの構文で使用するディレクティブ名および引数
トレーサをグループに関連付けたり、グループを有効化/無効化する単純なキーワードのほかに、PBD ファイルにはトレーサの定義が含まれています。 Introscope でトレーサを認識および処理できるようにするには、カスタム トレーサを作成するときに特定の構文を使用します。 トレーサは、ディレクティブと、追跡するメソッドまたはクラスについての情報を、以下の形式で指定して構成します。
<directive>: [arguments]
ここで、
[arguments]
はディレクティブ固有のリストです。
注:
使用するディレクティブによっては、パラメータのサブセットだけが必要な場合もあります。
最も一般的に使用するディレクティブは以下の追跡ディレクティブです。
  • TraceOneMethodOfClass
    指定されたクラスの指定されたメソッドを追跡します。
  • TraceAllMethodsOfClass
    指定されたクラスのすべてのメソッドを追跡します。
  • TraceOneMethodIfInherits
    指定されたクラスのすべての直接サブクラス、または指定されたインターフェースのすべての直接インターフェース実装の特定のメソッドを追跡します。指定されたクラスまたはインターフェースは完全修飾名である必要があります。
  • TraceAllMethodsIfInherits
    指定されたクラスのすべての直接サブクラス、または指定されたインターフェースの直接実装の、コンストラクタおよび静的な初期化子を除くすべてのメソッドを追跡します。 指定されたクラスまたはインターフェースは完全修飾名である必要があります。
  • TraceOneMethodIfFlagged
    指定されたクラスが、
    TurnOn
    キーワードによって有効化されたトレーサ グループに含まれている場合、1 つのメソッドを追跡します。
  • TraceAllMethodsIfFlagged
    指定されたクラスが、
    TurnOn
    キーワードによって有効化されたトレーサ グループに含まれている場合、コンストラクタおよび静的な初期化子を除くすべてのメソッドを追跡します。
  • TraceComplexMethodsIfFlagged
    トレーサ グループ内のその他のメソッドを呼び出す、コンストラクタおよび静的な初期化子を除くすべてのパブリックまたはパッケージに表示可能な非合成メソッドを追跡します。
  • TraceAllComplexMethodsIfFlagged
    トレーサ グループ内のその他のメソッドを呼び出す、コンストラクタおよび静的な初期化子を除くすべてのメソッドを追跡します。
TraceAll* ディレクティブは、指定されたクラスのすべてのメソッドをインスツルメントします。 これらのディレクティブの使用はアプリケーションで不要なオーバーヘッドにつながる可能性があり、トランザクション追跡がデフォルトの 5,000 コンポーネント制限を超えることがあります。
TraceAllComplex* および TraceComplex* ディレクティブは、ディレクティブまたは関連するトレーサ グループで指定したクラスをインスツルメントします。
TraceOne* ディレクティブは、呼び出されるその他のメソッドのどれかではなく、指定したメソッドにのみインスツルメンテーションを適用します。
注:
具象メソッドが実装された場合のみ、追跡対象となり、実行中にメトリック データをレポートできます。 カスタム トレーサで抽象メソッドを指定しても、メトリック データはレポートされません。
トレース ディレクティブ用の構文は通常、以下の引数から構成されます。
  • <Tracer-Group>
    トレーサが関連付けられているグループ。
  • <class>
    追跡するクラスまたはインターフェースの完全修飾名。 クラスの完全修飾名には、名前だけでなくクラスの完全なアセンブリ名が含まれます。たとえば、以下のようになります。
    [MyAssembly]com.mycompany.myassembly.MyClass
    アセンブリ名は [] かっこで囲む必要があります。
  • <method>
    メソッド名(
    MyMethod
    など)
    または
    戻り値の型およびパラメータが指定された完全なメソッド シグネチャ(たとえば、
    myMethod;[mscorlib]System.Void([mscorlib]
    System.Int32)
    。 メソッド シグネチャの詳細については、「シグネチャの区別」を参照してください。
  • <Tracer-name>
    使用するトレーサのタイプを指定します。 たとえば、
    BlamePointTracer
    となります。 トレーサ名の詳細については、「一般的に使用されるトレーサ名」のセクションを参照してください。
  • <metric-name>
    収集されたデータを Introscope Workstation に表示する方法を制御します。
    以下の例は、メトリック ツリーのさまざまなレベルにあるメトリックの名前および場所を指定する方法を示します。
    metric-name
    - メトリックは エージェント ノードのすぐ内側に表示されます。
    resource:metric-name
    - メトリックは、エージェント ノード の下の 1 つのリソース(フォルダ) 内に表示されます。
    resource|sub-resource|sub-sub-resource:metric-name
    - メトリックは、エージェント ノード の 1 レベル下よりも深いリソース(フォルダ)に表示されます。 リソースを区切るには、パイプ文字(|)を使用します。
カスタム トレーサ定義での引用符の使用
カスタム トレーサにはスペースを持つメトリック名を使用できます。 カスタムのメトリック名にスペースを使用する場合に、すべてのメトリック名の前後に引用符("")を使用することをお勧めします。
重要:
クラス名の前後には引用符を使用しないでください。 引用符を使用すると、カスタム トレーサが誤動作を起こします。 たとえば、以下の通りです。
IdentifyClassAs: MyClass MyTracers
IdentifyClassAs: "MyClass" MyTracers
クラス名を含むメトリック名を作成する場合は、メトリック名全体を引用符で囲む必要があります。 メトリック名にはスペースを使用できます。また、メトリック名の中にあるすべてのスペースが引用符の中に含まれている必要があります。 たとえば、メトリック名「{classname}|Test One Node」は、以下のように表す必要があります。
TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer 
"
{classname}|Test One Node
"
TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer {classname}|Test One Node
警告:
Introscope では、クラス ファイル名が無効であるクラスを監視しません。 たとえば以下のようなクラス ファイルがある場合、
org/jboss/seam/example/seambay/AuctionImage$JaxbAccessorM_getData_setData_[B:
_[B:
によってクラス ファイル名が無効になります。 Java クラス ファイル名には開いている角かっこ([)を使用できません。 Introscope が無効なクラス名を持つクラスを見つけた場合、そのクラスのインスツルメントは失敗し、その内容はエージェント ログにエラー メッセージとしてレポートされます。
以下に、メソッド トレーサの例を示します。 以下の例では、メトリック名の前後に引用符("")が使用されています。 CA Technologies では、カスタムのメトリック名を作成するときに、すべてのメトリック名の前後を引用符で囲むことを強くお勧めしています。
一般的に使用されるトレーサ名および例
以下のリストでは、最も一般的に使用されるトレーサ名とその追跡対象を示します。
  • BlamePointTracer
    追跡対象のコンポーネントの平均応答時間、指定間隔あたりのカウント、並行処理、ストール、およびエラーを含む、標準のメトリックのセットを提供します。
  • ConcurrentInvocationCounter
    すでに開始されているが、まだ終了していないメソッドの回数をレポートします。 結果は、Investigator ツリー内のトレーサに指定されているメトリック名
    <metric-name>
    の下にレポートされます。 このトレーサの使用例としては、データベースの同時クエリ数のカウントがあります。
  • DumpStackTraceTracer
    スタックの追跡データを、その適用先のメソッドのインスツルメント済みアプリケーションの標準エラーにダンプします。 Dump Stack Tracer によってスローされた例外スタック追跡は、本当の例外ではありません。これは、メソッド スタックの追跡データを出力するためのメカニズムです。
    この機能は、メソッドの呼び出しパスを調べるときに便利です。
    重要:
    この機能を使用すると大きなシステム オーバーヘッドが発生します。 このトレーサの使用は、急激なオーバーヘッドの増加が問題にならない、診断目的時に限ることを強くお勧めします。
  • MethodCPUTimer
    メソッド実行中に使用される CPU 時間(ミリ秒単位)の平均で算出し、それをメトリック ツリーの
    <metricname>
    の下にレポートします。
    注:
    このトレーサには、サポートされるプラットフォームのプラットフォーム モニタが必要です。
  • MethodTimer
    メソッド実行時間の平均をミリ秒単位で算出し、それをメトリック ツリーのトレーサに指定されているメトリック名
    <metric-name> の下にレポ
    トします。
  • PerIntervalCounter
    間隔あたりの呼び出し数。 この間隔は、データのコンシューマ(Investigator のビュー ペインなど)の表示期間に基づいて変更されます。 これは Investigator ツリーで、トレーサに指定されているメトリック名
    <metric-name>
    の下にレポートされます。
Average トレーサの例
このトレーサは、指定したメソッドの平均実行時間(ミリ秒単位)を追跡します。
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search BlameMethodTimerHC "Petstore|Catalog|search:Average Method Invocation Time (ms)"
Rate トレーサの例
このトレーサは、1 秒あたりのメソッドの呼び出し回数をカウントし、この速度を、指定したメトリック名の下にレポートします。
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search BlamedMethodRateTracer "Petstore|Catalog|search:Method Invocations Per Second"
Per Interval Counter トレーサの例
このメソッド トレーサは、指定した間隔あたりのメソッド呼び出し回数をカウントし、そのカウントを、指定したメトリック名の下にレポートします。
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search PerIntervalCounter "Petstore|Catalog|search:Method Invocations Per Interval"
間隔は、グラフの頻度など、Enterprise Manager での監視ロジックによって決まります。
Investigator のプレビュー ペインでは、デフォルト間隔は 15 秒です。
Counter トレーサの例
このトレーサは、メソッドの呼び出し回数の合計をカウントします。
TraceOneMethodOfClass: com.sun.petstore.cart.ShoppingCart placeOrder BlamedMethodTraceIncrementor "Petstore|ShoppingCart|placeOrder:Total Order Count"
Counter トレーサの結合例
これらのトレーサは、実行時カウントを保持するために、増分および減分を行うトレーサを結合しています。
TraceOneMethodOfClass: com.sun.petstore.account.LoginEJB login MethodTraceIncrementor "Petstore|Account:Logged In Users"
TraceOneMethodOfClass: com.sun.petstore.account.LogoutEJB logout MethodTraceDecrementor "Petstore|Account:Logged In Users"
高度な単一メトリック トレーサ
ディレクティブおよびトレーサが、メソッド、クラス、およびクラス セットを追跡します。 単一メトリック トレーサでは、特定のメソッドの特定のメトリックについてレポートが実行されます。これは Introscope で追跡可能な最小の単位です。 単一メトリック トレーサは、メソッド シグネチャ、キーワードの代入、メトリック名パラメータの使用など、いくつかの方法によって作成できます。
シグネチャの区別
トレーサを、メソッド署名に基づいてメソッドに適用できます。
特定の署名を持つメソッドの単一インスタンスを追跡するには、内部メソッド記述子形式を使用して指定されたメソッド名(戻り値の型も含む)の最後に署名を付加します。
たとえば、
myMethod(Ljava/lang/String;)V
は、文字列引数および戻り値の型 void を持つメソッドのインスタンスを追跡します。
この形式に関する詳細については、「
Sun Java Virtual Machine Specification
」を参照してください。
メトリック名キーワード ベースの代入
キーワード ベースの代入では、実行時に値をメトリック名に代入できます。
トレーサ内のメトリック名のパラメータは、実行時に実際の値と置き換えられてメトリック名に代入されます。 この機能は、どのディレクティブでも使用できます。
  • {method}
    追跡されるメソッドの名前
  • {classname}
    追跡されるクラスの実行時クラス名
  • {packagename}
    追跡されるクラスの実行時パッケージ名
  • {packageandclassname}
    追跡されるクラスの実行時パッケージ名およびクラス名
注:
パッケージを持たないクラスを処理する場合、Introscope は {packagename} を文字列「<Unnamed Package>」と置き換えます。
キーワード ベースの代入: 例 1
pbd ファイル内のトレーサのメトリック名が以下であるとします。
"{packagename}|{classname}|{method}:Response Time (ms)"
また、トレーサが、パッケージ myPackage 内にある myClass の実行時クラスを持つメソッド myMethod に適用されるとします。結果のメトリック名は以下のようになります。
"myPackage|myClass|myMethod:Response Time (ms)"
キーワード ベースの代入: 例 2
.pbd ファイルに以下のメトリック名を持つトレーサがあるとします。
"{packageandclassname}|{method}:Response Time (ms)"
これが同じメソッドに適用されると、結果のメトリック名は以下のようになります。
"myPackage.myClass|myMethod:Response Time(ms)"
注:
パッケージとクラスの間には、最初の例で使用されていた | ではなく、ピリオドが使用されている点に注意してください。
メトリック名ベースのパラメータ
このフォーマットを使用し、「
TraceOneMethodWithParametersOfClass
」キーワードを使用して、メソッドに渡されたパラメータに基づいてメトリック名を作成する単一メソッド トレーサを作成できます。
TraceOneMethodWithParametersOfClass: <class-name> <method> <tracer-name> <metric-name>
パラメータをメトリック名で使用できます。 これは、メトリック名のプレースホルダ文字列をパラメータの値と置き換えることで実現できます。 使用するプレースホルダ文字列は、「{#}」です。# は、代入するパラメータのインデックスです。 インデックスのカウントはゼロから始まります。 パラメータの代入は、いくつでも、またどのような順序でも使用できます。 すべてのパラメータは、メトリック名に代入される前に文字列に変換されます。 文字列以外のオブジェクト パラメータは、toString() メソッドを使用して変換されるので、使用する際は注意が必要です。
重要:
パラメータがどんな文字列に変換されるかがはっきりしない場合は、メトリック名を使用しないでください。
パラメータに基づいたメトリック名の例
Web サイトが、「order」という名前のクラスを、「process」という名前のメソッドと共に使用します。 メソッドは、異なる種類の order のパラメータ「book」または「music」を保持します。
以下の例のようにトレーサを作成できます。
TraceOneMethodWithParametersOfClass: order process(Ljava/lang/string;)V MethodTimer "Order|{0}Order:Average Response Time (ms)"
このトレーサは、以下のようなメトリックを作成します。
Order
BookOrder
  • Average Response Time (ms) (平均応答時間(ミリ秒))
MusicOrder
  • Average Response Time (ms) (平均応答時間(ミリ秒))
また、「TraceOneMethodWithParametersIfInherits」キーワードも使用できます。
 
Skip ディレクティブ
Skip ディレクティブを使用すると、AutoProbe または ProbeBuilder によって特定のパッケージ、クラス、またはメソッドをスキップさせることができます。 デフォルトでは、Java エージェント、および基本的な Java クラスとパッケージは、AutoProbe または ProbeBuilder によってスキップされます。
注:
名前に「-」(ハイフン)文字が含まれるクラスへの参照が Skip ディレクティブに含まれている場合、クラスはスキップされず、エラーがログに表示されます。 ただしこのエラーは表面的なものであり、機能に影響はありません。
「-」はクラス名では無効な文字とされているため、クラス名にこのような文字が含まれるのは、その名前が動的に生成された場合と考えられます。
オブジェクト インスタンスのカウント
トレーサ グループ「InstanceCounts」は、それに関連付けられている特定のオブジェクトの種類のインスタンス数をカウントします。 コードに明示的に割り当てられたインスタンスは、すべてカウントされます。 また、サブタイプもカウントされます。 逆シリアル化や複製など、異なる手段で作成されたオブジェクトは、カウントされないことがあります。 カウントされる全体的なインスタンス数によっては、このトレーサ グループを使用して追跡することで、徐々にパフォーマンス(およびメモリ量)が低下する可能性があります。
InstrumentPoint ディレクティブのオン
キーワード
InstrumentPoint
は以下のタイプのディレクティブを識別します。
  • 例外を追跡するもの
  • (最初にプローブを実行したときではなく)アプリケーションの起動時にエージェントを初期化させるもの
例外
以下のディレクティブは、例外がスローまたはキャッチされた場合にその追跡をオンにするために使用されます。 これらは、パフォーマンスを低下させることがあるので、デフォルトではオンになっていません。 これらのいずれかをオンにするには、以下の該当行のコメント化を解除します。
#InstrumentPoint: ThrowException
#InstrumentPoint: CatchException
エージェントの初期化
エージェント初期化の InstrumentPoint ディレクティブでは、追加のオーバーヘッドは発生しないので、このディレクティブは、デフォルトでフルおよび標準の PBD セットの両方でオンになっています。
InstrumentPoint: AgentInitialization
複数の ProbeBuilder ディレクティブ ファイルが使用されている場合は、いずれかのファイルでオンになっている設定(トレーサ グループ、Skip、InstrumentPoint、カスタム メソッド トレーサなど)が有効になります。
カスタム トレーサの結合
同じメトリックに影響を及ぼす複数のトレーサを実質的に結合して使用できます。 結合は、増分および減分のトレーサで最もよく使用されます。
以下の例では、「
Total Purchases
」という名前のメトリックを作成します。 クラス「
cart
」、メソッド「buyBook」および「buyCD」を使用して、以下のトレーサを作成します。
TraceOneMethodOfClass cart buyBook PerIntervalCounter "Total Purchases"
TraceOneMethodOfClass cart buyCD PerIntervalCounter "Total Purchases"
誰かが商品を 1 つ買うと、「
Total Purchases
」というメトリックが 1 ずつ増加します。
Java のアノテーション
Introscope では、カスタム メトリックの作成時に Java 1.6 のアノテーションを使用できます。
  • 注:
    Java のアノテーションの詳細については、Java デベロッパー サイトのドキュメントを参照してください。
IdentifyAnnotatedClassAs を使用してクラスをトレーサ グループに配置し、次に TraceAllMethodsIfFlagged ディレクティブを使用してクラスでメソッドをインスツルメントします。 たとえば、以下の通りです。
SetFlag: AnnotationTracing TurnOn: AnnotationTracing
IdentifyAnnotatedClassAs: com.test.MyAnnotation AnnotationTracing
TraceAllMethodsIfFlagged: AnnotationTracing BlamePointTracer "Target|MyTarget|{classname}"
例では、com.test.MyAnnotation がアノテーション名になります。 独自のアノテーションを作成する場合は、コード内の用語を使用してください。 アノテーション名を含むクラスが、特定されます。