EPAgent のインストール、構成、および使用

内容
apmdevops96jp
内容
このセクションでは、CA APM Environment Performance Agent (EPAgent)のインストール、設定、および使用について説明します。
Environment Performance Agent の概要
CA APM Environment Performance Agent (EPAgent)は、Java 環境以外のソースによるメトリック データを CA Introscope に統合します。
EPAgent では、1 つのプロセスに対しサブプロセスを生成し、そのサブプロセスからオペレーティング システムのパイプ(標準の IPC メカニズム)を介して標準出力を受け取るという、多くのオペレーティング システムで使用できる機能を利用しています。 サブプロセスを起動する機能と、Perl のような柔軟なスクリプト環境とを組み合わせることで、事実上どのソースからでもアプリケーションのパフォーマンス情報を収集することができる、柔軟で強力な機能が得られます。
EPAgent によるプロセスからの入力の受信
EPAgent は、Java で実装され、Java 仮想マシン(JVM)で実行されます。 EPAgent は、JVM 機能を利用してサブプロセスを起動し、そのプロセスから STDOUT および STDERR を受信します。 任意のスクリプトや実行可能ファイル、その他コマンド ラインで起動可能なものはすべてプロセスとなります。 たとえば、以下の通りです。
  • C 言語で記述されたコンパイル済みプログラム
  • Perl スクリプト
簡単な PRINT 関数を実行することによって、サブプロセスのアプリケーションまたはスクリプトは EPAgent と通信できます。 以下の図は、アプリケーションまたはスクリプトがSTDOUT(標準出力)に出力することによって、メトリックデータを EPAgent に渡す方法を示しています。
This diagram depicts how the EPAgent communicates with processes. The example shows the communication and output  from the PRITN function.
EPAgent は、STDOUT (標準出力)を使用して受信するテキストが以下のいずれかの特定の形式に準拠していることが想定されています。
  • シンプルな名前/値のペア
または
  • XML
EPAgent テキスト形式の要件とオプションは、このマニュアルの後半で詳細に説明しています。
このマニュアルでは、EPAgent にデータを送信するアプリケーションまたはスクリプトを EPAgent プラグインと呼びます。 EPAgent には、詳細なメトリック データを提供するいくつかのデフォルト プラグインが含まれます。 また、ユーザはカスタムのプラグインを作成することもできます。
EPAgent およびスクリプト環境
EPAgent は、コンパイル済みアプリケーションを含め、サブプロセスの任意の実行可能ファイルのエンティティからテキストを受信することができます。もっとも柔軟なアプローチは、Perl、KornShell、または REXX などのスクリプト環境を使用することです。 インタープリタ型のスクリプト環境には実装の容易さという利点があり、ライブラリ、またはリレーショナルデータベース、OS サブシステム(プロセス テーブル、ファイル システムなど)、およびサードパーティ製品などの実際のデータ ソースへのインターフェースが数多く提供されています。
スクリプトは、幅広いソースから情報を収集することができます。 たとえば、スクリプトによって以下のことが可能です。
  • ライブラリ関数、またはシステム ユーティリティを呼び出し、データベースなどの重要なアプリケーションの存在を確認する。
  • アプリケーション ログファイルをスキャンおよび解析して、アプリケーション エラーを検出する。
