• ログイン今すぐ開始

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

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

重要

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

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

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

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

これらのすべてのアノテーションを含むものとして、classpathにnewrelic-api.jarが表示されることを確認してください。

@Trace

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

メソッドの呼び出しをカスタムトレースとして追加するには、メソッドに@Traceアノテーションを追加します。

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.jarRequestおよびResponseのインタフェースの実装です。

重要

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アノテーションは、以下のプロパティに対応しています。

@TraceLambda

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

import com.newrelic.api.agent.TraceLambda;
@TraceLambda
class ClassContainingLambdaExpressions() {
// work
}

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

@TraceLambdaのプロパティ

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

@TraceByReturnType

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

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

@TraceByReturnTypeのプロパティ

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

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

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

注意

すべてのメソッドをインストゥルメントしないでください。パフォーマンスが低下し、メトリクスのグループ化問題につながる可能性があります。

追加API機能

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

Copyright © 2022 New Relic株式会社。