• English日本語한국어
  • ログイン今すぐ開始

この機械翻訳は参考用に提供されます。

英語版と翻訳版に矛盾がある場合は、英語版が優先されます。詳細については、こちらのページをご覧ください。

問題を作成する

JavaエージェントAPI。外部呼び出し、メッセージング、データストア、ウェブフレームワークの実装

New Relic の Java エージェントは、 Web トランザクションバックグラウンドタスクなどの非 Web トランザクション の情報を収集して報告します。エージェントは、サポートされているフレームワークを自動的に計測し、アプリケーションのコードを変更する必要はありません。ただし、カスタムコードや 「Compatibility and requirements for the Java agent」 のドキュメントに記載されていないフレームワークやテクノロジーに加えて、サポートされているフレームワークの実装によっては、 カスタムインスツルメンテーション が必要になる場合があります。

このドキュメントでは、 Java エージェント API を使用して、外部コール、メッセージングフレームワーク、 クロスアプリケーショントレース (CAT)、データストア、および Web フレームワークを計測する方法について説明します。API を使用する際に最良の結果を得るためには、 最新の Java エージェント・リリース を持っていることを確認してください。例題で使用されているいくつかのAPIには、Java agent 3.36.0以降が必要です。

外部API

外部 APIを使用すると、アプリケーションは外部サービス呼び出しを New Relic に報告できます。この情報は、APM の [外部サービス] ページに表示されます。HTTP 外部アクティビティをレポートするには、 HttpParametersビルダーを使用してExternalParametersのインスタンスを作成し、レポートするトレース メソッドでreportAsExternal(ExternalParameters parameters)を呼び出すだけです。

外部パラメータービルダー

ExternalParametersを作成するためのビルダーがいくつかあります。

  • DatastoreParameters
  • HttpParameters
  • GenericParameters
  • MessageConsumeParameters
  • MessageProduceParameters

これらのビルダーは、TracedMethodreportAsExternal API 呼び出しの入力パラメーター オブジェクトを作成します。これらのパラメーター オブジェクトは、クロス アプリケーション トレースによる HTTP 外部呼び出しのリンク、データストアへの外部呼び出しのトレース、追加の低速クエリ処理によるデータストアへの外部呼び出しのトレース、メッセージ プロデューサーとコンシューマー間の呼び出しのトレースなどに使用されます。

重要

このクラスのメソッドはすべて、機密性の高い個人情報を公開する可能性があります。引数を作成する際には、URIや文字列値に特に注意してください。

分散型トレーシングAPI

分散型トレーシング API は、New Relic Java エージェントが、New Relic Java エージェントまたは他のオープンインスツルメンテーション標準ツールによってインスツルメンテーションされたアプリケーション間のトランザクションをリンクすることを可能にします。このAPIは、エージェントがリクエストのヘッダーを読み書きできるようにするためのラッパーを使用しています。

ヘッダーのラッパー

エージェントはインターフェースHeadersを使用して、リクエストのヘッダーを読み書きします。クライアントとサーバーの両方が、通信フレームワークのクラスを使用してこのインターフェイスを実装する必要があります。例えば:

ラッパーを使った分散型トレーシングの実装

前のセクションで説明したラッパー・オブジェクトを使って、Javaエージェントがクライアント側とサーバー側でトレースを報告することを可能にすることができます。例えば、以下のようになります。

このサンプルコードでは、リクエストを開始したクライアント上で分散型トレーシングを使用して外部からの呼び出しを報告するようにエージェントが設定されています。これらの手順は、以下のようにまとめられます。

  1. クライアントでフレームワーク クラスを使用してHeadersを実装します。
  2. insertDistributedTraceHeaders(Headers headers)を使用して、エージェントが適切なヘッダーをアウトバウンド リクエストに追加するようにします。

このサンプルコードでは、エージェントはリクエストからヘッダーを読み取るように設定されています。これらの手順をまとめると以下のようになります。

  1. サーバーでフレームワーク クラスを使用してHeadersを実装します。
  2. acceptDistributedTraceHeaders(TransportType transportType, Headers headers)を使用して、このトランザクションを呼び出しを行ったトランザクションにリンクします。

クロスアプリケーショントレースAPI

重要

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

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

クロスアプリケーショントレーシング (CAT) API は、New Relic Java エージェントが New Relic で監視しているアプリケーション間のトランザクションをリンクさせることができます。この API は、クライアントおよびサーバーのラッパーを使用しており、エージェントはリクエストからヘッダーを読み取り、レスポンスにヘッダーを追加することができます。

クライアント・ラッパー

エージェントがリクエストを開始するクライアントでアウトバウンド リクエスト ヘッダーを書き込むには、 OutboundHeadersインターフェースを使用します。例えば:

エージェントが応答を受信するクライアントで受信応答ヘッダーを読み取るには、 InboundHeadersを実装します。例えば:

サーバーラッパー

エージェントがウェブ リクエスト ヘッダーを取得するには、 ExtendedRequestクラスを拡張する必要があります。

エージェントが Web 応答ヘッダーを設定するには、 Responseインターフェースを実装します。

ラッパーによるCAT実装