スクリプト環境の柔軟性により、EPAgent が実質的にあらゆるソースから パフォーマンス、および管理情報を収集することが可能になります。 以下の図は、スクリプトが多くのソースから情報にどのようにアクセスできるかを示しています。
This diagram depicts an EPAgent collecting information using a script.
Perl インタープリタはさまざまなプラットフォーム上で使用でき、オペレーティング システム、ミドルウェア、およびサードパーティ製品へのデータの API を幅広くサポートしているため、CA Technologies では、EPAgent で Perl を使用することを強くお勧めします。 CA Introscope EPAgent には、プロセスの可用性の確認、ディスク パフォーマンス統計情報の取得、および HTTP ログの読み取りなどのさまざまな機能を実行するための、Perl スクリプトのサンプルセットが含まれています。 これらのスクリプトを拡張して、その他の機能を実行させることも可能です。
注:
PBD、EPAgent スクリプト、または JavaScript 計算機のカスタマイズに関するサポートについては、CA Technologies プロフェッショナル サービスにお問い合わせください。
EPAgent でのネットワーク ソースからの入力
ローカル プロセスからの入力に加えて、EPAgent はネットワーク ソースからの入力も使用できます。 これは、情報を収集するプロセスがネットワーク化されていて、EPAgent が実行できない場合に役立ちます。たとえば、ネットワーク ポートを使用して監視情報を提供したり Web URL に定期的にデータをポストする C++ バックエンド システムのようなプロセスが該当します。
EPAgent および CA Introscope
EPAgent は、スタンドアロン プロセスとして動作します。 PHP エージェント、Java エージェント、または .NET エージェントと同様に、Enterprise Manager に接続して管理およびパフォーマンスに関する情報を提供します。 以下の図は、Enterprise Manager に、EPAgent がどのようにデータを転送するかを示しています。
This diagram depicts the EPAgent pushing data to Introscope.
EPAgent を使用すれば、アプリケーション環境全体のより詳細なビューを取得できます。 分散型アプリケーションアーキテクチャは複雑であり、Java および Java 以外のアプリケーション サブシステムの混在で構成されることがよくあります。 EPAgent を使用することで、CA Introscope Workstation 内の Java および .NET メトリックと併せて、アプリケーション環境内の Java 以外および .NET 以外の部分からの情報を簡単に収集し表示することができるようになります。
サポートされるプラグイン
EPAgent は、ステートフル、および ステートレス プラグインの両方をサポートします。
注:
すべてのデフォルトのプラグインで、Perl バージョン 5.00503 以降が必須です。
プラグイン タイプ
利用可能なプラグイン タイプは以下の通りです。
  • ステートフル プラグイン --
    ステートフル プラグインは、EPAgent が起動する際に起動され無期限に実行する、長期実行スクリプト(デーモン)を想定しています。 これらのステートフル プラグインは、プラグインの標準出力チャネルを介して、データを CA Introscope にいつでも取り込むことができます。 ステートフル プラグインが終了した場合は、EPAgent によって再起動されます。
  • ステートレス プラグイン --
    ステートレス プラグインは、定期的なスケジュールで実行するように設計されており、実行する必要のある周期(実行から次の実行までの遅延時間として指定されます)を設定します。 収集したデータを標準出力チャネルを介して EPAgent に送信し、その後で終了するような短期実行スクリプトを想定しています。
    注:
    EPAgent では、同時に複数のステートレス プラグインのインスタンスが実行されていないかを確認するためのチェックを特に行っていないので、プラグイン開発者はステートレス プラグインが必要最小限の時間内で実行し、完了するように設計する必要があります。
エラー ログ
エラーは、プラグインの標準エラーチャネルを介してログに記録されます。EPAgent は、このエラー出力をその他のエラーと同様にログに記録することができます。
デフォルト プラグイン
EPAgent には、最小限の構成で使用できるデフォルトのプラグインのライブラリが含まれています。 以下の表に、各プラグインの機能とサポートされているオペレーティング システムについての概要を示します。
プラグイン
機能
サポートされている環境
プロセス可用性チェック
特定の名前を持つ実行中のプロセスを検索
Solaris
OS レベル ディスク統計
読み取り/書き込み、トランザクション時間、待機時間 %、ディスク容量などをレポート
Solaris
Apache ログ リーダー
HTTP エラー数、トランザクション数、平均トランザクション サイズをレポート
Solaris
WebLogic ログ リーダー
エラー数、警告数をレポート
Solaris
WebSphere ログ リーダー
エラー数、警告数をレポート
Solaris
IIS ログ リーダー
タイプごとのエラー数、使用されたページ数、IP アドレスごとのユーザ数をレポート
Windows
HTTP サービス可用性
HTTPS サービス可用性
接続の成功/失敗、接続の往復時間、平均スループット/帯域幅をレポート
Solaris
Solaris Kstat 統計
I/O 統計情報など、Kstat ユーティリティを介して使用できるすべての統計情報、すべてのデバイスのネットワーク統計情報、仮想メモリ統計情報をレポートします。
Solaris
 
