EPAgent Java クラス プラグインの拡張機能

apmsaas
スタンドアロン EPAgent はダウンロードできなくなりました。また、この機能は、DX APM SaaS および DX APM オンプレミス(20.x 以降)で APM インフラストラクチャ エージェントの EPAgent 拡張機能を使用してサポートされるようになりました。実装の詳細は、こちらを参照してください。ただし、既存のユーザは、ここで説明する手順を使用して、レガシー スタンドアロン EPAgent を DX APM SaaS または DX APM オンプレミス(20.x 以降)に接続できます。詳細については、「スタンドアロン EPAgent のインストールおよび設定」と「クラウド プロキシ」を参照してください。
EPAgent プラグイン拡張機能は、ステートレスとステートフルの Java クラス形式で作成できます。10.7 より前の既存の EP エージェント プラグインを、インフラストラクチャ エージェント拡張形式に変換することもできます。
以下の高レベル手順に従います。
2
2
example.zip ファイルをダウンロードします。
続くトピックで説明されているサンプル Java クラス プラグインのファイルおよびスクリプトを含む example.zip ファイルをダウンロードします。
プラグイン クラスの書き込み
インフラストラクチャ エージェントは、ステートフルおよびステートレスの 2 つのタイプのプラグインを呼び出します。インフラストラクチャ エージェントは、どちらのプラグインも同じ方法で呼び出します。どちらのプラグインも、メトリックとトランザクションの追跡データを出力に印刷するために同じ形式を使用します。
ステートレス プラグインは、一連のデータを生成した直後に制御を戻して終了することが想定されています。このプラグインはその後ロードされ、一定の時間が経過したら再度呼び出されます。
ステートフル プラグインは、
main()
インターフェース メソッドへの最初の呼び出し後に実行状態を維持することが想定されています。このプラグインはさらに、内部ロジックに従って定期的に出力ストリームへのデータの書き込みを続けることが想定されています。ステートフル プラグインの実装はさらに複雑です。ただし、ステートフル プラグインには、継続的に再利用されるインスタンス変数の状態が維持されるという利点があります。たとえば、オープン ファイル記述子などです。
以下の手順に従います。
  1. オプション: 10.7 より前の EP エージェントの展開の既存プラグインを使用します。これらのプラグインは変更しなくても使用できます。
    1. プロジェクトのソース ディレクトリに、10.7 より前の既存の EP エージェント プラグイン ソース ファイルをコピーします。
    2. プラグインのコンパイル」に移動して、10.7 より前の既存の EP エージェント プラグインをインフラストラクチャ エージェント拡張形式に変換することを続行します。
  2. テキスト エディタを使用して、新しいプラグイン クラス ファイルを作成します。この例で示すように、
    main()
    インターフェース メソッドの両方のバージョンを実装します。
    public static void main(String[] args);
    public static void main(String[] args, PrintStream out);
    プラグイン外部テストの最初のインターフェース バージョンを使用できます。プラグインを効率的にロードするには、インフラストラクチャ エージェントの 2 番目のバージョンを使用できます。