前のセクションで説明したラッパー・オブジェクトを使って、Javaエージェントがクライアント側とサーバー側でクロス・アプリケーション・トレーシング(CAT)を行えるようにすることができます。例えば、以下のようになります。

このサンプルコードでは、リクエストを開始したクライアントのCATを使用して外部からの電話を報告するようにエージェントが設定されています。これらの手順は、以下のようにまとめられます。

  1. クライアントでフレームワーク クラスを使用してOutboundHeadersInboundHeadersを実装します。
  2. addOutboundRequestHeaders(OutboundHeaders outboundHeaders)を使用して、エージェントが適切なヘッダーをアウトバウンド リクエストに追加するようにします。
  3. HttpParametersビルダーを使用してExternalParametersオブジェクトを作成し、受信応答ヘッダーを提供します。
  4. reportAsExternal(ExternalParameters params)を使用して外部リクエストとして報告します。

このサンプルコードでは、リクエストに応答しているサーバーのCATを使用して、エージェントが外部からの電話を報告するように設定されています。これらの手順をまとめると、以下のようになります。

  1. Responseを実装し、サーバー上のフレームワーク クラスを使用してExtendedRequestクラスを拡張します。

  2. setWebRequest(ExtendedRequest request)setWebResponse(Response response)を使用してトランザクションを Web トランザクションに変換し、一緒にエージェントにインバウンド リクエスト ヘッダーとアウトバウンド ヘッダーを記録する場所を提供します。

    トランザクション名はリクエスト オブジェクトに依存し、レスポンス コードはレスポンス オブジェクトに依存するため、 setWebRequest(ExtendedRequest request)setWebResponse(Response response)の両方を一緒に使用することが重要です。

  3. addOutboundResponseHeaders()を使用して、エージェントが適切なヘッダーを送信応答に追加するようにします。

  4. markResponseSent()への呼び出しで応答の終わりをマークします。

Messaging API

メッセージング API を使用すると、アプリケーションはメッセージ キュー ブローカーとのやり取りをレポートできます。MessageConsumerParametersMessageMessageConsumerParametersを提供することで、外部 API の上に構築されます。

このAPIは、メッセージ・ブローカー・インタラクションを識別するために必要なメトリクスを生成します。UIはこれらのメトリクスを使用して、適切なアクションとカウント(メッセージプット、またはメッセージテイク)を持つトランザクション内のセグメント、トランザクショントレース内の専用メッセージタブなど、メッセージングデータを表示します。APIにインバウンドおよびアウトバウンドヘッダを提供することで、エージェントはCATヘッダを追加し、CATメトリクスを記録することができます。これにより、UIはアプリケーション間の接続を示す サービスマップ を描くことができます。

重要

メッセージングAPIは、プロデューサとコンシューマの間の双方向通信に依存しています。Fire and Forgetパターンのように、プロデューサーがコンシューマーから確認応答を受け取らない場合、メッセージングAPIはメッセージキュー・ブローカーとのやり取りを正確に反映しません。

以下の例は、架空のJMSライブラリをインストルメント化する方法を示しています。

簡単にするために、エージェントは、 sendMessageToQueueが常にメッセージを名前付きキューに入れると想定しています。実際には、名前付きキュー、一時キュー、トピック、一時トピックなど、さまざまな種類の宛先にメッセージを送信できます。API は、メッセージをさまざまな宛先タイプ ( NAMED_QUEUETEMP_QUEUENAMED_TOPICTEMP_TOPIC ) に報告する列挙型を提供します。UI には名前付きキューと名前付きトピックの名前が表示され、一時キューと一時トピックの名前は省略されるため、適切な宛先タイプを指定することが重要です。

ライブラリが CAT ヘッダーを送信できる場合、エージェントが CAT ヘッダーを追加できるように、 OutboundHeadersオブジェクトが API に提供されます。

Datastore API

トレースされたメソッドが外部データストア呼び出しとして報告されると、その呼び出しは APMデータベースページに表示されます。データストアは実行中のアプリケーションの外部にあるため、メソッドはreportAsExternal(ExternalParameters params)メソッドを使用してデータストア アクティビティとしてレポートされます。唯一の違いは、別のビルダーDatastoreParametersを使用して適切なExternalParametersオブジェクトを作成することです。

Datastore API。クエリが遅い

この API 呼び出しは、 Datastore API 呼び出しと同じ動作を提供し、遅いクエリ情報を追跡できるように拡張します。同じreportAsExternal(ExternalParameters params)メソッドとビルダーが使用されますが、ビルダー メソッドが追加されています。

WebFrameworksのAPI

WebFrameworks API では、エージェントが アプリケーションに関する追加の識別情報を報告することができます。

// Set the dispatcher name and version which is reported to APM.
// The dispatcherName is intended to represent the type of server that this
// application is running on such as: Tomcat, Jetty, Netty, etc.
NewRelic.setServerInfo(String dispatcherName, String version)
// Set the app server port which is reported to APM.
NewRelic.setAppServerPort(int port)
// Set the instance name in the environment.
// A single host:port may support multiple JVM instances.
// The instance name is intended to help identify a specific JVM instance.
NewRelic.setInstanceName(String instanceName)

ヒント

これらの値は一度しか設定できません。それ以降の呼び出しには影響しません。

Copyright © 2024 New Relic Inc.

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