カスタム プラグイン
EPAgent は、任意のプログラムおよびプラグインからデータを収集することができますが、そのためにはサポートされている 2 種類の形式のいずれかでデータが出力される必要があります。
Environment Performance Agent のインストール
EPAgent をインストールするには、スタンドアロン エージェント インストーラを使用します。
注:
詳細については、「
CA APM インストールおよびアップグレード ガイド
」を参照してください。
EPAgent スタンドアロン インストーラ
以下のスタンドアロン エージェント インストーラのいずれかを使用して、EPAgent を別のコンピュータ上にインストールすることができます。 CA APM 製品は、CA サポートの CA APM のソフトウェア ダウンロード領域からダウンロードできます。
  • EPAgent<
    バージョン
    >windows.zip
  • EPAgent<
    バージョン
    >ebcdic.tar
  • EPAgent<
    バージョン
    >unix.tar
EPAgent インストーラを抽出すると、以下のファイルが
<EPAgent_Home>/
epagent ディレクトリにインストールされます。
注:
<EPAgent_Home>
は EPAgent をインストールしたディレクトリです。
  • IntroscopeEPAgent.properties
  • lib/EPAgent.jar
  • epaplugins/ (プラグインの最上位ディレクトリ)
    • epaplugins/apache/apacheLogReader.pl
    • epaplugins/iis/iisLogReader.pl
    • epaplugins/solaris/diskStats.pl
    • epaplugins/solaris/kstat.pl
    • epaplugins/solaris/httpSvcAvailability.pl
    • epaplugins/solaris/processAvailability.pl
    • epaplugins/weblogic/weblogicLogReader.pl
    • epaplugins/websphere/websphereLogReader.pl
    • epaplugins/windows/diskStats.pl
    • epaplugins/windows/httpSvcAvailability.pl
    • epaplugins/windows/processAvailability.pl
  • /xml (ChangeDetector ファイルのトップレベルのディレクトリ)
    • ChangeDetectorAgent.jar
    • ChangeDetector-Agent_Server.jar
    • ChangeDetector-CommonAll.jar
    • ChangeDetector-config.xml
    • Windows: cdnativefile.dll
    • UNIX: libcdnativefile.so
EPAgent の構成
EPAgent には、Enterprise Manager の場所、およびポート設定などの、エージェントの構成プロパティのセットが含まれています。
注:
プロパティ ファイルの設定で何らかのエラー(無効なファイル名パスなど)があると、EPAgent は起動に失敗します。 ブート時に EPAgent を自動的に起動する場合には、プロパティが正しく設定されていることを確認してください。
EPAgent プロパティの設定
EPAgent で使用されるプロパティは Java エージェントで使用されるプロパティと同様です。
以下の手順に従います。
  1. IntroscopeEPAgent.properties
    ファイルで EPAgent を設定します。 EPAgent の設定は、CA Introscope エージェント プロファイルで定義される設定と同じタイプのものを使用します。
    注:
    プロパティの詳細については、「
    CA APM Java エージェント実装ガイド
    」を参照してください。
  2. IntroscopeEPAgent.properties
    ファイルの名前または場所を変更する場合、以下の Java システム プロパティを使用して設定できます。
    -Dcom.wily.introscope.epagent.properties=filename
    注:
    このシステム プロパティは、コマンド ラインで「java」という文字列に続けて入力する必要があります。 コマンド ラインの後方(たとえば
    -jar
    の後など)に記述された場合は無効です。
