JavaエージェントのAPI注記を使用してインストゥルメントする

New RelicのJavaエージェントは、カスタムインストゥルメンテーション向けに複数のオプションを提供しています。こうしたオプションの1つとして、JavaエージェントAPIの@Traceアノテーションをご利用のアプリケーションコードに追加できます。このドキュメントでは、アノテーションの利用方法を解説しています。

アノテーションを利用するには、ソースコードを修正する必要があります。ソースコードの修正を希望しないか、これができない場合は、カスタムインストゥルメンテーションを参照してその他のインストゥルメンテーションオプションを見つけてください。

エージェントをアノテーション用に設定する

デフォルトでは、構成設定enable_custom_tracingのJavaエージェントがtrueに設定されています。これは、@Traceアノテーションを機能させる上で必須の設定です。この設定は、デフォルトではnewrelic.yml含まれていません

この設定を、ご利用の設定ファイルに取り入れる必要があるのは、@Traceアノテーションを完全に無効にしたい場合のみとなります。これを行うには、ご利用のnewrelic.ymlcommonスタンザでenable_custom_tracing: false(最初にスペース2つ)を設定します。

カスタムトレースを検出するには:

  1. 必ず、classpathにnewrelic-api.jarが表示されることを確認してください。
  2. ご利用のコードに@Traceアノテーションを追加します。インストゥルメントしたいメソッドを含む各クラスにおいて、以下をコールします:

    import com.newrelic.api.agent.Trace;
  3. 各ターゲットメソッドに@Traceアノテーションを配置します。

annotation com.newrelic.api.agent.Traceは、newrelic-api.jarにあります。

新規トランザクションを作成する

トランザクションが表示されず、新規トランザクションを開始したい場合は、@Traceアノテーションにdispatcher=trueを含めます:

@Trace (dispatcher=true)
public void run() {
  // background task
}

トランザクショントレースに詳細を追加する

トランザクショントレースにインストゥルメントされていない時間のブロックが大量にあり、トレース内により多くのメソッドを含めたい場合は、パラメーター無しで@Traceアノテーションを使用できます:

@Trace
protected void methodWithinTransaction() {
  // work
}

トランザクションをWebリクエストに変換する

JavaエージェントAPIコールで、バックグラウンドタスクレポートをWebブラウザトランザクションとして行うには:@Trace(dispatcher=true)のアノテーションを注釈されたメソッドで、以下をコールします:

NewRelic.setRequestAndResponse(Request request, Response response)

この引数は、RequestおよびResponseインターフェースをnewrelic-api.jarで実装したものです。

RequestおよびResponseオブジェクトが既に存在している場合でも、このAPIコールを追加する必要があります。

独自の@Traceアノテーションクラスを定義する

独自の@Traceアノテーションクラスを定義した場合、newrelic-api.jarとの依存関係はありません。クラスを定義するには:

package com.test;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)

public @interface Trace {
  public static final String NULL = "";
  String metricName() default NULL;
  boolean dispatcher() default false;
  String tracerFactoryName() default NULL;
}

次に、エージェントを設定して、このアノテーションをnewrelic.ymlcommonセクションで使用できるようにします:

class_transformer:
  trace_annotation_class_name: com.test.Trace

@Traceのプロパティ

@Traceアノテーションは、以下のプロパティに対応しています。

dispatcher
種類: ブール値
デフォルト: false

trueの場合、トランザクションが既に進行中でなければ、エージェントはこの@Traceアノテーションでメソッドに達した際にトランザクションを開始します。トランザクションが既に進行中であれば、新しく作成されるのではなく、進行中のトランザクションにこのアノテーションのメソッドが含まれます。

false(デフォルト)の場合、@Traceアノテーションに達する前にエージェントがトランザクションを開始していないのであれば、メトリクスは記録されません。例えば:

@Trace(dispatcher=true)
async
種類: ブール値
デフォルト: false

trueの場合、このメソッドは非同期としてマークされ、エージェントが既存のトランザクションとリンクした場合はこのメソッドをトレースします。例えば:

@Trace(async=true)

false(デフォルト)の場合、メソッドは非同期としてマークされません。他の@Traceアノテーションが存在し、メソッドが非同期に実行していない場合でも、トレースはされます。

metricName
種類: 文字列
デフォルト: (なし)

このプロパティは、トランザクショントレースとエラーレポートに作用します。デフォルトでは、メトリック名にはクラス名に続いてメソッド名が含まれます。クラスの次にメソッド名が続くのを希望しない場合、このプロパティを使用してメトリック名を変更できます。

metricName@Trace(metricName="YourMessageHere")のように設定した場合、このメソッドに費やした時間はあらゆるトランザクショントレースにおいてYourMessageHereとして表示されます。

ディスパッチャーに加えてmetricName@Trace(metricName="YourMessageHere", dispatcher=true)のように設定した場合、トランザクション名はAPM トランザクションページでYourMessageHereと表示されますが、このメソッドで費やした時間はいずれのトランザクショントレースでもYourMessageHereとは表示されません。

次の例を見てみましょう:

@Trace(metricName="YourMetricName")

トランザクション名の末尾に角括弧 [suffix] を使わないでください。New Relicは名前から自動的に角括弧を除去します。代わりに、必要に応じて丸括弧 suffix、またはその他の記号を使ってください。

excludeFromTransactionTrace
種類: ブール値
デフォルト: false

trueの場合、このメソッドはトランザクショントレースから除外されます。エージェントは、依然としてこのメソッドのメトリックスを収集します。次の例を見てみましょう:

@Trace(excludeFromTransactionTrace=true)
leaf
種類: ブール値
デフォルト: false

リーフトレーサーには、子トレーサーがありません。これは、トレーサーの実行時に他のトレースポイントに遭遇する場合でも、すべての時間をトレーサーに帰属させたい時に便利です。

多くの場合、データベーストレーサーはリーフとして機能することで、インストゥルメントされた外部コールが行われた場合でも、すべての時間がデータベースアクティビティに帰属されます。次の例を見てみましょう:

@Trace(leaf=true)

リーフトレーサーがトランザクショントレースに参加しない場合、エージェントはより少ないオーバーヘッドでトレーサーを作成できます。次の例を見てみましょう:

@Trace(excludeFromTransactionTrace=true, leaf=true)

さらなるAPI関数

JavaエージェントAPIとその関数の詳細については、JavaエージェントAPI入門をご覧ください。

その他のヘルプ

推奨する詳細情報: