EPAgent の使用

目次
apmdevops97jp
目次
EPAgent の実行
EPAgent は、スタンドアロンの .jar ファイル、または Java アプリケーションのいずれかとして実行できます。
スタンドアロン .jar ファイルとして EPAgent を実行する方法
  • 以下の例のように適切な
    -jar
    フラグを使用して、Java コマンドラインを実行します。
    java -Dcom.wily.introscope.epagent.properties="<EPAgent_Home>/epagent/IntroscopeEPAgent.properties" -jar <EPAgent_Home>/epagent/lib/EPAgent.jar
Java アプリケーションとして EPAgent を実行する方法
  • 適切な
    クラスパス
    に EPAgent ファイルを以下の例のように追加します。
    java -classpath "<EPAgent_Home>/epagent/lib/EPAgent.jar" -Dcom.wily.introscope.epagent.properties="<EPAgent_Home>/epagent/IntroscopeEPAgent.properties" com.wily.introscope.api.IntroscopeEPAgent
UNIX での EPAgent の実行
制御スクリプト(シェル スクリプト)を使用して、UNIX オペレーティング システムで Introscope EPAgent を実行できます。
以下の手順に従います。
  1. コマンド プロンプトを開きます。
  2. コントロール スクリプトがあるディレクトリに移動します。 たとえば、以下のように追加します。
    cd Introscope<version_number>/bin
  3. 目的のアクションに対応するコマンドを実行します。
    • EPACtrl.sh start
      EPAgent を開始します。
    • EPACtrl.sh status
      EPAgent プロセスのステータス(実行中または停止中)を表示します。
    • EPACtrl.sh stop
      EPAgent プロセスを停止します。
    • EPACtrl.sh help
      ヘルプ メニューを表示します。
EPAgent を使用したカスタム プラグインの実行
EPAgent を使用したカスタム プラグインを作成して、アプリケーションに固有の追加メトリックを収集できます。
以下の 2 つのガイドラインがあります。
メトリック データ形式
EPAgent は、シンプル形式または 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 は常に最初の等号まで(左から右に読む場合)のすべての文字をメトリック名として解析し、最初の等号の後にある文字をすべて値として解析します。
  • 数字で構成された値はすべて、数値データとして解釈され、CA Introscope の「IntCounter」型としてレポートされます。
  • 数字以外で構成された値はすべて、文字列データとして解釈され、CA Introscope の「string event」型としてレポートされます。
XML 形式のメトリックデータ
シンプル形式では Introscope メトリック タイプに制限があるのに対し、XML スタイル形式では、プラグインが、Introscope メトリック名、Introscope メトリック タイプ、および値などの追加情報を、以下の例に示すようにレポートできるようになります。
<metric type="LongCounter" name="Resource Usage|File IO:diskWrites" value="37" /> <metric type="StringEvent" name="Apache Errors:LastErrorString" value="ERROR: Apache shutdown unexpectedly" />
XML 形式のガイドラインは、以下のとおりです。
  • この形式により、Introscope データ タイプを完全にサポートし、メトリック名と値の両方で等号が使用できるようになります。
  • メトリックの type 属性は、以下のいずれかである必要があります。
    • PerIntervalCounter -- 値は間隔ごとのレート。間隔は変更可能です。 これらのメトリックは、値を合計することによって、一定期間で集約されます。 たとえば、15 秒間に10 のメソッド呼び出しがあり、次の15 秒間に 15 のメソッド呼び出しがあった場合、30 秒に集約すると、「30 秒間に25 メソッド呼び出し」になります。
    • IntCounter -- int 値は上下します。
    • IntAverage -- 徐々に平均される int 値。
    • IntRate -- 値は 1 秒あたりのレートです。 これらのメトリックは、値の平均値を利用することによって一定期間で集約されます。
    • LongCounter -- long 値は上下します。
    • LongAverage -- 徐々に平均される long 値。
    • StringEvent -- 定期的に文字列を生成するタイプを表しています。 このレコーダは、現在の値の概念を持たず、レポートされた順番にイベントをレポートするのみです。
    • Timestamp -- 連続して増加するタイプスタンプを生成するタイプ。
  • 比較には大文字小文字の区別がありません(プラグイン の作成を容易にします)。 数値タイプが入力されたが、値が数値以外の場合、Introscope には何もレポートされず、EPAgent によってエラーがログに記録されます。