EPAgent ログ記録オプションの設定
デフォルトでは、EPAgent はメッセージ、およびエラー出力をコマンド コンソールに送信します。 メッセージおよびエラー出力がログ ファイルにも送信されるように EPAgent を設定できます。
以下の手順に従います。
  1. <
    EPAgent_Home
    >/epagent/IntroscopeEPAgent.properties ファイルを開きます。
  2. プロパティを変更します。
冗長モードでの EPAgent の実行と出力ファイルのリダイレクト
EPAgent を冗長モードで実行すると、ログに詳細な情報が記録されます。これはデバッグ時に役立ちます。 冗長モードの有無を設定するプロパティでは、ログ ファイルの出力先も設定できます。
以下の手順に従います。
  1. <
    EPAgent_Home
    >/epagent/IntroscopeEPAgent.properties ファイルを開きます。
  2. プロパティ log4j.logger.EPAgent を以下のようにコメント化します。
    #log4j.logger.EPAgent=INFO, console
  3. 出力をコンソールではなくログ ファイルに送るようにするには、プロパティ log4j.logger.IntroscopeAgent のコメント化を解除し、INFO を VERBOSE#com.wily.util.feedback.Log4JSeverityLevel に、console を logfile にそれぞれ置き換えます。 たとえば、EPAgent から冗長モードでログ ファイルにレポートが出力されるようにするには、プロパティは以下のようになります。
    log4j.logger.IntroscopeAgent=VERBOSE#com.wily.util.feedback.Log4JSeverityLevel,logfile
  4. 変更を保存し、IntroscopeEPAgent.properties ファイルを閉じます。
重要:
IntroscopeEPAgent.properties ファイルを保存した後も、プロパティ ファイルが読み取られて実装されるまでは、EPAgent ログはコマンド コンソールにそのまま表示されます。 プロパティ ファイルが実装されると、以降のログはログ ファイルに書き込まれるようになります。
EPAgent プラグインの構成
IntroscopeEPAgent.properties ファイルの特定のプロパティをコメント化解除するだけで、デフォルトのプラグインを使用して EPAgent を実行することができます。
ただし、IntroscopeEPAgent.properties ファイル内のデフォルトのプラグインから必要のないプラグインを削除したり、プラグインを追加することも可能です。
EPAgent プラグインは、IntroscopeEPAgent.properties ファイルで、ステートフルとステートレスの 2 つのセクションに分けられます。
ステートフル プラグインの追加
EPAgent によって使用されるプラグインは、
IntroscopeEPAgent.properties
ファイルで設定されます。
以下の手順に従います。
  1. <
    EPAgent_Home
    >/epagent/IntroscopeEPAgent.properties ファイルを開きます。
  2. プロパティ
    introscope.epagent.plugins.stateful.names
    をコメント化解除し、すべてのステートフル プラグインの名前をカンマ区切りで以下の例のように追加します。
    introscope.epagent.plugins.stateful.names=APACHE,WEBLOGIC,WEBSPHERE,IIS
  3. 前の手順で追加されたステートフル プラグインの名前に、必要なすべてのコマンド ライン引数を含めて、ステートフル プラグインを開始または起動するのに必要な完全なコマンドを指定する行を追加します。
