• ログイン

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 のレスポンスタイムに対しタイマーを開始し、作成する TransactionWeb トランザクションとしてではなく、Other Webトランザクションとして報告する。

NewRelic.setRequestAndReponse(...)

カスタム属性Transactionsに追加する TransactionEvents

NewRelic.addCustomParameter(...)

Transaction がNew Relicに報告されるのを防ぐ。

NewRelic.ignoreTransaction()

アプリケーションの TransactionApdex スコアを計算するときに を除外する

NewRelic.ignoreApdex()

関連ログの参照

アプリケーションのエラーとトレースのコンテキスト内でログを直接表示するには、次のAPI呼び出しを使用してログに注釈を付けます。

ログデータと他のテレメトリーデータの相関に関する詳細は、コンテキストのログに関するドキュメントを参照してください。

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

詳しくは、非同期アプリケーション用の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ヘッダー(traceparenttracestate)の両方を挿入します。明示的にnewrelicヘッダーを除外するようにエージェントが設定されている場合は例外です。

現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。

呼び出し元サービスから送信されたディストリビューティッド(分散)トレーシングヘッダーを受け入れて、ディストリビューティッド(分散)トレースでこれらのサービスをリンクします。

現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。

ディストリビューティッド(分散)トレーシングのヘッダーを受け入れる際のトランスポートタイプを定義するための列挙体の定数を提供するユーティリティクラスを理解します。

分散トレースのカスタム属性SpanEventsに追加

NewRelic.getAgent().getTracedMethod().addCustomAttribute(...)

注意

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

以下を行う場合...

これを使用

呼び出したサービスに送るペイロードを作成する。

現行のトランザクションおよびその他のAPIクラスへのリファレンスの取得の詳細については、リファレンスの取得をご覧ください。

注意

エージェント6.4.0の時点で非推奨になったAPI

最初のサービスから送られたペイロードを受け取る。その結果、これらのサービスを1つのトレース内で結びつけることができる。

現行のトランザクションおよびその他の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を使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

のメトリック名やロールアップメトリック名を表示または変更する TracedMethod

OtherTransaction/allなどのロールアップメトリック名は特定のトランザクションに限定されておらず、すべてのバックグラウンドトランザクションを表しています。)

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 を入手する。

開始して、へのリファレンスを入手する Segment

現在トレースされているメソッドへのリファレンスを入手する。

NewRelic.getAgent().getTracedMethod()

Agent ロガーへのリファレンスを入手する。

NewRelic.getAgent().getLogger()

AgentAgentコンフィギュレーションへのリファレンスを入手する。

NewRelic.getAgent().getConfig()

カスタムメトリックスに対するアグリゲータへのリファレンスを入手する。

NewRelic.getAgent().getAggregator()

カスタムイベントを記録するために、Insights(カスタムイベントを管理する機能の元の名前)への参照を取得する

NewRelic.getAgent().getInsights()

追加のAPI機能

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

以下を行う場合...

これを使用

アプリケーションサーバーやディスパッチャーに対してポート、名前、バージョン情報、もしくはJVMに対してインスタンス名を明示的に設定する。

New Relicが自動的に報告しないエラーを報告する。

NewRelic.noticeError(...)

トランザクション内では、noticeErrorへの最後の呼び出しが優先されます。トランザクションごとに1つのエラーのみが報告されます。

New Relicが自動的にヘッダに追加しない に対する、ブラウザ ページロードタイミングTransactionsを追加する。

カスタムメトリックスを作成および蓄積する。

NewRelic.recordMetric(...).recordResponseTimeMetric(...) 、または .incrementCounter(...)

カスタムイベントを記録

Insights.recordCustomEvent(...)

または、NewRelic.addCustomParameter(...)を使用して、New Relicが定義したTransactionEventタイプにカスタム属性を追加する。

Insightsを使用してNew Relic APIクラスへのリファレンスを取得する方法については、このドキュメントの情報もご覧ください。

その他のAPI使用例

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

Copyright © 2022 New Relic株式会社。

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.