カスタム トレーサの作成

カスタム PBD ファイルを作成して、メトリック コレクションを細かく設定することができます。アプリケーション固有の測定を追跡するトレーサを作成して、カスタム ディレクティブを作成するには、特定の構文およびキーワードを使用する必要があります。
apmsaas
カスタム PBD ファイルを作成して、メトリック コレクションを細かく設定することができます。アプリケーション固有の測定を追跡するトレーサを作成して、カスタム ディレクティブを作成するには、特定の構文およびキーワードを使用する必要があります。
2
2
カスタム追跡を作成するには、以下のことを定義する必要があります。
  • ディレクティブ タイプ(通常は、追跡するクラスまたはメソッドの数を示します)
  • 追跡する特定のクラスまたはメソッド。
  • 1 つまたは複数のクラスまたはメソッドで追跡する情報のタイプ(たとえば、時間、レート、または数)
  • この情報を示すメトリックの完全修飾名(リソース パスを含む)
カスタム PBD は、
<Agent_Home>\releases\<release_number>\core\config\hotdeploy
ディレクトリに格納されます。このディレクトリに追加された PBD はすべて、IntroscopeAgent.profile の
introscope.autoprobe.directivesFile
プロパティを更新または変更する必要なく実装されます。動的 ProbeBuilding を有効にしている場合、hotdeploy ディレクトリ内の PBD はフォルダからそのままピックアップされます。再起動は必要ありません。
カスタム PBD が作成されると、Java エージェントはこれを標準装備の PBD として扱います。作成されたメトリックのアラートを設定したり、メトリックを使用してカスタム ダッシュボードを作成したりすることができます。
追跡するメソッドが多くなるとオーバーヘッドが増加するため、追跡するメソッドは慎重に選択してください。
一般的なメトリックでのカスタム BlamePoint トレーサの使用
BlamePoint トレーサ
は、最も一般的に使用されるトレーサです。このトレーサは、関連付けられているメソッドまたはクラス用に個々に 5 つのメトリックを生成します。
  • Average Response Time (ms)
  • 同時進行中の呼び出し
  • Errors Per Interval[Errors Per Interval]
  • Responses Per Interval
  • ストール数
BlamePoint トレーサの例を以下に示します。BlamePoint トレーサは、
petshop.catalog.Catalog
クラスの
searc
h
と呼ばれるメソッド用に設定されます。BlamePoint メトリックは、メトリック ブラウザ ツリーの PetShop|Catalog|search ノードの下に表示されます。
TraceOneMethodOfClass: petshop.catalog.Catalog search BlamePointTracer "PetShop|Catalog|search"
トレーサ構文で使用されるディレクティブ名および引数
PBD ファイルには、トレーサをグループに関連付けたり、グループを有効化および無効化したりする単純なキーワードが含まれます。PBD ファイルにはトレーサの定義も含まれます。カスタム トレーサには、Java エージェントがトレーサを認識して処理できるようにする特定の構文が必要です。
Tracer は、ディレクティブと、追跡するメソッドまたはクラスについての情報を、以下の形式で指定して構成します。
<directive>: [arguments]
ここで、
[arguments]
はディレクティブ固有のリストです。
使用するディレクティブによっては、パラメータのサブセットのみを必要とします。
最も一般的に使用するディレクティブは以下の追跡ディレクティブです。
  • TraceOneMethodOfClass
    このディレクティブは指定クラスの指定メソッドを追跡します。
  • TraceAllMethodsOfClass
    このディレクティブは、指定クラス内のすべてのメソッドを追跡します。
  • TraceOneMethodIfInherits
    このディレクティブは、以下の 2 つの場合に特定のメソッドを追跡します。
    • 指定クラスのすべての直接サブクラス内
    • 指定インターフェースのすべての直接インタ フェース実装内
    指定されたクラスまたはインターフェースは完全修飾名である必要があります。
  • 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>
    このディレクティブは、使用されるトレーサのタイプを指定します。たとえば、BlamePoint トレーサです。
    詳細: 一般的に使用されるトレーサ名
  • <metric-name>
    収集されたデータをユーザ インターフェースに表示する方法を制御します。
    以下の例は、メトリック ツリーのさまざまなレベルにあるメトリックの名前および場所を指定する方法を示します。
    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