注:
コメント化解除することによってファイル内のデフォルトのプロパティを使用できます。ただしプラグインを開始または起動するには、必要なコマンド ラインを完全な形で記述する必要があります。
前の手順で指定したステートフル名のプロパティには、以下の 4 行が必要です。
introscope.epagent.stateful.APACHE.command=/usr/bin/perl <EPAgent_Home>/epagent/epaplugins/apache/apacheLogReader.pl introscope.epagent.stateful.WEBLOGIC.command=/usr/bin/perl <EPAgent_Home>/epagent/epaplugins/weblogic/weblogicLogReader.pl introscope.epagent.stateful.WEBSPHERE.command=/usr/bin/perl <EPAgent_Home>/epagent/epaplugins/websphere/websphereLogReader.pl introscope.epagent.stateful.IIS.command=/usr/bin/perl <EPAgent_Home>/epagent/epaplugins/iis/iisLogReader.pl
注:
Windows マシンの場合、パスを追加する際には以下のようにして、もう 1 つの円記号を使って円記号をエスケープする必要があります。
introscope.epagent.stateful.TEST.command=perl c:\\mydirectory\\myscript.pl
次の手順
ステートレス プラグインを追加できます。 ステートレス プラグインを追加しない場合は、IntroscopeEPAgent.properties ファイルへの変更を保存し、EPAgent を再起動します。
ステートレス プラグインの追加
ステートレス プラグインを追加できます。
以下の手順に従います。
  1. <
    EPAgent_Home
    >/epagent/IntroscopeEPAgent.properties ファイルを開きます。
  2. プロパティ
    introscope.epagent.plugins.stateless.names
    で、プロパティをコメント化解除し、すべてのステートレス プラグインに対し、カンマ区切りで、以下のようにして論理名を追加します。
    introscope.epagent.plugins.stateless.names=DISK,ORACLE,HTTP,KSTAT
  3. 前の手順で追加されたステートレス プラグイン名にさらに 2 行を追加します。以下のように指定します。
    • ステートレス プラグインを開始または起動するのに必要な、完全コマンド ライン(「EPAgent のデフォルト プラグイン」を参照して必要なすべてのコマンド ライン引数を含めます)。以下のような構文になります。
      introscope.epagent.plugins.stateless.<pluginname>.command= <command>
    • EPAgent がプラグインを実行する周期。実行から実行までの遅延時間として秒単位で定義します。以下のような構文になります。
      introscope.epagent.stateless.<pluginname>.delayInSeconds=<value in seconds>
    たとえば、以下の通りです。
    introscope.epagent.stateless.DISK.command=/usr/bin/perl <EPAgent_Home>/epagent/epaplugins/solaris/diskStats.pl introscope.epagent.stateless.DISK.delayInSeconds=900 introscope.epagent.stateless.ORACLE.command=/usr/bin/perl <EPAgent_Home>/epagent/solaris/processAvailability.pl introscope.epagent.stateless.ORACLE.delayInSeconds=900 introscope.epagent.stateless.HTTP.command=/usr/bin/perl <EPAgent_Home>/epaplugins/solaris/httpSvcAvailability.pl introscope.epagent.stateless.HTTP.delayInSeconds=900 introscope.epagent.stateless.KSTAT.command=/usr/bin/perl <EPAgent_Home>/epaplugins/solaris/kstat.pl introscope.epagent.stateless.KSTAT.delayInSeconds=900
    注:
    これらの例は、これらのプロパティのデフォルトの値です。 使用するには、各プロパティをコメント化解除する必要があります。
  4. 作業が終了したら、変更を保存して EPAgent を再起動します。
ステートフルおよびステートレス プラグインの削除
任意の理由でプラグインを削除できます。
以下の手順に従います。
  1. <
    EPAgent_Home
    >/epagent/IntroscopeEPAgent.properties ファイルを開きます。
  2. プロパティ
    introscope.epagent.plugins.stateful.names
    および
    introscope.epagent.plugins.stateless.names
    で、削除対象のプラグインの名前を削除します。
  3. 削除するプラグインに関連付けられたすべてのコマンド ラインをコメント化するか、または削除します。
  4. 作業が終了したら、変更を保存して EPAgent を再起動します。