2 つのカスタム プラグイン形式に関する注意事項
どちらかのタイプのカスタム プラグイン形式を使用するときは、以下の注意事項を考慮してください。
  • 両方の形式をサポートすると、システムが不等号の小なり記号で始まるメトリック名を認識しないという、相互作用の原因になります。
  • いずれの形式の場合も、無効な構文や不正な構文などにより形式が解析できない場合、EPAgent はその行を無視し、エラーをログに記録します。
  • プラグインが複数の行を返す場合、次の行が続けて解析されます。
  • 各メトリック名に対し、指定できるメトリックタイプは 1 つだけです。 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 形式のイベントは、イベントを生成したリソースの名前(たとえば、「接続プール」または「Java 仮想マシン」など)を通知します。 以下の例は、
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 を指定する必要はありません。指定されていない場合、Java メソッド System.currentTimeMillis() または new Date().getTime() によって指定される際に、現在の時刻の値がデフォルトで設定されます。 startTime を <calledComponent> エレメントから省略すると、時間のデフォルトは含まれるエレメントの時間になるので、startTime 属性がどこにも指定されていない場合は、デフォルトですべて現在の時刻に設定されます。
offset 属性は整数値です。 数値はミリ秒単位の時間と解釈され、startTime 属性 (startTime がデフォルトであれ明示的であれ)に加算されて、<event> または <calledComponent> にレポートされる実際の時刻を生成します。
例 1
<event resource="Customized Web Server" startTime="123456789" duration="500"> <calledComponent resource="Web Server Module" offset="300" duration="100"/> </event>
このイベントのトレース ビューには、123456789 に開始された「カスタマイズ Web サーバ」および 123457089 (123456789 + 300)に開始された「Web サーバ モジュール」があります。 各エレメントの所要時間の指定を合わせると、以下に示すような有用なトレース ビューを生成します。
  • 「カスタマイズ Web サーバ」が 300 ミリ秒実行
  • 「カスタマイズ Web サーバ」に呼び出され、「Web サーバ モジュール」が100 ミリ秒実行
  • 「Web サーバ モジュール」から戻った後に、 「カスタマイズ Web サーバ」が 100 ミリ秒実行
例 2
<event resource="Customized Web Server" duration="500"> <calledComponent resource="Web Server Module" offset="300" duration="100"/> </event>
この例は、例 1 と似ていますが「カスタマイズ Web サーバ」は現在の時刻に開始され、「Web サーバ モジュール」が 300 ミリ秒後に開始されます。 この例の構成では、EPAgent スクリプトで現在時刻の取得が必要ない点に注意してください。
例 3
<event resource="Customized Web Server" startTime="123000000" offset="1000" duration="5000"> <calledComponent resource="Web Server Module" startTime="123003000" duration="200"/> </event>
ここで、「カスタマイズ Web サーバ」は 123001000 (123000000 + 1000)に開始され、「Web サーバ モジュール」が123003000 に開始されます。
所要時間を指定することで可読性と使いやすさが向上します。 startTime、offset、duration が誤って指定された場合、トレース ビューが見にくくなるため、使用の際にはご注意ください。 特に、<calledComponent> エレメントの startTime と offset を加えて計算した開始時刻は常に、それを含む <event> または <calledComponent> の開始時刻より後である必要があります。また、<calledComponent> の(開始時刻 + 継続時間)は常に、それを含む <event> または <calledComponent> の(開始時刻 + 継続時間)より少なくする必要があります。
エラーまたはイベント データの XML スキーマ
フォーマル 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>