EPAgent カスタム プラグイン インターフェース定義
シンプル形式または XML 形式を使用して、EPAgent カスタム プラグイン用のメトリック解析インターフェースを定義できます。
apmsaas
スタンドアロン EPAgent はダウンロードできなくなりました。また、この機能は、DX APM SaaS および DX APM オンプレミス(20.x 以降)で APM インフラストラクチャ エージェントの EPAgent 拡張機能を使用してサポートされるようになりました。実装の詳細は、こちらを参照してください。ただし、既存のユーザは、ここで説明する手順を使用して、レガシー スタンドアロン EPAgent を DX APM SaaS または DX APM オンプレミス(20.x 以降)に接続できます。詳細については、「スタンドアロン EPAgent のインストールおよび設定」と「クラウド プロキシ」を参照してください。
2
2
メトリック データ形式
EPAgent プラグインでは、2 つのソースによって提供されるメトリック データを解析できます。ソースは、シンプル形式または XML 形式のいずれかを使用して EPAgent プラグインにプラグインされる、プラグインまたは他のメトリック生成プログラムです。
シンプル形式のメトリック データ
以下の形式を使用して、行ごとに 1 つのメトリック名と値を指定します。
<metric_name>=<value>
例:
diskWrites=37
リソース セグメントへの参照を含めることもできます。例:
<resource_segment>:<metric_name>=<value>
たとえば、以下のとおりです(すべて 1 行で記述します)。
Resource Usage|File IO:diskWrites=37 Apache Errors:LastErrorString=ERROR: Apache shutdown unexpectedly
シンプル形式のガイドラインは、以下のとおりです。
- メトリック名に等号(=)を含めることはできません。名前が等号(=)を必要とする場合は、XML 形式を使用します。
- 値には等号(文字列として)を含めることができます。EPAgent は常に最初の等号まで(左から右に読む場合)のすべての文字をメトリック名として解析します。EPAgent は、最初の等号の後のすべての文字を値として解析します。
- EPAgent プラグインは、数字から構成される値をすべて数値データとして解釈し、IntCounter型として値をレポートします。
- EPAgent プラグインは、数字以外で構成される値をすべて文字列データとして解釈します。EPAgent プラグインは、Introscope;string event型として値をレポートします。
XML 形式のメトリックデータ
シンプル形式ではメトリック タイプに制限があるのに対し、XML スタイル形式では、プラグインで追加情報をレポートできます。たとえば、メトリック名、メトリック タイプ、および値です。例:
<metric type="LongCounter" name="Resource Usage|File IO:diskWrites" value="37" /> <metric type="StringEvent" name="Apache Errors:LastErrorString" value="ERROR: Apache shutdown unexpectedly" />
XML 形式のガイドライン
- XML 形式では、データ タイプが完全にサポートされ、メトリック名と値で等号(=)を使用できます。
- メトリックの type 属性は、以下のいずれかの値である必要があります。
- PerIntervalCounter -- 値は間隔ごとのレート。間隔は変更可能です。これらのメトリックは、値を合計することによって、一定期間で集約されます。たとえば、トランザクションで 15 秒間に 10 のメソッド呼び出しがあり、次の 15 秒間に 15 のメソッド呼び出しがあるなどです。30 秒を超えるメトリックを集計することは、「30 秒間に 25 のメソッド呼び出し」になります。
- IntCounter -- int 値は上下します。
- IntAverage -- 徐々に平均される int 値。
- IntRate -- この値は 1 秒あたりのレートです。これらのメトリックは、値の平均値を利用することによって一定期間で集約されます。
- LongCounter -- long 値は上下します。
- LongAverage -- 徐々に平均される long 値。
- StringEvent -- 定期的に文字列を生成するタイプを表しています。このレコーダは、現在の値の概念を持たず、レポートされたイベントを受信した順番にレポートします。
- Timestamp -- 連続して増加するタイプスタンプを生成するタイプ。
- 比較には大文字と小文字の区別がないため、プラグインの作成が容易になります。数値タイプを指定し、値が数値以外の場合、Enterprise Manager には何もレポートされません。EPAgent プラグインは、エラーをログに記録します。
2 つのカスタム プラグイン形式に関する注意事項
いずれかのタイプのカスタム プラグイン形式を使用する際は、以下の注意事項を考慮してください。
- 両方の形式をサポートすると、システムが不等号の小なり記号で始まるメトリック名を認識しないという、相互作用の原因になります。
- いずれの形式の場合も、無効な構文や不正な構文などにより形式が解析できない場合、EPAgent プラグインはその行を無視します。また、EPAgent は、エラーをログに記録します。
- プラグインが複数の行を返す場合、次の行が続けて解析されます。
- 各メトリック名に対して、メトリック タイプを 1 つだけ指定できます。複数のタイプを指定すると、以下のエラーが発生します。mm/dd/yy hh:mm:ss PM PDT [ERROR] [EPAgent] Metric name from plugin 'Plugin <plugin_name>' is invalid: "<metric_name>" is already in use by another DataRecorder of a different type
エラーまたはイベント データ形式
EPAgent は、以下の 2 つの形式を使用して、プラグインが提供するエラーまたはイベント データを解析できます。
- シンプル
- XML
シンプル形式のエラーまたはイベント データ
通常、シンプル形式のスクリプトは、以下の固定文字列で始まります。
event:
コロンの後のテキストについては、以下のガイドラインを使用します。
- テキストは「name=value」ペアの一部であり、各ペアはアンパサンド(&)で区分されます。
- テキストは、イベントに対するオプション パラメータにできます。
以下の例は、Firefox ブラウザのプロセスを監視し、ブラウザが終了すると通知を送信する仮定のスクリプトの出力を示しています。
event:type=processWentAway&processName=firefox
単純な XML 形式のエラーまたはイベント データ
イベントは XML 形式で指定することもでき、この場合、エージェント内のイベントを完全に表現できます。最も単純な XML 形式のイベントは、イベントを生成したリソースの名前を通知します。たとえば、
Connection Pool
や Java Virtual Machine
という名前のリソースです。以下の例は、Some Resource
という名前のリソースでイベントが発生したことを通知しています。<event resource="Some Resource"/>
タイムスタンプは、イベントが生成された時間であり、イベント所要時間はゼロです。
パラメータと時間データを含む XML 形式のエラーまたはイベント データ
明示的なタイムスタンプと明示的な所要時間を持つイベント通知を設定できます。タイムスタンプ形式は、任意の Java 解析可能形式です。所要時間はミリ秒単位です。以下の例は、継続時間が 1 分(60,000 ミリ秒)のイベントです。
<event resource="Some Resource" startTime="123003000" duration="60000"> <param name="urgent" value="true"/> </event>
XML 形式でのエラー スナップショットの作成
エラー スナップショットは、パラメータ内でタイプをエラー スナップショットとして示す必要があります。例:
<event resource="Some Resource" startTime="123003000" duration="60000"> <param name="Trace Type" value="ErrorSnapshot"/> </event>
ネスト コンポーネント
以下の例は、ネストされたサブコンポーネントを持つイベントを示しています。イベントは、ゼロから無制限の数のサブコンポーネントを持つことができます。それぞれのサブコンポーネントはゼロから無制限の数のサブコンポーネントを持つこともできます。実際には、ネストのレベルは小さいか、またはゼロになる傾向があります。
<event resource="Some Resource"> <calledComponent resource="Another Resource"> <param name="isCorrelated" value="uncertain"/> <calledComponent resource="A Third Resource"/> <calledComponent resource="A Fourth Resource"/> </calledComponent> </event>
EPAgent プラグイン イベントとトランザクション追跡
[追跡ビュー]
タブを選択して、EPAgent プラグイン イベントをトランザクション追跡としてイベント ビューアに表示することができます。EPAgent プラグインが送信するイベントに時間情報が含まれていると、追跡ビューが理解しやすいものになります。時間情報を含めるには、
<event>
および <calledComponent>
タグの startTime
および offset
属性を使用します。startTime
属性は絶対時間です。形式は、java.util.Date.parse()
によって解析できるすべての形式です。<event>
エレメントに startTime
を指定する必要はありません。startTime
が指定されていない場合、Java メソッド System.currentTimeMillis()
または new Date().getTime()
によって指定される際に、現在の時刻の値がデフォルトで設定されます。startTime
を <calledComponent>
エレメントから省略すると、時間のデフォルトは含まれるエレメントの時間になります。startTime
属性がどこにも指定されていない場合は、デフォルトですべて現在の時刻に設定されます。offset
属性は、ミリ秒単位の時間と解釈される、整数値です。offset 属性
は、startTime
がデフォルトであれ明示的であれ startTime
属性に加算されます。これら 2 つの属性が追加されると、<event>
または <calledComponent>
について EPAgent がレポートする実際の時刻が生成されます。例 1
<event resource="Customized Web Server" startTime="123456789" duration="500"> <calledComponent resource="Web Server Module" offset="300" duration="100"/> </event>
このイベントの追跡ビューには、123456789 に開始された
Customized Web Server
という名前のリソースが表示されます。また、123457089 (123456789 + 300)に開始された Web Server Module
という名前のリソースも表示されます。各エレメントの継続時間を指定すると、以下のトランザクション アクティビティを示す有用な追跡ビューが生成されます。- Customized Web Serverが 300 ミリ秒間実行
- Customized Web ServerによってWeb Server Moduleが呼び出されて 100 ミリ秒間実行
- Web Server Moduleが戻った後にCustomized Web Serverがさらに 100 ミリ秒間実行
例 2
<event resource="Customized Web Server" duration="500"> <calledComponent resource="Web Server Module" offset="300" duration="100"/> </event>
この例は、例 1 と似ていますが、
Customized Web Server
は現在の時刻に開始され、Web Server Module
が 300 ミリ秒後に開始されます。この例の構成では、EPAgent プラグイン スクリプトで現在時刻の取得が必要ない点に注意してください。例 3
<event resource="Customized Web Server" startTime="123000000" offset="1000" duration="5000"> <calledComponent resource="Web Server Module" startTime="123003000" duration="200"/> </event>
ここでは、
Customized Web Server
は 123001000 (123000000 + 1000)に開始され、Web Server Module
が 123003000 に開始されます。所要時間を指定することで可読性と使いやすさが向上します。startTime、offset、および duration の指定は注意深く行ってください。startTime、offset、duration が誤って指定された場合、トレース ビューが見にくくなります。開始時刻は
<calledComponent>
エレメントの startTime
と offset を追加することで計算されます。開始時刻はそれに含まれる <event>
または <calledComponent>
の開始時刻の後に発生することを確認します。<calledComponent>
の(開始時刻 + 期間)がその含まれる <event>
または <calledComponent>
の(開始時刻 + 期間)よりも小さいことを確認してください。エラーまたはイベント データの XML スキーマ
以下に、EPAgent プラグインがサポートするフォーマル XSD スキーマを示します。
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="event" type="eventElement"> <xs:annotation> <xs:documentation>The root element for events. This element is nearly equivalent to the calledComponent element, except that the event element must occur only once, at the outermost level.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="param"> <xs:complexType> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="value" type="xs:string" use="required"/> </xs:complexType> </xs:element> <xs:element name="calledComponent" type="eventElement"> <xs:annotation> <xs:documentation>A component called by the containing element. This element is nearly equivalent to the event element, except that this element cannot occur at the outermost level. </xs:documentation> </xs:annotation> </xs:element> <xs:complexType name="eventElement"> <xs:sequence> <xs:element ref="param" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="calledComponent" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="startTime" type="xs:dateTime" use="optional"/> <xs:attribute name="offset" type="xs:integer" use="optional" default="0"/> <xs:attribute name="duration" type="xs:dateTime" use="optional" default="0"/> </xs:complexType> </xs:schema>