• /
  • ログイン
  • 無料アカウント

本書は、お客様のご参考のために原文の英語版を機械翻訳したものです。

英語版と齟齬がある場合、英語版の定めが優先するものとします。より詳しい情報については、本リンクをご参照ください。

問題を作成する

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

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

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

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

  • DatastoreParameters
  • HttpParameters
  • GenericParameters
  • MessageConsumeParameters
  • MessageProduceParameters

これらのビルダーは、 TracedMethod's reportAsExternal 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 は、クライアントおよびサーバーのラッパーを使用しており、エージェントはリクエストからヘッダーを読み取り、レスポンスにヘッダーを追加することができます。

CAT diagram

クライアント・ラッパー

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

エージェントが応答を受け取るクライアントのインバウンド応答ヘッダーを読み取るためには、 InboundHeaders を実装してください。例えば、以下のようになります。

サーバーラッパー

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

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

ラッパーによるCAT実装

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

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

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

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

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

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

    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_QUEUE, TEMP_QUEUE, NAMED_TOPIC, TEMP_TOPIC という列挙型が用意されています。UIでは、名前付きキューや名前付きトピックの名前が表示され、一時的なキューや一時的なトピックの名前は省略されますので、適切な宛先タイプを指定することが重要です。

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

Datastore API

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

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 © 2022 New Relic Inc.