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

New Relic JavaエージェントAPIを使うことで、APM 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クラスにアクセスするには、アプリケーションのクラスパスにnewrelic-api.jarを追加してください。このjarは、New Relic Javaエージェントのインストレーションzipファイル内にあります。APIは、Javaエージェントが実行中でないときにコールできます。APIメソッドは単なるスタブで、実装はJavaエージェントがクラスを読み込んだときに追加されます。

トランザクション

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

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

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

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

以下を行う場合...	これを使用
非同期メソッドが既存の`Transaction`にリンクされている場合、そのメソッドをトレースする...	`@Trace(async = true)`
現在のスレッド上の`Token`に関連する`Transaction`をリンクする...	`Token.link()`または`Token.linkAndExpire()`
現在の`Transaction`に関連する`Token`を期限切れにする...	`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`データ構造に挿入します。このAPIは、`newrelic`ヘッダーとW3C Trace Contextヘッダー（`traceparent`と`tracestate`）の両方を挿入します。明示的にnewrelicヘッダーを除外するようにエージェントが設定`されている場合は例外です。`	`Transaction.insertDistributedTraceHeaders(Headers)` 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。
呼び出し元サービスから送信されたディストリビューティッド（分散）トレーシングヘッダーを受け入れて、ディストリビューティッド（分散）トレースでこれらのサービスをリンクします。	`Transaction.acceptDistributedTraceHeaders(TransportType, Headers)` 現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。
受信または送信メッセージのタイプ固有のヘッダー。提供されている`Headers`の実装には、`ConcurrentHashMapHeaders`を使用します。	`Headers`
ディストリビューティッド（分散）トレーシングのヘッダーを受け入れる際のトランスポートタイプを定義するための列挙体の定数を提供するユーティリティクラス。	`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）の使用

外部コールを追跡し、クロスアプリケーショントレーシングを追加するには、以下の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サービス、データベースサーバー、メッセージキュー、またはその他の外部リソースへのコールを報告する	`ExternalParameters`ビルダを使用して作成された引数を`TracedMethod.reportAsExternal（...）`に渡す。 `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のエージェントオブジェクトが必要になります。エージェントオブジェクトは、以下の機能を提供する複数のオブジェクトを公開します：

以下を行う場合...	これを使用
現在の`Transaction`へのリファレンスを取得する	`NewRelic.getAgent().getTransaction()`
非同期作業をリンクする`Token`を取得する	`NewRelic.getAgent().getTransaction().getToken()`
起動して、`Segment`へのリファレンスを取得する	`NewRelic.getAgent().getTransaction().startSegment()`
現在トレースされているメソッドへのリファレンスを入手する。	`NewRelic.getAgent().getTracedMethod()`
`Agent`ロガーへのリファレンスを取得する	`NewRelic.getAgent().getLogger()`
`Agent`の設定へのリファレンスを取得する	`NewRelic.getAgent().getConfig()`
カスタムメトリックスに対するアグリゲータへのリファレンスを入手する。	`NewRelic.getAgent().getAggregator()`
カスタムイベントを記録するために、`Insight`へのリファレンスを取得する	`NewRelic.getAgent().getInsights()`

追加のAPI機能

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

以下を行う場合...	これを使用
アプリケーションサーバーやディスパッチャーに対してポート、名前、バージョン情報、もしくはJVMに対してインスタンス名を明示的に設定する。	`NewRelic.setAppServerPort(...), .setServerInfo(...), and .setInstanceName(...)`
New Relicが自動的に報告しないエラーを報告する。	`NewRelic.noticeError(...)` トランザクション内では、`noticeError`への最初の呼び出しが優先されます。トランザクションごとに1つのエラーのみが報告されます。
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`タイプにカスタムアトリビュートを追加する。 `Insight`を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

その他のAPI使用例

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

その他のヘルプ

さらに支援が必要な場合は、これらのサポートと学習リソースを確認してください：

Explorers Hubを参照して、コミュニティから支援を受け、ディスカッションに参加してください。
当社のサイトで回答を見つけ、サポートポータルの使用方法について学びます。
Linux、Windows、およびmacOSのトラブルシューティングツールであるNew Relic Diagnosticsを実行します。
New Relicのデータセキュリティとライセンスドキュメントを見直してください。