JavaエージェントAPIを用いた監視

Javaエージェントを用いたAPMインサイト監視はフレームワークやライブラリーを一般的に用います。

JavaエージェントAPIを用いて、特定のアプリケーションにおける監視パラメーターのカスタムメトリクスを追跡できます。これはコンテキストのデバッグに役立ちます。

JavaエージェントAPIは監視対象のメソッドに注釈をつけることができ、さらにメソッドやコンポーネントに名前をつけて、その特定やトラブルシュートを簡単にすることができます。

必要条件：

JavaエージェントAPIを使った監視を行う前に次の要件を確認してください。

Javaバージョン1.6以上を起動すること。
JavaエージェントzipファイルにあるAPI JAR (Java ARchieved) file (apminsight-javaagent-api.jar)をダウンロードすること。（Site24x7アカウントからJavaエージェントをダウンロードできます。）
API Jarファイルがアプリケーションビルドパスで利用可能で、そのアプリケーションと同じ環境に置けること（好ましいロケーション：WEB-INF/lib）
プロジェクトへの参考としてJavaエージェントAPI成果物を追加するMavenユーザーは、こちらを参照してください。

できること：

JavaエージェントAPIでできることは次の項目があります。

カスタムインストルメンテーション
例外の追跡
コードブロックの監視
追跡のためのカスタムパラメーターの追加
トランザクション名のカスタマイズ

1. JavaエージェントAPIを用いたカスタムインストルメンテーション：

アプリケーションフレームワークで定義されているデフォルトのクラスやメソッドは別として、カスタムインストルメンテーションを用いて独自のアプリケーション固有のメソッドやクラスを監視できます。

カスタムインストルメンテーションはJavaエージェントAPIか設定ファイルを用いて行うことができます。

JavaエージェントAPIはメソッドやクラスの計測のための注意付けをすることができます。

2. JavaエージェントAPI (バージョン3.5)を用いた例外の追跡：

エージェントによって例外の追跡が可能ですが、JavaエージェントAPIは監視/デバッグの目的で、より良い可視化とオプションのカスタマイズを提供します。

一般的にエージェントはログやアンコートから例外をキャプチャーします。そして大抵の場合、開発者は例外を取得し、それらを伝播せずにそれらをコード内で処理する傾向があります。このAPIを用いてそのような例外を追跡することができ、JavaエージェントAPIによりカスタムメッセージや実際のスロー可能な例外オブジェクトや発生時の例外の追跡を表示できます。

アプリケーションコードにAPIを追加すると、エラーメッセージや例外を表示できます。エージェントが追跡を行い、各トランザクションを関連付けます。

APMインサイトの例外タブでこれらの例外についてみることができます。

構文：

CustomTracker.trackException(String message, Throwable throwable)
CustomTracker.trackException(Throwable throwable)

サンプル入力：

サンプル結果：

3. ブロックコードの監視：

JavaエージェントAPIを用いてメソッドレベルでの特定のブロックコードを監視することができます。ブロックコードを監視することで、カスタムトラッカーや停止メソッドの新しいオブジェクト内にコードブロックを囲むことができます。

ブロックの名前、コンポーネント、例外を関連付けることができます。今のところ、名前ではスペース、ハイフン、アンダースコア、英数字をサポートしています。ブロック名は64文字までで、コンポーネント名は32文字までという制限があります。

新しいカスタムトラッカーオブジェクトを作成すると、監視されているブロックの開始点がマークされ、ブロックの終了点は<trackerObj>.stop() メソッドを用いてマークされます。ブロックにいくつかの例外がある場合は、例外オブジェクトが停止メソッドに送られます。これにより自動的に例外が対応するブロックやトランザクションに関連付けられます。

構文:

CustomTracker tracker = new CustomTracker("block__name");

CustomTracker tracker = new CustomTracker("block_name", "component_name");

tracker.stop();

tracker.stop(exceptionObj);

例：

CustomTracker tracker = new CustomTracker("operation_"+opId);
try {
// some operations
tracker.stop();
}
catch (NumberFormatException nfe) {
tracker.stop(nfe);
// some rescue operations
}

サンプル結果：

4.追跡のためのカスタムパラメーターの追加

追跡をより有用にするために、トランザクション追跡のコンテキストを特定する追加パラメーターを設定することができます。コンテキストのメトリクスはトランザクション追跡の情報をを識別するのに、セッションID、ユーザーID、メソッドパラメーターのいずれかを用います。最大で10までのパラメーターをトランザクションの追跡に追加することができ、これらパラメーターは追跡サマリータブ内で確認できます。

カスタムパラメーターを追加するには次の構文を入力してください。

構文：

CustomTracker.addParameter("key", value);

Key - Name of the parameter
Value - Parameter of the value. It can be of any type, internally agent converts them to string using Object.toString()

例：

import com.manageengine.apminsight.agent.api.CustomTracker;
....
{
....
CustomTracker.addParameter("User ID", user_id);
....
}

サンプル結果

5. トランザクション名のカスタマイズ

簡単な追跡や特定に用いるトランザクション名に一意な名前を設定したい場合、エージェントAPIを使用してください。

構文

CustomTracker.setTransactionName("name");
name - desired name for the transaction

例：

import com.manageengine.apminsight.agent.api.CustomTracker;
....
{
....
CustomTracker.setTransactionName("reseller/search");
....
}