JavaエージェントAPIの使用ガイド

New Relic JavaエージェントAPIを使うことで、 Javaエージェントの機能のコントロール、カスタマイズ、そして拡張が可能です。このAPIは、以下の内容によって構成されています。

com.newrelic.api.agent.NewRelicクラス上の静的メソッド
カスタムインストゥルメンテーションを実装するための@Trace アノテーション
追加の機能を提供するAPIオブジェクトの階層

Javaアプリケーションのカスタムインストゥルメンテーションをセットアップして、より精細なデータを収集するには、このAPIを使用します。このAPIの詳しい情報に関しては、GitHub上のJavadoc一覧を参照してください。

カスタムインストゥルメンテーションをセットアップできるもう1つの手段として、XMLインストゥルメンテーションを使用する方法もあります。XMLを使用した方が簡単な上、アプリケーションのコード修正が必要ありませんが、これにはJavaエージェントAPIのような完全な機能は備わっていません。

重要

APIを使用するにあたって最良の結果を出すには、Javaエージェントのリリースが最新版であることを確認してください。例で使用されているAPIには、Javaエージェント6.4.0以降が必要です。

入手可能なすべてのNew Relic APIを見るには、API入門を参照してください。

APIの使用

APIにアクセスするには、ビルドツールを使用してMaven Centralからダウンロードします。

以下は、${agent.version}エージェントのバージョンに置き換えることができるGradleの例です。

implementation 'com.newrelic.agent.java:newrelic-api:${agent.version}'

エージェントが実行されていなくてもAPIを呼び出すことはできますが、エージェントがアプリケーションをロードするまでメソッドでは何も実行されません。

トランザクション

アプリケーションでTransactionsをインストゥルメントするには、以下のAPIを使用してください。

以下を行う場合...	これを使用
New Relicがトランザクションを自動作成しない場合、`Transaction` を作成する。	報告されるべき作業を含むメソッドで`@Trace(dispatcher = true)`。このアノテーションを既存トランザクションのコンテキスト内のメソッドで使用した場合、新たなトランザクションは開始されず、このメソッドを既存トランザクションに含めることになります。
New Relicが自動的にトレースしないメソッドの経過時間を取得する	時間を計測したいメソッドに`@Trace()`する。
現在の名前を設定する `Transaction`	`NewRelic.setTransactionName(...)`
現在の`Transaction` のレスポンスタイムに対しタイマーを開始し、作成する `Transaction` を `Web` トランザクションとしてではなく、`Other` Webトランザクションとして報告する。	`NewRelic.setRequestAndReponse(...)`
カスタム属性を`Transactions`に追加する `TransactionEvents`	`NewRelic.addCustomParameter(...)`
`enduser.id`エージェント属性を設定して、ユーザー追跡を`Transactions`に追加します。	`NewRelic.setUserId()`
`Transaction` がNew Relicに報告されるのを防ぐ。	`NewRelic.ignoreTransaction()`
アプリケーションの `Transaction`Apdex スコアを計算するときにを除外する	`NewRelic.ignoreApdex()`

非同期の作業をインストゥルメントする

詳しくは、非同期アプリケーション用のJavaエージェントAPIを参照してください。

以下を行う場合...	これを使用
既存の `Transaction` にリンクされている場合の非同期メソッドをトレースする。	`@Trace(async = true)`
現在のスレッド上の `Transaction` に関連する `Token` をリンクする。	`Token.link()` または `Token.linkAndExpire()`
現在の `Token`に関連する `Transaction` を失効させる	`Token.expire()`
`Segment`の時間計測を停止し、その親の一部として報告させる `Transaction`	`Segment.end()`
`Segment`の時間計測を停止し、その親の一部として報告させない `Transaction`	`Segment.ignore()`

ディストリビューティッド（分散）トレーシングAPIの使用

これらのAPIでは、ディストリビューティッド（分散）トレーシングを有効化する必要があります。ディストリビューティッド（分散）トレーシングのすべての設定オプションについては、Javaエージェントの設定をご覧ください。

ディストリビューティッド（分散）トレーシングでは、リクエストが分散システムを経由するパスを見ることができます。以下のコールを利用してディストリビューティッド（分散）トレーシングを実装する一般的な案内については、ディストリビューティッド（分散）トレーシングAPIの使用を参照してください。動作するAPIを確認するには、KafkaでのJavaエージェントのディストリビューティッド（分散）トレーシングAPIの使用をご覧ください。