エージェントは、クラス ファイル名が無効であるクラスを監視しません。
クラス ファイル名が無効なクラスの例
クラス ファイル名
org/jboss/seam/example/seambay/AuctionImage$JaxbAccessorM_getData_setData_[B:
_[B:
によってクラス ファイル名が無効になります。開いている角かっこ
[
を Java クラス ファイル名に使用することはできません。Java エージェントが無効なクラス名を持つクラスを見つけると、そのクラスのインスツルメントは失敗します。また、Java エージェントは、無効なクラス名をエージェント ログ内のエラー メッセージとしてレポートします。
以下に、メソッド トレーサの例を示します。以下の例では、メトリック名の前後に引用符("")が使用されています。カスタム メトリック名を作成するときに、すべてのメトリック名を引用符で囲むことを強くお勧めします。
一般的に使用されるトレーサ名および例
以下のリストでは、最も一般的に使用されるトレーサ名とその追跡対象を示します。
  • BlamePointTracer
    このトレーサ名は、平均応答時間、間隔ごとの数、同時進行中の数、ストールの数、エラーの数など、blamed コンポーネントの標準メトリック セットを提供します。
  • ConcurrentInvocationCounter
    このトレーサ名は、メソッドがすでに開始されているが、まだ終了していない回数をレポートします。結果は、Investigator ツリー内のトレーサに指定されているメトリック名
    <metric-name>
    の下にレポートされます。このトレーサの使用例としては、データベースの同時クエリ数のカウントがあります。
  • DumpStackTraceTracer
    このトレーサ名は、適用先メソッドのインスツルメント済みアプリケーションの標準エラーにスタック トレースをダンプします。Dump Stack Tracer によってスローされた例外スタック トレースは、本当の例外ではありません。この例外スタック トレースは、メソッド スタック トレースを出力するためのメカニズムです。
    この機能は、メソッドへのコール パスを見つけるのに役立ちます。
    ただし、この機能では、大きなシステム オーバーヘッドが発生します。このトレーサを使用するのは、急激なオーバーヘッドの増加が許容される診断のコンテキストに限ることをお勧めします。
  • MethodCPUTimer
    メソッド実行中に使用される CPU 時間(ミリ秒単位)の平均で算出し、それをメトリック ツリーの
    <metricname>
    の下にレポートします。
    注:
    このトレーサには、サポートされるプラットフォームのプラットフォーム モニタが必要です。
  • MethodTimer
    メソッド実行の平均時間をミリ秒単位で算出し、メトリック ツリーのトレーサに指定されているメトリック名、
    <metric-name>
    の下にレポートします。
  • PerIntervalCounter
    間隔あたりの呼び出し数。この間隔は、データのコンシューマ(Investigator の[ビュー]ペインなど)の表示期間に基づいて変更されます。PerIntervalCounter は、メトリック ブラウザ ツリーのトレーサで指定されたメトリック名、
    <metric-name>
    の下にレポートされます。
Average トレーサの例
この Tracer は、指定したメソッドの平均実行時間(ミリ秒単位)を追跡します。
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search BlameMethodTimerHC "Petstore|Catalog|search:Average Method Invocation Time (ms)"
Rate トレーサの例
この Tracer は、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"
高度な単一メトリック トレーサ
ディレクティブおよび Tracer が、メソッド、クラス、およびクラス セットを追跡します。単一メトリック トレーサでは、特定のメソッドの特定のメトリックがレポートされます。これは Java エージェントで追跡可能な最小の単位です。単一メトリック Tracer は、メソッド シグネチャ、キーワードの代入、メトリック名パラメータの使用など、いくつかの方法によって作成できます。
シグネチャの区別
メソッド シグネチャに基づいてトレーサをメソッドに適用できます。
特定のシグネチャを持つメソッドの単一インスタンスを追跡するには、メソッド名の末尾にシグネジャを付加します。内部メソッド記述子形式を使用して指定した戻り値の型を含めます。
たとえば、
myMethod(Ljava/lang/String;)V
は、文字列引数および戻り値の型 void を持つメソッドのインスタンスを追跡します。
この形式に関する詳細については、「
Sun Java Virtual Machine Specification
」を参照してください。
メトリック名キーワード ベースの代入
キーワード ベースの代入では、実行時に値をメトリック名に代入できます。
Tracer 内のメトリック名のパラメータは、実行時に実際の値と置き換えられてメトリック名に代入されます。この機能は、どのディレクティブでも使用できます。
  • {method}
    追跡されるメソッドの名前
  • {classname}
    追跡されるクラスの実行時クラス名
  • {packagename}
    追跡されるクラスの実行時パッケージ名
  • {packageandclassname}
    追跡されるクラスの実行時パッケージ名およびクラス名
Java エージェントでパッケージのないクラスが処理されると、
{packagename}
に置き換えられます。
"<Unnamed Package>"
に変更を加えないでください。
キーワード ベースの代入: 例 1
.pbd ファイルに以下のメトリック名を持つトレーサがあります。
{packagename}|{classname}|{method}:Response Time (ms)
Tracer が、パッケージ
myPackage
内にある
myClass
の実行時クラスを持つメソッド
myMethod
に適用されるとします。
結果のメトリック名は以下のとおりです。
myPackage|myClass|myMethod:Response Time (ms)
キーワード ベースの代入: 例 2
.pbd ファイルに以下のメトリック名を持つトレーサがあります。
{packageandclassname}|{method}:Response Time (ms)
このトレーサは同じ (
myMethod)
メソッドに適用されます。
結果のメトリック名は以下のとおりです。
myPackage.myClass|myMethod:Response Time(ms)
例 1 と 2 での結果のメトリック名の相違点に注意してください。例 1 では、パイプ記号 | が
myPackage
myClass
を区切っています。例 2 では、終止符記号「
.
」が
myPackage
myClass
を区切っています。
メトリック名ベースのパラメータ
単一メソッド トレーサは、メソッドに渡されたパラメータに基づいてメトリック名を作成できます。このような場合には、以下の形式を使用してメトリック名を作成します。
TraceOneMethodWithParametersOfClass: <クラス名> <メソッド> <Tracer 名> <メトリック名>
Java エージェントでは、
TraceOneMethodWithParametersOfClass
キーワードを使用して、パラメータがメソッドに渡されます。
メトリック名のプレースホルダ文字列のパラメータ値を置き換えることによって、メトリック名にパラメータを使用できます。使用するプレースホルダ文字列は番号記号 {
#
} です。ここでの # は、代入するパラメータのインデックスです。インデックスのカウントはゼロから始まります。パラメータの代入は、いくつでも、またどのような順序でも使用できます。すべてのパラメータは、メトリック名に代入される前に文字列に変換されます。文字列以外のオブジェクト パラメータは、
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 Agent、および基本的な Java クラスとパッケージは、AutoProbe または ProbeBuilder によってスキップされます。
名前に
-
(ハイフン)文字を含むクラスへの参照が skip ディレクティブに含まれている場合は、それらのクラスはスキップされません。表面的なエラーがログに表示されます。機能への影響はありません。
クラス名の
-
(ハイフン)文字は不正であると見なされます。動的に生成されたクラス名にはにハイフンが含まれる可能性があります。
オブジェクト インスタンスのカウント
トレーサ グループ「
InstanceCounts
」は、それに関連付けられている特定のオブジェクトの種類のインスタンス数をカウントします。コードに明示的に割り当てられたインスタンスがカウントされます。サブタイプもカウントされます。シリアル化解除や複製など、異なる手段で作成されたオブジェクトは、カウントされないことがあります。カウントされる全体的なインスタンス数によっては、このトレーサ グループを使用して追跡することで、徐々にパフォーマンス(およびメモリ量)が低下する可能性があります。
InstrumentPoint ディレクティブのオン
キーワード
InstrumentPoint
は以下のタイプのディレクティブを識別します。
  • 例外を追跡するディレクティブ
  • (最初にプローブを実行したときではなく)アプリケーションの起動時にエージェントを初期化させるディレクティブ
例外
以下のディレクティブは、例外がスローまたはキャッチされた場合にその追跡をオンにするために使用されます。これらのディレクティブは、パフォーマンスを低下させることがあるので、デフォルトではオフになっています。これらのいずれかのディレクティブをオンにするには、適切な行のコメント化を解除します。
#InstrumentPoint: ThrowException
#InstrumentPoint: CatchException
エージェントの初期化
エージェント初期化の InstrumentPoint ディレクティブでは、追加のオーバーヘッドは発生しないので、このディレクティブは、デフォルトでフルおよび標準の PBD セットの両方でオンになっています。
InstrumentPoint: AgentInitialization
複数の ProbeBuilder ディレクティブ ファイルを使用する場合は、任意のファイルでオンに指定された任意の設定が有効になります。設定の例は、トレーサ グループ、skip、instrumentPoint ディレクティブ、およびカスタム メソッド追跡です。
カスタム Tracer の結合
同じメトリックに影響を及ぼす複数の Tracer を実質的に結合して使用できます。複数はトレーサは、増分および減分のトレーサで最もよく使用されます。
以下の例では、「Total Purchases」という名前のメトリックを作成します。以下のトレーサを作成するには、
cart
クラスと
buyBook
および
buyCD
メソッドを使用します。
TraceOneMethodOfClass cart buyBook PerIntervalCounter "Total Purchases"
TraceOneMethodOfClass cart buyCD PerIntervalCounter "Total Purchases"
複数のトレーサのこの使用方法では、誰かが 1 つの商品購入すると、Total Purchases メトリックが増加します。
Java のアノテーション
Java エージェントでは、カスタム メトリックの作成時に Java 1.6 のアノテーションを使用できます。
詳細
: Java アノテーションについては、Java 開発者向けの Web サイトを参照してください。
Variable not found を使用して、
IdentifyAnnotatedClassAs
クラスを Tracer グループに配置してから、
TraceAllMethodsIfFlagged
ディレクティブを使用してクラス内でメソッドをインスツルメントします。例:
SetFlag: AnnotationTracing TurnOn: AnnotationTracing
IdentifyAnnotatedClassAs: com.test.MyAnnotation AnnotationTracing
TraceAllMethodsIfFlagged: AnnotationTracing BlamePointTracer "Target|MyTarget|{classname}"
例では、
com.test.MyAnnotation
がアノテーション名になります。独自のアノテーションを作成する場合は、コード内の用語を使用してください。アノテーション名を含むクラスが、特定されます。
アプリケーションで生成される相関 ID トレーサ
com.wily.Java Agent.agent.trace.correlation.custom.ApplicationCorrelationIDTracer
は Java エージェントでのみサポートされています。
トレーサは、トランザクション追跡の相関キー プロパティとして、アプリケーションで生成された ID を取得します。この生成された ID は、戻り値か、またはアプリケーション メソッドの引数から取得されます。相関 ID の値は、取得されたオブジェクトの
Object.toString()
です。Enterprise Manager は、相関のためにトランザクション追跡に追加される相関キーを自動的に使用します。
このトレーサは、以下の 2 つのパラメータを使用する BlamePoint トレーサです。
  • argumentPosition
    取得される引数のゼロから始まるインデックスの位置。負の値は、メソッドの戻り値がキャプチャされたことを示します。
    デフォルト:
    -1
  • correlationKey
    トランザクション追跡でアプリケーション ID プロパティ名として使用できるオプションの文字列値。この文字列は、トレーサにはまったく影響しません。代わりに、この文字列は参照用として UI に表示されます。
    デフォルト:
    ApplicationCorrelationId
例: 変動するキャプチャ値
SetFlag: PollingTask
TurnOn: PollingTask
IdentifyClassAs: com.ca.sample.election.poll.PollingTask PollingTask
SetFlag: RegisterTask
TurnOn: RegisterTask
IdentifyClassAs: com.ca.sample.election.register.RegisterTask RegisterTask
##################
# Capture from return value
##################
SetTracerClassMapping: ApplicationCorrelationIDRetTracer com.wily.introscope.agent.trace.correlation.custom.ApplicationCorrelationIDTracer com.wily.introscope.probebuilder.validate.ResourceNameValidator
SetTracerParameter: ApplicationCorrelationIDRetTracer argumentPosition -1
SetTracerParameter: ApplicationCorrelationIDRetTracer correlationKey CitizenId
TraceOneMethodWithParametersIfFlagged: PollingTask submitVote(Lcom/ca/sample/dto/Vote;)Ljava/util/UUID; ApplicationCorrelationIDRetTracer "corid|count"
################
# Capture argument at position 0
################
SetTracerClassMapping: ApplicationCorrelationIDArgTracer com.wily.introscope.agent.trace.correlation.custom.ApplicationCorrelationIDTracer com.wily.introscope.probebuilder.validate.ResourceNameValidator
SetTracerParameter: ApplicationCorrelationIDArgTracer argumentPosition 0
SetTracerParameter: ApplicationCorrelationIDArgTracer correlationKey CitizenId
SetTracerParameter: ApplicationCorrelationIDArgTracer generatetransactionelement false
TraceOneMethodWithParametersIfFlagged: RegisterTask registerCitizen(Ljava/util/UUID;Lcom/ca/sample/dto/Citizen;)V ApplicationCorrelationIDArgTracer "corid|cast"