ProbeBuilder ディレクティブの操作
目次
apmdevops97jp
目次
エージェントはデフォルトで、.NET アプリケーションの多数のコンポーネントを監視します。ただし、Introscope を最大限に活用するため、少なくともアプリケーション固有のクラスおよびメソッドのいくつかはインスツルメントするのが一般的です。このセクションでは、ProbeBuilder ディレクティブ キーワードの操作およびカスタム PBD ファイルの作成について簡単に説明します。
重要:
PBD と PBL は ASCII 文字のみをサポートしています。PBD または PBL にほかの文字(Unicode 文字など)を挿入すると、問題が発生する可能性があります。既存のトレーサ グループへのクラスの追加
特定のクラスの追跡をオンにするには、そのクラスを既存のトレーサ グループに追加します。クラスをトレーサ グループの一部として識別するには、Identify キーワードのいずれかを使用します。
たとえば、クラス
System.EnterpriseServices.ServicedComponent
をトレーサ グループ ServicedComponentTracing
に追加するには、以下のように記述します。IdentifyClassAs:System.EnterpriseServices.ServicedComponentServicedComponentTracing
カスタム トレーサの作成
カスタム .pbd ファイルを作成して、メトリック コレクションをさらに細かく設定することができます。アプリケーション固有の情報を追跡するトレーサを作成してカスタム ディレクティブを作成するには、特定の構文およびキーワードを使用する必要があります。
カスタム追跡を作成するには、以下のことを定義する必要があります。
- ディレクティブのタイプ(通常は、追跡するクラスまたはメソッドの数を示します)
- 追跡する特定のクラスまたはメソッド
- クラスまたはメソッドで追跡する情報の種類(時間、速度、数など)
- この情報を示すメトリックの完全修飾名(リソース パスを含む)
作成したカスタム .pbd は、デフォルトの .pbd と同様に扱われます。作成したメトリックにアラートを設定して SmartStor に保存したり、Introscope Workstation でカスタム ダッシュボードを作成するときに使用したりすることができます。
注:
追跡するメソッドが多くなるとオーバーヘッドも大きくなるため、追跡するメソッドは慎重に選択する必要があります。一般的なカスタム追跡の例
BlamePointTracer
は、最も一般的に使用されるトレーサです。このトレーサは、関連付けられているメソッドまたはクラス用に個々に 5 つのメトリックを生成します。- Average Response Time (ms) (平均応答時間(ミリ秒))
- Concurrent Invocations (同時進行中の呼び出し)
- Errors Per Interval (間隔ごとのエラー数)
- Responses per Interval (間隔ごとの応答数)
- Stall Count (ストール数)
以下に、BlamePointTracer の例を示します。BlamePointTracer は、クラス "petshop.catalog.Catalog" で "search" と呼ばれるメソッド用に設定されています。Introscope Investigator で BlamePoint メトリックが表示されるノードの名前は「MSPetShop|Catalog|search」です。この場合、以下の記述となります。
TraceOneMethodOfClass: petshop.catalog.Catalog search BlamePointTracer "MSPetShop|Catalog|search"
トレーサ構文
トレーサをグループに関連付けたり、グループを有効化/無効化する単純なキーワードのほかに、PBD ファイルにはトレーサの定義が含まれています。Introscope でトレーサを認識および処理できるようにするには、カスタム トレーサを作成するときに特定の構文を使用する必要があります。トレーサは、ディレクティブと、追跡するメソッドまたはクラスについての情報を、以下の形式で指定して構成します。
<directive>: [arguments]
[arguments]
はディレクティブ固有のリストです。トレース ディレクィブに使用される引数には、<Tracer-Group>
、<class>
、<method>
、<Tracer-name>
、<metric-name>
があります。注:
使用するディレクティブによっては、これらのパラメータのサブセットだけが必要な場合もあります。<directive>
カスタム追跡に利用できる主なディレクティブは、以下の 6 つです。
- TraceOneMethodOfClass-- 指定されたクラスの指定されたメソッドを追跡します。
- TraceAllMethodsOfClass-- 指定されたクラスのすべてのメソッドを追跡します。
- TraceOneMethodIfInherits-- 指定されたクラスまたはインターフェースのすべての直接サブクラス、または直接インターフェースのすべての実装で、1 つのメソッドを追跡します。
- TraceAllMethodsIfInherits-- 指定されたクラスまたはインターフェースのすべての直接サブクラス、または直接インターフェースのすべての実装で、すべてのメソッドを追跡します。
注:
具象メソッドが実装された場合のみ、追跡対象となり、実行中にメトリック データをレポートできます。カスタム トレーサで抽象メソッドを指定しても、メトリック データはレポートされません。- TraceOneMethodIfFlagged-- 指定されたクラスがTurnOnキーワードによって有効化されたトレーサ グループに含まれている場合、1 つのメソッドを追跡します。
- TraceAllMethodsIfFlagged-- 指定されたクラスがTurnOnキーワードによって有効化されたトレーサ グループに含まれている場合、すべてのメソッドを追跡します。
<Tracer-Group>
トレーサが関連付けられているグループ。
<class>
追跡するクラスまたはインターフェースの完全修飾名。クラスの完全修飾名には、名前だけでなくクラスの完全なアセンブリ名が含まれます。たとえば、以下のようになります。
[MyAssembly]com.mycompany.myassembly.MyClass
注:
アセンブリ名は [] かっこで囲む必要があります。<method>
メソッド名(
MyMethod
など)または
- 戻り値の型およびパラメータが指定された完全なメソッド シグネチャ(例:myMethod;[mscorlib]System.Void([mscorlib]System.Int32))。
<Tracer-name>
使用するトレーサのタイプを指定します。たとえば、BlamePointTracer となります。トレーサ名および追跡対象の詳細については、「トレーサ名」を参照してください。
<metric-name>
収集されたデータを Introscope Workstation に表示する方法を制御します。
以下の例は、メトリック ツリーのさまざまなレベルにあるメトリックの名前および場所を指定する 3 つの方法を示します。
- metric-name-- メトリックは エージェント ノードのすぐ内側に表示されます。
- resource:metric-name-- メトリックは、エージェント ノード の下の 1 つのリソース(フォルダ) 内に表示されます。
- resource|sub-resource|sub-sub-resource:metric-name-- メトリックは、エージェント ノード の 1 レベル下よりも深いリソース(フォルダ)に表示されます。リソースを区切るには、パイプ文字(|)を使用します。
トレーサ名
以下の表は、トレーサ名およびその追跡対象項目を示しています。
BlamePointTracer
追跡対象のコンポーネントの平均応答時間、指定間隔あたりのカウント、並行処理、ストール、およびエラーを含む、標準のメトリックのセットを提供します。
ConcurrentInvocationCounter
すでに開始されているが、まだ終了していないメソッドの回数をレポートします。結果は、Investigator ツリー内のトレーサ に指定されているメトリック名の下にレポートされます。このトレーサの使用例としては、データベースの同時クエリ数のカウントがあります。
DumpStackTraceTracer
このトレーサは、スタック トレースを、その適用先のメソッドのインスツルメント済みアプリケーションの標準エラーにダンプします。Dump Stack Tracer によってスローされた例外スタック トレースは、本当の例外ではありません。これは、メソッドのスタック トレースを出力するためのメカニズムです。
この機能は、メソッドの呼び出しパスを調べるときに便利です。
重要:
この機能を使用すると大きなシステム オーバーヘッドが発生します。このトレーサの使用は、急激なオーバーヘッドの増加が問題にならない、診断目的時に限ることを強くお勧めします。MethodTimer
メソッド実行時間の平均をミリ秒単位で算出し、メトリック ツリーのトレーサ
<metric-name>
に指定されているメトリック名 の下にレポートします。PerIntervalCounter
間隔あたりの呼び出し数。この間隔は、データのコンシューマ(Investigator のビュー ペインなど)の表示期間に基づいて変更されます。これは Investigator ツリーで、トレーサ
<metric-name>
に指定されているメトリック名 の下にレポートされます。カスタム メソッド トレーサの例
カスタム トレーサにはスペースを持つメトリック名を使用できます。カスタムのメトリック名にスペースを使用する場合に、すべてのメトリック名の前後に引用符("")を使用することをお勧めします。
重要:
クラス
名の前後には引用符を使用しないでください。引用符を使用すると、カスタム トレーサが誤動作を起こします。たとえば、以下のように追加します。- 正IdentifyClassAs: My.Name.Space.MyClass MyTracers
- 誤IdentifyClassAs: "My.Name.Space.MyClass" MyTracers
クラス名を含むメトリック名を作成する場合は、メトリック名全体を引用符で囲む必要があります。メトリック名にはスペースを使用できます。また、メトリック名の中にあるすべてのスペースが引用符の中に含まれている必要があります。たとえば、「{classname}|Test One Node」というメトリック名は以下のように記述します。
- 正TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer "{classname}|Test One Node"
- 誤TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer {classname}|Test One Node
以下に、メソッド トレーサの例を示します。以下の例では、メトリック名の前後に引用符("")が使用されています。CA Technologies では、カスタムのメトリック名を作成するときに、すべてのメトリック名の前後を引用符で囲むことを強くお勧めしています。
Average トレーサの例
このトレーサは、指定したメソッドの平均実行時間(ミリ秒単位)を追跡します。
TraceOneMethodOfClass: petshop.catalog.Catalog search BlamedMethodTimer "MSPetShop|Catalog|search:Average Method Invocation Time (ms)"
Rate トレーサの例
このトレーサは、1 秒あたりのメソッドの呼び出し回数をカウントし、この速度を、指定したメトリック名の下にレポートします。
TraceOneMethodOfClass: petshop.catalog.Catalog search BlamedMethodRateTracer "MSPetShop|Catalog|search:Method Invocations Per Second"
Per Interval Counter トレーサの例
このメソッド トレーサは、指定した間隔あたりのメソッド呼び出し回数をカウントし、そのカウントを、指定したメトリック名の下にレポートします。
TraceOneMethodOfClass: petshop.catalog.Catalog search PerIntervalCounter "MSPetShop|Catalog|search:Method Invocations Per Interval"
間隔は、グラフの頻度など、Enterprise Manager での監視ロジックによって決まります。
Introscope Investigator のプレビュー ペインでは、デフォルトの間隔は 15 秒です。
Counter トレーサの例
このトレーサは、メソッドの呼び出し回数の合計をカウントします。
TraceOneMethodOfClass: petshop.cart.ShoppingCart placeOrder BlamedMethodTraceIncrementor "MSPetShop|ShoppingCart|placeOrder:Total Order Count"
Counter トレーサの結合例
これらのトレーサは、実行時カウントを保持するために、増分および減分を行うトレーサと結合しています。
TraceOneMethodOfClass: petshop.account.LoginComponent login MethodTraceIncrementor "MSPetShop|Account:Logged In Users"TraceOneMethodOfClass: petshop.account.LogoutComponent logout MethodTraceDecrementor "MSPetShop |Account:Logged In Users"
高度なカスタム トレーサの作成
以下のセクションでは、単一メトリック トレーサ、Skip、およびカスタム トレーサの結合など、高度なカスタム トレーサの作成について説明します。
高度な単一メトリック トレーサ
ディレクティブおよびトレーサが、メソッド、クラス、およびクラス セットを追跡します。単一メトリック トレーサでは、特定のメソッドの特定のメトリックについてレポートが実行されます。これは Introscope で追跡可能な最小の単位です。単一メトリック トレーサは、メソッド シグネチャ、キーワードの代入、メトリック名パラメータの使用など、いくつかの方法によって作成できます。
シグネチャの区別
トレーサを、メソッド署名に基づいてメソッドに適用できます。
特定の署名を持つメソッドの単一インスタンスを追跡するには、内部メソッド記述子形式を使用して指定されたメソッド名(戻り値の型も含む)の最後に署名を付加します。
たとえば、myMethod;[mscorlib]System.Void([mscorlib]System.Int32) は、
int
引数および戻り値の型 void
を持つメソッドのインスタンスを追跡します。メトリック名キーワード ベースの代入
キーワード ベースの代入では、実行時に値をメトリック名に代入できます。
トレーサ内のメトリック名のパラメータは、実行時に実際の値と置き換えられてメトリック名に代入されます。この機能は、どのディレクティブでも使用できます。以下の表は、パラメータおよびそれらの実行時の代入の一覧です。
パラメータ | 実行時の代入 |
{method} | 追跡されるメソッドの名前 |
{classname} | 追跡されるクラスの実行時クラス名 |
{namespacename} | 追跡されるクラスの実行時ネームスペース名 |
{namespaceandclassname} | 追跡されるクラスの実行時ネームスペース名およびクラス名 |
{assemblyname} | 追跡されるアセンブリの名前 |
{fullclassname} | アセンブリ名を含む完全なクラス名をレポートする |
注:
Introscope では、ネームスペース
を持たないクラスの処理では、{namespacename}
が「<Unnamed Namespace>
」という文字列に置き換えられます。キーワード ベースの代入: 例 1
.pbd ファイル内のトレーサのメトリック名が以下であるとします。
"{namespacename}|{classname}|{method}:Response Time (ms)"
また、トレーサが、myNamespace 内にある myClass の実行時クラスを持つメソッド
myMethod
に適用され場合、結果のメトリック名は以下のようになります。"myNamespace|myClass|myMethod:Response Time (ms)"
キーワード ベースの代入: 例 2
.pbd ファイルに以下のメトリック名を持つトレーサがあるとします。
"{namespaceandclassname}|{method}:Response Time (ms)"
これが例 1 と同じメソッドに適用されると、結果のメトリック名は以下のようになります。
"myNamespace.myClass|myMethod:Response Time(ms)"
注:
この例では、namespace
と class
の間に、例 1 の | (パイプ記号)ではなく、.(ピリオド)が 使用されています。メトリック名ベースのパラメータ
メトリック名を作成する単一メソッド トレーサを作成できます。このメトリック名は、以下の形式を使用した、TraceOneMethodWithParametersofClass キーワードを使用してメソッドに渡されるパラメータに基づいています。
TraceOneMethodWithParametersOfClass: <class> <method> <Tracer-name> <metric-name>
パラメータをメトリック名で使用できます。メトリック名のプレースホルダ文字列をパラメータの値と置き換えます。プレースホルダには文字列「{#}」を使用します。# は、代入するパラメータのインデックスです。インデックスのカウントはゼロから始まります。パラメータの代入は、いくつでも、またどのような順序でも使用できます。すべてのパラメータは、メトリック名に代入される前に文字列に変換されます。文字列以外のオブジェクト パラメータは、toString() メソッドを使用して変換されるので、使用する際は注意が必要です。
重要:
パラメータがどのような文字列に変換されるかがはっきりしない場合は、そのパラメータをメトリック名で使用しないでください。パラメータの例に基づいたメトリック名
Web サイトが「
order
」という名前のクラスを、「process
」という名前のメソッドと共に使用します。メソッドは、異なる種類の order のパラメータ「book
」または「music
」のいずれかを持ちます。この場合、以下のようなトレーサを作成できます。
TraceOneMethodWithParametersOfClass: order process; [mscorlib]System.Void([mscorlib]System.Int32) MethodTimer "Order|{0}Order:Average Response Time (ms)"
このトレーサは、以下のようなメトリックを作成します。
OrderBookOrderAverage Response Time (ms)MusicOrderAverage Response Time (ms)
また、「
TraceOneMethodWithParametersIfInherits
」キーワードも使用できます。Skip ディレクティブ
Skip ディレクティブを使用することで、特定のパッケージ、クラス、またはメソッドをインスツルメントしないようにすることができます。Skip ディレクティブを使用すると、ProbeBuilder ではネームスペース、クラス、またはアセンブリがスキップされます。
さらに、条件に一致する範囲を小さくすることにより、インスツルメントされるパッケージ、クラス、またはメソッドの量を制限することもできます。そのためには、IdentifyAllClassAs や TraceAllMethodsIfFlagged ディレクティブを、より範囲の狭いものに置き換えます。
注:
名前に「-」(ハイフン)文字が含まれるクラスへの参照が Skip ディレクティブに含まれている場合、クラスはスキップされず、エラーがログに表示されます。ただしこのエラーは表面的なものであり、機能に影響はありません。「-」はクラス名では無効な文字とされているため、クラス名にこのような文字が含まれるのは、その名前が動的に生成された場合と考えられます。
カスタム トレーサの結合
同じメトリックに影響を及ぼす複数のトレーサを実質的に結合して使用できます。結合は、増分および減分のトレーサで最もよく使用されます。
以下の例は、「
Logged-in Users
」という名前のメトリックを作成します。クラス「user
」、メソッド「login
」および「logout
」を使用して、以下のトレーサを作成します。TraceOneMethodOfClass user login MethodTraceIncrementor "Logged-in Users"TraceOneMethodOfClass user logout MethodTraceDecrementor "Logged-in Users"
これは、任意のユーザがログインしたときにメトリック「Logged-in Users」を増分し、ログアウトしたときに「Logged-in
Users
」を減分します。特定のトレーサに関する注意事項
以下の識別子とトレーサは、.NET 環境に特有の動作をします。
- IdentifyAnnotatedClassAs: <attribute-class-name> <Tracer-group>指定の属性クラスの注釈が付けられたクラスをすべて指定のトレーサ グループに関連付けます。一部のクラスには、属性クラスの注釈を付けてクラスに追加機能を持たせることができます。以下の例では、System.EnterpriseServices.Transactionという属性クラスがクラスServicedComponentに添付されています。[Transaction]Public class ServicedComponent {}.pbd ファイルでは以下のように記述します。IdentifyAnnotatedClassAs: System.EnterpriseServices.Transaction MyTracerGroupこれにより、[Transaction]の注釈があるクラスがすべて、ServicedComponentも含め、識別されます。
注:
この識別子を使用した場合、Introscope .NET エージェントでは継承された属性は追跡されませんが、ベース クラスに適用された属性は追跡されます。- TraceAnnotatedMethodsIfFlagged: <Tracer-group> <attribute-class-name> <Tracer-name> <metric-name>指定のトレーサ グループに関連付けられているクラスについて、指定のクラスにより注釈を付けられているメソッドをすべて追跡します。
明示的なインターフェースの実装
.NET エージェントでは、.pbd ファイルによる明示的なインターフェースの実装が使用されます。あるクラスのメソッドを追跡する場合に、そのメソッド名が、他のクラスで使用される他のメソッドと同じ場合は、追跡するメソッドとそのメソッドが所属するインターフェースを明示的に指定する必要があります。たとえば、InterfaceA と InterfaceB の両方に MethodX というメソッドがある場合、InterfaceA の MethodX を呼び出すには、InterfaceA.MethodX のようにインターフェースとメソッドの両方を指定する必要があります。
以下に、明示的なインターフェースの実装を使用して、あるクラスのメソッドを追跡する例を示します。
SetFlag: customInterfaceTracingTurnOn: customInterfaceTracingIdentifyInheritedAs: EdgeCaseInterface customInterfaceTracingTraceOneMethodIfFlagged: customInterfaceTracing EdgeCaseInterface.method2 BlamePointTracer "Interface|{namespaceandclassname}|{method}"
インスツルメントおよび継承
Introscope では、クラス階層の下位レベルのクラスは自動的にはインスツルメントされません。たとえば、ClassB が ClassA を拡張し、ClassC が ClassB を拡張する、以下のようなクラス階層があるとします。
Interface\ClassAClassBClassC
ClassA をインスツルメントすると、ClassA を明示的に拡張する ClassB もインスツルメントされます。しかし、ClassC はインスツルメントされません。これは、ClassC が ClassA を明示的に拡張しないためです。ClassC をインスツルメントするには、明示的に ClassC を特定する必要があります。
ProbeBuilder ディレクティブの適用
ProbeBuilder ディレクティブ ファイルを実装する準備が整った段階で、新しいファイルを実装する方法として以下の 3 つがあります。
hotdeploy ディレクトリの使用
hotdeploy
ディレクトリを使用すると、Introscope の管理者は、IntroscopeAgent.profile
を編集することなく、また場合によってはアプリケーションを再起動することもなく、新しいディレクティブをより迅速かつ簡単にデプロイできます。この機能を使用する場合は注意が必要です。カスタム PBD に無効な構文が含まれていたり、非常に多くのメトリックを収集するよう設定されていたりすると、即座に影響を及ぼします。PBD が無効である場合は NativeProfiler のシャットオフを引き起こす可能性があります。また、非常に多くのメトリックを収集する PBD はアプリケーションのパフォーマンスに影響を与えます。これを解決するため、以下をお勧めします。- 実運用環境に導入する前に、すべてのディレクティブを QA 環境およびパフォーマンス環境でテストおよび検証する。
- PBD をデプロイするため、サーバ環境の変更管理プロセスが更新されており、新しいオプションが反映されていることを確認する。
新しい PBD が hotdeploy ディレクトリに格納されると、.NET エージェントによって自動的にこの新しい PBD がデプロイされます。ただし、アプリケーションが再起動されるまでは、すでに実行されているクラスおよびアプリケーションに新しい PBD または変更された PBD の影響が及ぶことはありません。新しい PBD がこのディレクトリに格納されていれば、IntroscopeAgent.profile を編集して新しい PBD または変更された PBD を指定する必要はありません。
hotdeploy ディレクトリを使用して .pbd を適用する方法
- カスタム ファイルまたは変更したファイル(.pbdsおよび .pbls)を<Agent_Home>\hotdeployディレクトリにコピーします。
<
Agent_Home
> ディレクトリの使用新しいまたは変更した PBD と PBL をデプロイするには、該当するファイルを、introscope.autoprobe.directivesFile プロパティ内に追加し、IntroscopeAgent.profile ファイルと同じディレクトリまたは IntroscopeAgent.profile ファイルの場所を起点とする相対ディレクトリに配置する必要があります。
その他のディレクトリにファイルを配置する場合は、introscope.autoprobe.directivesFile プロパティを設定するときにファイルのフル パスを指定する必要があります。
新しいまたは変更された .pbd および .pbl ファイルをデプロイする方法
- カスタムまたは変更したファイル(PBDおよび PBL)を<Agent_Home>ディレクトリにコピーします。
- IntroscopeAgent.profile ファイルの introscope.autoprobe.directivesFile プロパティを更新して、新しいファイルの名前をカンマで区切って追加します。たとえば、カスタムの petstore.pbd ファイルをプロパティに追加します。introscope.autoprobe.directivesFile=default-full.pbl,petstore.pbd,hotdeploy
- IntroscopeAgent.profile を保存して閉じます。
- アプリケーションまたは IIS サービスを再起動します。
注
: 既存の .pbl
または .pbd
ファイルによって制御される監視を無効にする場合を除き、プロパティで定義された既存の .pbl または .pbd ファイルは削除しないでください。カスタムの場所とアクセス権
hotdeploy ディレクトリまたは
<Agent_Home>
ディレクトリを使用する方法に加えて、任意の場所を選択して PBD を配置することもできます。.pbd ファイルをカスタムの場所に置く場合は、IntrosocopeAgent.profile で .pbd ファイルの場所を指定する必要があります。たとえば、leakhunter.pbd を C: ドライブのカスタムの場所に配置した場合は、introscope.autoprobe.directivesFile プロパティを以下のように更新します。
introscope.autoprobe.directivesFile=default-full.pbl,C:\\sw\\leakhunter.pbd
.pbd をカスタムの場所に置く場合は、IIS プロセスを開始するユーザに、そのカスタムの場所(上記の例では
C:\\sw
)に対する適切な権限が付与されている必要があります。IIS プロセスを開始するユーザに、この場所に対する権限が付与されていない場合、デフォルト ドメインのログにエラー メッセージが記録され、カスタムの場所にある .pbd は有効になりません。重要:
CA Technologies では、PBD を hotdeploy ディレクトリに置くことを強くお勧めします。トランザクション追跡および動的インスツルメンテーション
Introscope Workstation からトランザクション追跡をするときは、動的インスツルメンテーションを実行するオプションがあります。動的インスツルメンテーションでは、PBD ファイルを作成したり、エージェント プロファイルを変更したりせずに、実行時にインスツルメントする 1 つ以上のメソッドを選択できます。動的インスツルメンテーションでは、以下を実行できます。
- トランザクション コンポーネントに属する、1 つ、複数、またはすべての呼び出されたメソッドを表示およびインスツルメントする。
- 一時的にインスツルメントされたメソッドでの追跡を表示する。
- 一時的にインスツルメントされたメソッドで収集されたメトリックを表示する。
- 一時的なインスツルメンテーションを永続化する。
動的インスツルメンテーションは、CPU への負荷が高い操作です。CA Technologies は、インスツルメントされるクラスを最小限にする設定を使用することを強くお勧めします。
注:
.NET オペレーティング環境のサポートは制限されています。詳細については、「CA APM Workstation ユーザ ガイド」の「トランザクション追跡」を参照してください。