プラグイン クラスの例
この例では、ソース(
src
)ディレクトリの
/examples
サブディレクトリに 2 つのプラグイン クラスがあります。
src
|-- examples
| `-- epagent
| `-- plugin
| |-- SampleStatefulPlugin.java
| `-- SampleStatelessPlugin.java
`-- manifest
SampleStatelessPlugin クラスは、このサンプルの epagent.plugin に示すように、2 つのメトリックを順に生成します。
package examples.epagent.plugin;
import java.io.PrintStream;
import java.util.Date;
import java.util.Random;
public class SampleStatelessPlugin {
public static final Random random = new Random();
public static void main(String[] args) throws Exception
{
main(args, System.out);
}
public static void main(String[] args, PrintStream out) throws Exception
{
int mean = Integer.parseInt(args[0]);
int sd = Integer.parseInt(args[1]);
Double value = sd * random.nextGaussian() + mean;
out.println("examples|stateless:intvalue=" + value.intValue());
out.println("examples|stateless:date=" + new Date().toString());
}
}
まず SampleStatelessPlugin でクラスは、特定の平均および標準偏差のランダムな正規分布メトリックを生成します。次にこのクラスは、現在の日付で 2 番目の文字列メトリックを生成し、新たに開始します。
SampleStatefulPlugin クラスが、このサンプルの epagent.plugin に示されています。
package examples.epagent.plugin;
import java.io.PrintStream;
import java.util.Date;
import java.util.Random;
public class SampleStatefulPlugin {
public static final Random random = new Random();
public static void main(String[] args) throws Exception
{
main(args, System.out);
}
public static void main(String[] args, PrintStream out) throws Exception
{
int mean = Integer.parseInt(args[0]);
int sd = Integer.parseInt(args[1]);
int period = Integer.parseInt(args[2]);
while(true) {
Double value = sd * random.nextGaussian() + mean;
out.println("examples|stateful:intvalue=" + value.intValue());
out.println("examples|stateful:date=" + new Date().toString());
Thread.sleep(period);
}
}
}
SampleStatefulPlugin クラスはまず、特定の平均および標準偏差のランダムな正規分布メトリックも生成します。次にこのクラスは、現在の日付で 2 番目の文字列メトリックを生成します。3 番目の引数は、指定したミリ秒だけスリープ状態になるように SampleStatefulPlugin に指示します。スリープになると、SampleStatefulPlugin がスリープ サイクルで恒久的にループし続けます。
プラグインのコンパイル
以下の手順に従います。
この例で示すように、コードをコンパイルするには
javac
コマンドを使用します。
$ cd src $ javac examples/epagent/plugin/*.java
コードをコンパイルしたら、プラグインはこの例で示すようにクラス ファイルを持ちます。
$ tree src src |-- examples | `-- epagent | `-- plugin | |-- SampleStatefulPlugin.class | |-- SampleStatefulPlugin.java | |-- SampleStatelessPlugin.class | `-- SampleStatelessPlugin.java `-- manifest 3 directories, 5 files
拡張マニフェストの作成
インフラストラクチャ エージェントは、拡張クラスをロードするために特殊なマニフェストを必要とします。マニフェストには、.jar ファイル内のクラスの解釈方法をインフラストラクチャ エージェントに指示する、特殊な
com-wily-*
属性があります。
以下の手順に従います。
  1. テキスト エディタを使用して、manifest.txt と呼ばれるファイルを作成します。
  2. マニフェストに以下の行を追加することで、
    com-wily-Extension-Version
    を 1 に設定します。
    com-wily-Extension-Version: 1
  3. マニフェストに以下の行を追加することで、拡張機能に名前を付けます。
    com-wily-Name: <Plug-in_Name>
    たとえば、com-wily-Name: EPAgentTestPlugins とします。
  4. com-wily-Extension-Plugins-List
    属性内のすべてのプラグイン クラスを一覧表示します。例:
    com-wily-Extension-Plugins-List: SampleStatelessPlugin,SampleStatefulPlugin
  5. 一覧表示された各プラグインに対して、
    com-wily-Extension-Plugin-
    プレフィックスで始まるさらに 4 つの属性を追加し、プラグイン名と属性のサフィックスを連続させます。属性のサフィックスを以下に示します。
    Version
    常に 1 に設定されています。
    名前
    プラグインがロードされるとエージェント ログに表示される、プラグイン名。
    Type
    epaplugin
    に設定します。
    エントリ ポイント クラス
    プラグイン
    main()
    メソッドを実装するクラスの名前。
    以下に例を示します。
    com-wily-Extension-Plugin-SampleStatelessPlugin-Name: EPA Sample Stateless Plugin
    com-wily-Extension-Plugin-SampleStatelessPlugin-Version: 1
    com-wily-Extension-Plugin-SampleStatelessPlugin-Type: epaplugin
    com-wily-Extension-Plugin-SampleStatelessPlugin-Entry-Point-Class: examples.epagent.plugin.SampleStatelessPlugin
    com-wily-Extension-Plugin-SampleStatefulPlugin-Name: EPA Sample Stateful Plugin
    com-wily-Extension-Plugin-SampleStatefulPlugin-Version: 1
    com-wily-Extension-Plugin-SampleStatefulPlugin-Type: epaplugin
    com-wily-Extension-Plugin-SampleStatefulPlugin-Entry-Point-Class: examples.epagent.plugin.SampleStatefulPlugin
  6. この例で示すように、マニフェストの残りの部分を作成します。
    Manifest-Version: 1.0 Created-By: CA Technologies com-wily-Name: EPAgentTestPlugins com-wily-Build: 1 com-wily-Extension-Type: Introscope-Agent com-wily-Extension-Version: 1 com-wily-Extension-Name: EPAgentTestPlugins com-wily-Extension-Plugins-List: SampleStatelessPlugin,SampleStatefulPlugin com-wily-Extension-Plugin-SampleStatelessPlugin-Name: EPA Sample Stateless Plugin com-wily-Extension-Plugin-SampleStatelessPlugin-Version: 1 com-wily-Extension-Plugin-SampleStatelessPlugin-Type: epaplugin com-wily-Extension-Plugin-SampleStatelessPlugin-Entry-Point-Class: examples.epagent.plugin.SampleStatelessPlugin com-wily-Extension-Plugin-SampleStatefulPlugin-Name: EPA Sample Stateful Plugin com-wily-Extension-Plugin-SampleStatefulPlugin-Version: 1 com-wily-Extension-Plugin-SampleStatefulPlugin-Type: epaplugin com-wily-Extension-Plugin-SampleStatefulPlugin-Entry-Point-Class: examples.epagent.plugin.SampleStatefulPlugin
  7. (オプション)プラグイン クラスにサードパーティ ライブラリへの依存関係がある場合には、いくつかのタスクを実行します。
    1. ライブラリ JAR ファイルを、使用する JAR ファイル PrepareStructure とともに以下に含めることができます。
    2. Class-Path
      属性をマニフェストに追加します。例:
      Class-Path: external/snmp4j.jar
  8. ファイルを保存して閉じます。
拡張 JAR ファイルを作成してテストします。
以下の手順に従います。
  1. /lib ディレクトリ内に JAR ファイルを作成するには、この Java
    jar
    コマンドを実行します。
    $ cd src
    $ jar cvfm ../lib/examples.jar manifest examples/epagent/plugin/*.class
    added manifest
    adding: examples/epagent/plugin/SampleStatefulPlugin.class(in = 1420) (out= 783)(deflated 44%)
    adding: examples/epagent/plugin/SampleStatelessPlugin.class(in = 1323) (out= 712)(deflated 46%)
    $ cd ..
    JAR ファイルは、最終の拡張機能パッケージの lib ディレクトリ内に存在している必要があります。
  2. それらが正しいことを確認するには、.jar ファイルの内容を調べます。以下に .jar ファイルの例を示します。
    $ /c/apm-dev/jdks/jdk1.8.0_05/bin/jar tvf lib/examples.jar
    0 Mon Mar 19 12:16:08 PDT 2018 META-INF/
    962 Mon Mar 19 12:16:08 PDT 2018 META-INF/MANIFEST.MF
    1420 Mon Mar 19 11:54:52 PDT 2018 examples/epagent/plugin/SampleStatefulPlugin.class
    1323 Mon Mar 19 11:54:52 PDT 2018 examples/epagent/plugin/SampleStatelessPlugin.class
  3. この例で示すように、プラグインが機能することを確認するには、プラグインを直接呼び出します。
    $ java -cp lib/examples.jar examples.epagent.plugin.SampleStatelessPlugin 100 5
    examples|stateless:intvalue=93
    examples|stateless:date=Mon Mar 19 12:20:17 PDT 2018
    $ java -cp lib/examples.jar examples.epagent.plugin.SampleStatefulPlugin 300 20 5000
    examples|stateful:intvalue=309
    examples|stateful:date=Mon Mar 19 12:20:54 PDT 2018
    examples|stateful:intvalue=303
    examples|stateful:date=Mon Mar 19 12:20:59 PDT 2018
    examples|stateful:intvalue=287
    examples|stateful:date=Mon Mar 19 12:21:04 PDT 2018
    examples|stateful:intvalue=266
    examples|stateful:date=Mon Mar 19 12:21:09 PDT 2018
    examples|stateful:intvalue=330
    examples|stateful:date=Mon Mar 19 12:21:14 PDT 2018
    ^C
    $
    予期どおり、ステートフル プラグインは終了しません。
  4. サイクルを中断するには、
    Ctrl + C
    キーを押します。
拡張機能フォルダ構造の準備
インフラストラクチャ エージェント拡張機能は、tar.gz アーカイブとして、以下の特定のフォルダ構造でパッケージされます。
  • bundle.properties ファイルは、ルート ディレクトリにあります。
  • .jar ファイルは、/lib ディレクトリにあります。
  • すべてのスクリプトは、/bin ディレクトリにあります。
  • description.md ファイルは、/metadata ディレクトリにあります。
|-- bundle.properties
|-- lib
| `-- examples.jar
`-- metadata
|-- bundle.json
`-- description.md
/lib ディレクトリは、JAR ファイルを作成するときに作成されています。ここでメタデータ ディレクトリを作成し、上記の 3 つのファイルを入れる必要があります。
以下の手順に従います。
  1. プラグイン実装が他のサードパーティ ライブラリに依存している場合は、それらを lib/external ディレクトリに追加します。例: lib/external/snmp4j.jar
  2. マニフェスト ファイルを作成したときに、クラス パス属性を追加したことを確認します。
bundle.json ファイルの準備
bundle.json には、プラグイン拡張機能メタデータが含まれています。
以下の手順に従います。
  1. テキスト エディタを使用して、bundle.json と呼ばれるファイルを作成します。
  2. 以下のコードをコピーし、それを正規フォーマットでファイル内に貼り付けます。
    {
    "specificationVersion": "2",
    "name" : "EpaPluginsJava",
    "displayName" : "EPA Plugin Extension for java",
    "version" : "1.0",
    "type": "epa",
    "dependencies" : [ ],
    "compatibility": {"osName" : ["windows","linux"], "agentVersion" : ">=10.5" }
    }
  3. 拡張機能の名前とバージョンを変更します。
  4. specificationVersion 値は
    2
    のままにしておきます。
  5. ファイルを保存して閉じます。
description.md ファイルの準備
description.md ファイルは、拡張機能の説明を含む markdown ファイルです。
以下の手順に従います。
  1. テキスト エディタを使用して、description.md ファイルを作成します。
  2. ファイルの内容に、プラグイン拡張機能の説明を記述します。以下に簡単な例を示します。
    This extension contains sample APM epagent plugins for Java.
  3. ファイルを保存して閉じます。
bundle.properties ファイルの準備
bundle.properties ファイルには、EPAgent プラグインをロードするインフラストラクチャ エージェントのプロパティが含まれています。
以下の手順に従います。
  1. ステートレスおよびステートフル プラグインは、別の名前リスト プロパティで定義します。プラグイン名ごとに、プラグイン引数を使用して、クラスのプロパティを指定します。この例では、100 と 5 がプラグインに渡される値です。
    introscope.epagent.stateless.EPAgentJavaExamples.names=SamplePlugin1
    introscope.epagent.stateless.EPAgentJavaExamples.SamplePlugin1.class=examples.epagent.plugin.SampleStatelessPlugin 100 5
    introscope.epagent.stateful.EPAgentJavaExamples.names=SamplePlugin2
    introscope.epagent.stateful.EPAgentJavaExamples.SamplePlugin2.class=examples.epagent.plugin.SampleStatefulPlugin 100 15 5000
  2. ステートレス プラグインには、プラグインの呼び出し間隔を指定するための、必須の
    delayInSeconds
    プロパティを追加します。このプロパティには、最大値はありません。
    introscope.epagent.stateless.EPAgentJavaExamples.names=SamplePlugin1
    introscope.epagent.stateless.EPAgentJavaExamples.SamplePlugin1.class=examples.epagent.plugin.SampleStatelessPlugin 100 5
    introscope.epagent.stateless.EPAgentJavaExamples.SamplePlugin1.delayInSeconds=5
    introscope.epagent.stateful.EPAgentJavaExamples.names=SamplePlugin2
    introscope.epagent.stateful.EPAgentJavaExamples.SamplePlugin2.class=examples.epagent.plugin.SampleStatefulPlugin 100 15 5000
拡張機能パッケージの作成
以下の手順に従います。
以下のコマンドを使用して、プラグイン パッケージを作成します。
$ tar cvzf EPAgentJavaExamples.tar.gz bundle.properties lib metadata
bundle.properties
lib/
lib/examples.jar
metadata/
metadata/bundle.json
metadata/description.md
拡張機能パッケージの展開
以下の手順に従います。
APM Command Center (ACC)を使用する
DX APM
の場合:
APM Command Center を使用してインフラストラクチャ エージェントのインストールを管理する場合は、以下の手順を使用します。
以下の手順に従います。
  1. APM Command Center に、新しい拡張機能をインポートします。
  2. インフラストラクチャ エージェント パッケージに、新しい拡張機能を追加します。
  3. パッケージをインフラストラクチャ エージェント インスタンスに適用します。
DX APM
または
の ACC 以外の場合
は、
DX APM
を使用する際に以下の手順を使用します。または、
DX APM
を使用するが、APM Command Center を使用しないでインフラストラクチャ エージェントのインストールを管理する場合:
以下の手順に従います。
  1. 拡張機能の EPAgentJAvaExamples.tar.gz ファイルをインストールの apmia/extensions/deploy ディレクトリに手動でコピーします。
  2. インフラストラクチャ エージェントを再起動します。
    この例で示すように、再起動メッセージがコンソールに表示されます。
    $ cp EPAgentJavaExamples.tar.gz ../../workspace/apmia/extensions/deploy/
    $ cd ../../workspace/apmia
    $ ./APMIACtrl.sh restart
    APM Infrastructure Agent stop in progress...
    APM Infrastructure Agent Stopped
    APM Infrastructure Agent starting in progress...
    APM Infrastructure Agent Started
デプロイの確認
ログ ファイルおよびメトリックを参照して、拡張機能がロードされたことを確認します。
以下の手順に従います。
  1. apmia ディレクトリに移動します。
  2. この例で示すように、IntroscopeAgent.log ファイルで拡張機能プラグイン ロード確認メッセージを確認します。
    $ grep Plugins logs/IntroscopeAgent.log
    3/19/18 01:44:53 PM PDT [INFO] [IntroscopeAgent.InfrastructureAgent Agent] Extension Name ### ->EPAgentTestPlugins
    3/19/18 01:44:53 PM PDT [INFO] [IntroscopeAgent.EPAgent] EPAgent Plugins successfully loaded.
  3. [メトリック ブラウザ]でメトリックを表示します。
    メトリックはデータを表示し、拡張機能がエクスポート データを収集してレポートしていることを確認できます。
  4. EPAgent プラグイン メトリックを調べます。これは EPAgent メトリックの下にあります。
    この図に示すように、プラグインの稼働状況(たとえば平均応答時間など)を評価できます。
    Sample Plug-in Response Time in Metric Browser