JavaエージェントAPI：アノテーションを使用したインストゥルメント

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

アノテーションはデフォルトで有効になっています

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

この設定は、デフォルトではnewrelic.ymlに含まれていません。アノテーションを無効にする場合は、enable_custom_tracing: false（2つのスペースで始まる）をnewrelic.ymlのcommonセクションで設定します。

@Trace

@Traceでメソッドにアノテーションを付けると、Javaエージェントにそのメソッドの測定が必要であることを伝えます。

メソッドの呼び出しをカスタムトレースとして追加するには、メソッドに@Traceアノテーションを追加します。これらのすべてのアノテーションを含むものとして、classpathにnewrelic-api.jarが表示されることを確認してください。

import com.newrelic.api.agent.Trace;

...

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

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

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

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

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

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

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

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

JavaエージェントAPIコールを使用してウェブブラウザトランザクションとしてバックグラウンドタスクレポートを作成するには、@Trace(dispatcher=true)でアノテーションを付けたメソッドで、次のコールを実行します。

NewRelic.setRequestAndResponse(Request request, Response response)

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

独自の@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.ymlのcommonセクションで使用します。

class_transformer:
  trace_annotation_class_name: com.test.Trace

@Traceのプロパティ

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

@Trace(dispatcher=true)

@Trace(async=true)

@Trace(metricName="YourMetricName")

@Trace(excludeFromTransactionTrace=true)

@Trace(leaf=true)

@Trace(excludeFromTransactionTrace=true, leaf=true)

@TraceLambda

この機能はデフォルトでは無効になっており、明示的に有効にして（例：-Dnewrelic.config.instrumentation.trace_lambda.enabled=true）アノテーションを有効にします。同等の環境変数はNEW_RELIC_INSTRUMENTATION_TRACE_LAMBDA_ENABLEDです。

トランザクショントレースにインストゥルメントされていない時間のブロックが大量にあり、トレース内にラムダ式を含める場合は、パラメーターなしで@TraceLambdaアノテーションを使用できます。

import com.newrelic.api.agent.TraceLambda;

@TraceLambda
class ClassContainingLambdaExpressions() {
  // work
}

ラムダ式は、コンパイル後にクラスを含む静的メソッドになります。デフォルトで、アノテーションパターンに一致する@TraceLambdaアノテーションでマークされたクラス内の静的メソッドは、@Traceアノテーションでマークされます。

@TraceLambdaのプロパティ

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

@TraceLambda(pattern="YourPattern")

@TraceLambda(includeNonstatic="true")

@TraceByReturnType

トレース内に特定の戻り値の型のメソッドを含めるには、@TraceByReturnTypeアノテーションを使用して、戻り値の型をプロパティとして渡すクラスをマークします。アノテーション付きクラスのメソッドは、指定された戻り値の型の1つに一致し、@Traceアノテーションでマークされます。

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  // ...
}

@TraceByReturnTypeのプロパティ

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

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  public String doSomething() { // matches
    // ...
  }

  public Long somethingElse() { // does not match
    // ...
  }
}

パフォーマンスに関する考慮事項

JavaエージェントがJVMに存在する場合、アノテーション付きメソッドにコードを投入します。パフォーマンスヒットは、データベースまたはウェブサービスコールなどの重い操作ではほとんど影響はありませんが、アクセサと呼ばれる1秒に数千回など、頻繁に呼び出されるメソッドでは顕著です。

追加API機能

JavaエージェントAPIとその機能の詳細については、JavaエージェントAPI入門を参照してください。