重要

エージェントのバージョン6.4.0では、6.1.0で導入されたaddCustomAttribute()を除いて、以下のディストリビューティッド（分散）トレーシングAPIが導入されました。非推奨のAPIの代わりに、これらのAPIを使用することを強く推奨します。

以下を行う場合...	これを使用
受信または送信メッセージのタイプ固有のヘッダーについて説明します。	`Headers` `Headers`の提供された実装については、`ConcurrentHashMapHeaders`を使用してください。 Kafkaを使用したDT API使用におけるW3Cトレースコンテキストヘッダーの実装例を参照してください。
ディストリビューティッド（分散）トレーシングのヘッダーを作成して、`Headers`データ構造に挿入します。このAPIは、`newrelic`ヘッダーとW3C Trace Contextヘッダー（`traceparent`と`tracestate`）の両方を挿入します。明示的に`newrelic`ヘッダーを除外するようにエージェントが設定されている場合は例外です。	`Transaction.insertDistributedTraceHeaders(Headers)` 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。
呼び出し元サービスから送信されたディストリビューティッド（分散）トレーシングヘッダーを受け入れて、ディストリビューティッド（分散）トレースでこれらのサービスをリンクします。	`Transaction.acceptDistributedTraceHeaders(TransportType, Headers)` 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。
ディストリビューティッド（分散）トレーシングのヘッダーを受け入れる際のトランスポートタイプを定義するための列挙体の定数を提供するユーティリティクラスを理解します。	`TransportType`
分散トレースのカスタム属性を`SpanEvents`に追加	`NewRelic.getAgent().getTracedMethod().addCustomAttribute(...)`

注意

エージェントのバージョン6.4.0では、以下のディストリビューティッド（分散）トレーシングAPIが非推奨になり、上の表のAPIで置き換えられました。エージェントをアップグレードして、非推奨APIの代わりに新しいAPIを使用することを強く推奨します。

以下を行う場合...	これを使用
呼び出したサービスに送るペイロードを作成する。	`Transaction.createDistributedTracePayload()` 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。注意エージェント6.4.0の時点で非推奨になったAPI
最初のサービスから送られたペイロードを受け取る。その結果、これらのサービスを1つのトレース内で結びつけることができる。	`Transaction.acceptDistributedTracePayload(...)` 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。注意エージェント6.4.0の時点で非推奨になったAPI
サービス接続に使用するペイロード。`text()` コールが、ペイロードのJSON文字列表現を返す。	`DistributedTracePayload.text()` 注意エージェント6.4.0の時点で非推奨になったAPI
サービス接続に使用するペイロード。`httpSafe()` コールが、base64エンコードされたペイロードのJSON文字列表現を返す。	`DistributedTracePayload.httpSafe()` 注意エージェント6.4.0の時点で非推奨になったAPI

クロスアプリケーショントレーシング（CAT）の使用

重要

クロスアプリケーショントレースは、エージェントバージョン7.4.0では非推奨となっており、将来のエージェントバージョンでは削除されます。

クロスアプリケーショントレーシングを使用する代わりに、ディストリビューティッド（分散）トレーシング機能を使用することをお勧めします。ディストリビューティッド（分散）トレーシングはクロスアプリケーショントレーシングの機能を向上させたものであり、大規模な分散システムに適しています。

外部コールを追跡し、クロスアプリケーショントレーシングを追加するには、以下のAPIを使用します。