Java クラス プラグインの構成
EPAgent JVM 内で実行される Java クラスのプラグインを設定するには、EPAgent プロパティ ファイルで、以下のプロパティを設定します。
introscope.epagent.stateful.JAVA-CLASS.class=my.package.path.Class arg1 arg2 arg3
注:
完全修飾クラス名に続けて任意のオプションを入力します。たとえば、以下のように入力します。
introscope.epagent.plugins.stateful.names=add introscope.epagent.stateful.add.class=com.wily.math.Add 1 2
ネットワーク データ ソースに関する EPAgent の構成
ネットワーク ソースからデータを受信するように EPAgentを構成することができます。
シンプル形式または XML 形式のネットワーク入力に関する EPAgent の構成
ネットワーク経由でデータを受け取れるように EPAgent を設定するには、EPAgent プロパティ ファイルの以下の行のコメント化を解除します。
introscope.epagent.config.networkDataPort=8000
HTTP GET 入力に関する EPAgent の構成
EPAgent で、簡易 HTTP サーバを作成して HTTP GET 要求をリスンします。 HTTP GET 要求は Enterprise Manager に送信するメトリックを定義します。
HTTP GET 要求は、以下の構文を使用します。
http://epaHost:epaPort/?metricType=type&metricName=name&metricValue= value
簡易 HTTP サーバを有効化およびテストする方法
  1. EPAgent プロパティ ファイル内で、以下のプロパティをコメント化解除することによって、簡易 HTTP サーバを有効にします。
    introscope.epagent.config.httpServerPort=8080
  2. EPAgent を再起動します。
    変更が反映されます。
  3. ブラウザを通して、HTTP GET 要求をテストします。 たとえば、以下の通りです。
    http://localhost:8080/?metricType=IntCounter&metricName= MyHTTPMetric|Test:MyCounter&metricValue=15
    15 秒後、EPAgent で、MyHTTPMetric|Test:MyCounter メトリックが表示されます。
    メトリックを更新するには、EPAgent で新しい HTTP GET 要求を受信する必要があります。 したがって、簡易 HTTP サーバ機能は、複数の HTTP GET 要求を発行するツールと併用するよう意図されています。 たとえば、複数の wget コマンドを発行する オープン ソース ツール Wget を使用して、複数の HTTP GET 要求を作成することができます。 Wget の詳細については、以下を参照してください。
    http://www.gnu.org/software/wget/wget.html
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 を実行することで、通常ほとんどのユーザのニーズを満たす情報を収集できます。 ただし、EPAgent でカスタム プラグインを使用したい場合があります。 これを行うには、以下の 2 つのガイドラインに従います。
メトリック データ形式
EPAgent は、プラグイン(または EPAgent にプラグインとして提供されている、その他のメトリック生成プログラム)から提供された以下の 2 つの異なる形式のメトリックデータを解析できます。
  • シンプル
  • XML
シンプル形式のメトリック データ
以下の形式を使用して、行ごとに 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 から送信されたイベントに時間情報が含まれていると、追跡ビューが理解しやすいものになります。 時間情報を含めるには、 および タグの startTime および offset 属性を使用します。
startTime 属性は絶対時間です。 形式は、java.util.Date.parse() によって解析できるすべての形式です。 エレメントに startTime を指定する必要はありません。指定されていない場合、Java メソッド System.currentTimeMillis() または new Date().getTime() によって指定される際に、現在の時刻の値がデフォルトで設定されます。 startTime を エレメントから省略すると、時間のデフォルトは含まれるエレメントの時間になるので、startTime 属性がどこにも指定されていない場合は、デフォルトですべて現在の時刻に設定されます。
offset 属性は整数値です。 数値はミリ秒単位の時間と解釈され、startTime 属性 (startTime がデフォルトであれ明示的であれ)に加算されて、 または にレポートされる実際の時刻を生成します。
例 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 が誤って指定された場合、トレース ビューが見にくくなるため、使用の際にはご注意ください。 特に、 エレメントの startTime と offset を加えて計算した開始時刻は常に、それを含む または の開始時刻より後である必要があります。また、 の(開始時刻 + 継続時間)は常に、それを含む または の(開始時刻 + 継続時間)より少なくする必要があります。
エラーまたはイベント データの 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>