以下を行う場合...	これを使用
プロプライエタリRPCトランスポートなど、New Relicがデフォルトでサポートしていないカスタムトランスポートチャネルを通してトレースする	`Transaction.getRequestMetadata(), .processRequestMetadata(...), .getResponseMetadata(), .processResponseMetadata(...)` `Transaction`を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。
のメトリック名やロールアップメトリック名を表示または変更する `TracedMethod` （`OtherTransaction/all`などのロールアップメトリック名は特定のトランザクションに限定されておらず、すべてのバックグラウンドトランザクションを表しています。）	`TracedMethod.getMetricName(), .setMetricName(...), .setRollupMetricName(...)` `TracedMethod`を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。
JavaエージェントAPIの `@Trace` アノテーションを使用してトレースされている、外部HTTPサービス、データベースサーバー、メッセージキュー、またその他の外部リソースへのコールを報告する	`TracedMethod.reportAsExternal(...)`は`ExternalParameters`ビルダーを使用して構築された引数を渡します。 `TracedMethod`を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。
New Relicによってインストゥルメントされている外部HTTPまたはJMSサービスと通信している際に、クロスアプリケーショントレーシングを有効化して追加する	`TracedMethod.addOutboundRequestHeaders(...)`ならびに `TracedMethod.reportAsExternal(...)` `TracedMethod`を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。
自動でサポートされないアプリケーションサーバーやディスパッチャーに対しタイミングを追加する。	`Transaction.setRequest(...), Transaction.setResponse(...)`、または`NewRelic.setRequestAndResponse(...)`、および `Transaction.markResponseSent()` `Transaction`を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

New Relic APIクラスへのリファレンスを取得する

他のタスクでは、New RelicのAgentオブジェクトが必要になります。Agentオブジェクトは、以下の機能を提供する複数のオブジェクトを公開します：

以下を行う場合...	これを使用
現在のへのリファレンスを入手する `Transaction`	`NewRelic.getAgent().getTransaction()`
非同期の作業をリンクするための `Token` を入手する。	`NewRelic.getAgent().getTransaction().getToken()`
開始して、へのリファレンスを入手する `Segment`	`NewRelic.getAgent().getTransaction().startSegment()`
現在トレースされているメソッドへのリファレンスを入手する。	`NewRelic.getAgent().getTracedMethod()`
`Agent` ロガーへのリファレンスを入手する。	`NewRelic.getAgent().getLogger()`
`Agent`Agentコンフィギュレーションへのリファレンスを入手する。	`NewRelic.getAgent().getConfig()`
カスタムメトリックスに対するアグリゲータへのリファレンスを入手する。	`NewRelic.getAgent().getAggregator()`
カスタムイベントを記録するために、`Insights`（カスタムイベントを管理する機能の元の名前）への参照を取得する	`NewRelic.getAgent().getInsights()`

追加のAPI機能

以下のAPIは、アプリケーションサーバーの情報設定、エラー報告、ページロードタイミングの情報追加、カスタムメトリックの記録、そしてカスタムイベントの送信など、追加の機能を提供します。

以下を行う場合...	これを使用
アプリケーションサーバーやディスパッチャーに対してポート、名前、バージョン情報、もしくはJVMに対してインスタンス名を明示的に設定する。	`NewRelic.setAppServerPort(...), .setServerInfo(...), and .setInstanceName(...)`
New Relicが自動的に報告しないエラーを報告する。	`NewRelic.noticeError(...)` トランザクション内では、`noticeError`への最後の呼び出しが優先されます。トランザクションごとに1つのエラーのみが報告されます。
独自のカスタム定義フィンガープリントでエラーをグループ化し、`ErrorGroupCallback`インターフェイスの実装を用いて、New Relicに送信されるエラーのグループキーを生成します。フィンガープリントは、エラー受信トレイUIでエラーメッセージのグループ化に使用します。	`public interface ErrorGroupCallback { String generateGroupingString(ErrorData errorData); }`
コールバック関数を使用して、独自のエラーフィンガープリントを設定します。指定されたエラーのグループキーの生成に使用する`ErrorGroupCallback`を登録します。	`NewRelic.setErrorGroupCallback(errorGroupCallback)`
New Relicが自動的にヘッダに追加しないに対する、ブラウザページロードタイミング`Transactions`を追加する。	`NewRelic.getBrowserTimingHeader(), .getBrowserTimingFooter(), .setUserName(String name), .setAccountName(String name), and .setProductName(String name)`
カスタムメトリックスを作成および蓄積する。	`NewRelic.recordMetric(...)`、`.recordResponseTimeMetric(...)` 、または `.incrementCounter(...)`
カスタムイベントを記録	`Insights.recordCustomEvent(...)` または、`NewRelic.addCustomParameter(...)`を使用して、New Relicが定義した`TransactionEvent`タイプにカスタム属性を追加する。 `Insights`を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

その他のAPI使用例

APIの使用における詳しいコード例に関しては、以下のカスタムインストゥルメンテーションに関するNew Relicのドキュメントを参照してください。