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

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

このドキュメントでは、Java エージェントAPIを使用して、外部呼び出し、メッセージングフレームワーク、ディストリビューティッド（分散）トレーシング、データストア、および Web フレームワークを計測する方法について説明します。 API使用時に最良の結果を得るには、最新の Java エージェントリリースを使用していることを確認してください。例で使用されるいくつかのAPIには、Javaagent 3.36.0 以上が必要です。

外部API

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

String library = "HttpClient"; // a user-recognizable name for the library that is being used
URI uri = request.getURI();    // the URI that is being requested
String procedure = "execute";  // these are typically named after the method in the library that's being instrumented

// construct external parameters
ExternalParameters params = HttpParameters
    .library(library)
    .uri(uri)
    .procedure(procedure)
    .inboundHeaders(inboundHeaders)
    .build();

// report the current method as doing external activity
NewRelic.getAgent().getTracedMethod().reportAsExternal(params);

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

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

DatastoreParameters
HttpParameters
GenericParameters
MessageConsumeParameters
MessageProduceParameters

これらのビルダーは、 TracedMethodのreportAsExternal API コールの入力コンテナーオブジェクトを作成します。これらの論点オブジェクトは、ディストリビューティッド（分散）トレーシングを介した HTTP 外部呼び出しのリンク、データストアへの外部呼び出しのトレース、追加の低速処理を伴うデータストアへの外部呼び出しのトレース、メッセージプロデューサー間の呼び出しのトレースなどに使用されます。そして消費者。

重要

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

分散型トレーシングAPI

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

ヘッダーのラッパー

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

class HeadersWrapper implements Headers {
    private final HttpMessage delegate;

    public HeadersWrapper(HttpMessage request) {
        this.delegate = request;
    }

    @Override
    public void setHeader(String name, String value) {
        delegate.setHeader(name, value);
    }

    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }

    @Override
    public String getHeader(String name) {
        return delegate.getFirstHeader(name).getValue();
    }

    @Override
    public Collection<String> getHeaders(String name) {
        return Arrays.stream(delegate.getHeaders(name))
                .map(NameValuePair::getValue)
                .collect(Collectors.toList());
    }

    @Override
    public void addHeader(String name, String value) {
        delegate.addHeader(name, value);
    }

    @Override
    public Collection<String> getHeaderNames() {
        return Arrays.stream(delegate.getAllHeaders())
                .map(NameValuePair::getName)
                .collect(Collectors.toSet());
    }

    @Override
    public boolean containsHeader(String name) {
        return Arrays.stream(delegate.getAllHeaders())
                .map(NameValuePair::getName)
                .anyMatch(headerName -> headerName.equals(name));
    }
}

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

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

@Trace
public int makeExternalCall(URI uri) throws IOException {
    HttpUriRequest request = RequestBuilder.get().setUri(uri).build();

    // Wrap the outbound Request object
    Headers outboundHeaders = new HeadersWrapper(request);

    // Obtain a reference to the current transaction
    Transaction transaction = NewRelic.getAgent().getTransaction();
    // Add headers for outbound external request
    transaction.insertDistributedTraceHeaders(outboundHeaders);

    CloseableHttpClient connection = HttpClientBuilder.create().build();
    CloseableHttpResponse response = connection.execute(request);

    return response.getStatusLine().getStatusCode();
}

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

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

@Trace(dispatcher = true)
@Override
public Response serve(IHTTPSession request) {
    // Obtain a reference to the current Transaction
    Transaction tx = NewRelic.getAgent().getTransaction();

    // Set the name of the current transaction
    NewRelic.setTransactionName("Custom", "ExternalHTTPServer");

    // Wrap the Request object
    Headers req = new HeadersWrapper(request);

    // Set the request for the current transaction and convert it into a web transaction
    tx.acceptDistributedTraceHeaders(TransportType.HTTP, req);

    queryDB();

    return newFixedLengthResponse("<html><body><h1>SuccessfulResponse</h1>\n</body></html>\n");
}

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

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

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

重要

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

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

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

クライアント・ラッパー

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

class OutboundWrapper implements OutboundHeaders {
    private final HttpUriRequest delegate;

    // OutboundHeaders is implemented by delegating to the library's request object
    public OutboundWrapper(HttpUriRequest request) {
        this.delegate = request;
    }

    // This allows the agent to add the correct headers to the HTTP request
    @Override
    public void setHeader(String name, String value) {
        delegate.addHeader(name, value);
    }

    // New Relic CAT specifies different header names for HTTP and MESSAGE
    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }
}

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

class InboundWrapper implements InboundHeaders {
    private final CloseableHttpResponse responseHeaders;

    // OutboundHeaders is implemented by delegating to the library's response object
    public InboundWrapper(CloseableHttpResponse responseHeaders) {
        this.responseHeaders = responseHeaders;
    }

    // New Relic CAT specifies different header names for HTTP and MESSAGE
    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }

    // this allows the agent to read the correct headers from the HTTP response
   @Override
   public String getHeader(String name) {
       return responseHeaders.getFirstHeader(name).getValue();
   }
}

サーバーラッパー

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

// Extend ExtendedRequest class to create a wrapper for the Request object
class RequestWrapper extends ExtendedRequest {
    private IHTTPSession session;

    public RequestWrapper(IHTTPSession session) {
        super();
        this.session = session;
    }

    @Override
    public String getRequestURI() {
        return session.getUri();
    }

    @Override
    public String getHeader(String name) {
        return session.getHeaders().get(name);
    }

    @Override
    public String getRemoteUser() {
        return null;
    }

    @SuppressWarnings("rawtypes")
    @Override
    public Enumeration getParameterNames() {
        return Collections.enumeration(session.getParms().keySet());
    }

    @Override
    public String[] getParameterValues(String name) {
        return new String[] { session.getParms().get(name) };
    }

    @Override
    public Object getAttribute(String name) {
        return null;
    }

    @Override
    public String getCookieValue(String name) {
        return null;
    }

    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }

    @Override
    public String getMethod() {
        return session.getMethod().toString();
    }
}

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

// Implement Response interface to create a wrapper for the outgoing Response object
public class ResponseWrapper implements com.newrelic.api.agent.Response {

    private final Response httpResponse;

    public ResponseWrapper(Response httpResponse) {
        this.httpResponse = httpResponse;
    }

    @Override
    public int getStatus() throws Exception {
        return 200;
    }

    @Override
    public String getStatusMessage() throws Exception {
        return null;
    }

    @Override
    public void setHeader(String name, String value) {
        httpResponse.addHeader(name, value);
    }

    @Override
    public String getContentType() {
        return "";
    }

    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }
}

ラッパーによるCAT実装

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

@Trace
public int makeExternalCall(URI uri) throws IOException {
    String library = "HTTPClient";
    String procedure = "Execute";
    HttpUriRequest request = RequestBuilder.get().setUri(uri).build();

    // Wrap the outbound Request object
    OutboundWrapper outboundHeaders = new OutboundWrapper(request);
    // Obtain a reference to the method currently being traced
    TracedMethod tracedMethod = NewRelic.getAgent().getTracedMethod();
    // Add headers for outbound external request
    tracedMethod.addOutboundRequestHeaders(outboundHeaders);

    CloseableHttpClient connection = HttpClientBuilder.create().build();
    CloseableHttpResponse response = connection.execute(request);

    // Wrap the incoming Response object
    InboundWrapper inboundHeaders = new InboundWrapper(response);
    // Create an input parameter object for a call to an external HTTP service
    ExternalParameters params = HttpParameters
            .library(library)
            .uri(uri)
            .procedure(procedure)
            .inboundHeaders(inboundHeaders)
            .build();

    // Report a call to an external HTTP service
    tracedMethod.reportAsExternal(params);

    return response.getStatusLine().getStatusCode();
}

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

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

@Trace(dispatcher = true)
@Override
public Response serve(IHTTPSession session) {
    // Obtain a reference to the current Transaction
    Transaction tx = NewRelic.getAgent().getTransaction();

    // Set the name of the current transaction
    NewRelic.setTransactionName("Custom", "ExternalHTTPServer");

    // Wrap the Request object
    ExtendedRequest req = new RequestWrapper(session);

    // Set the request for the current transaction and convert it into a web transaction
    tx.setWebRequest(req);

    queryDB();
    Response res = newFixedLengthResponse("<html><body><h1>SuccessfulResponse</h1>\n</body></html>\n");

    // Set the response for the current transaction and convert it into a web transaction
    tx.setWebResponse(new ResponseWrapper(res));

    // Instruct the transaction to write the outbound response headers
    tx.addOutboundResponseHeaders();

    // Mark the time when the response left the server
    tx.markResponseSent();

    return res;
}

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

Responseを実装し、サーバー上のフレームワーククラスを使用してExtendedRequestクラスを拡張します。
setWebRequest(ExtendedRequest request)とsetWebResponse(Response response)を使用してトランザクションを Web トランザクションに変換し、一緒にエージェントにインバウンドリクエストヘッダーとアウトバウンドヘッダーを記録する場所を提供します。
トランザクション名はリクエストオブジェクトに依存し、レスポンスコードはレスポンスオブジェクトに依存するため、 setWebRequest(ExtendedRequest request)とsetWebResponse(Response response)の両方を一緒に使用することが重要です。
addOutboundResponseHeaders()を使用して、エージェントが適切なヘッダーを送信応答に追加するようにします。
markResponseSent()への呼び出しで応答の終わりをマークします。

Messaging API

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

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

重要

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

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

public class MessageProducer {
    // instrument the method that puts messages on a queue
    @Trace
    public void sendMessageToQueue(Message message) {
        ExternalParameters messageProduceParameters = MessageProduceParameters.library("JMS")
                .destinationType(DestinationType.NAMED_QUEUE)
                .destinationName(message.getJMSDestination())
                .outboundHeaders(new OutboundWrapper(message))
                .build();

        NewRelic.getAgent().getTracedMethod().reportAsExternal(messageProduceParameters);
    }
}

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

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

public class MessageConsumer {
    @Trace
    public Message messageReceive() {
        ExternalParameters messageConsumeParameters = MessageConsumeParameters.library("JMS")
                .destinationType(DestinationType.NAMED_QUEUE)
                .destinationName(message.getJMSDestination())
                .inboundHeaders(new InboundWrapper(message))
                .build();

        NewRelic.getAgent().getTracedMethod().reportAsExternal(messageConsumeParameters);

        return message;
    }
}

Datastore API

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

TracedMethod tracedMethod = NewRelic.getAgent().getTracedMethod();
    tracedMethod.reportAsExternal(
        DatastoreParameters
        .product("sqlite") // the datastore vendor
        .collection("test.db") // the name of the collection (or table for SQL databases)
        .operation("select") // the operation being performed, for example "SELECT" or "UPDATE" for SQL databases
        .instance("localhost", 8080) // the datastore instance information - generally can be found as part of the connection
        .databaseName("test.db") // may be null, indicating no keyspace for the command
        .build());

Datastore API。クエリが遅い

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

適切なExternalParametersオブジェクトの作成を以下に示します。

// Reporting a method as doing datastore activity
TracedMethod tracedMethod = NewRelic.getAgent().getTracedMethod();
tracedMethod.reportAsExternal(
    DatastoreParameters
        .product("sqlite")           // the datastore vendor
        .collection("test.db")       // the name of the collection (or table for SQL databases)
        .operation("select")         // the operation being performed, for example "SELECT" or "UPDATE" for SQL databases
        .instance("localhost", 8080) // the datastore instance information - generally can be found as part of the connection
        .databaseName("test.db")     // may be null, indicating no keyspace for the command
        .slowQuery(rawQuery, QUERY_CONVERTER)
        .build());

private static QueryConverter<String> QUERY_CONVERTER = new QueryConverter<String>() {

    @Override
    public String toRawQueryString(String statement) {
        // Do work to transform raw query object to string
        return statement;
    }

    @Override
    public String toObfuscatedQueryString(String statement) {
        // Do work to remove any sensitive information here
        return obfuscateQuery(statement);
    }
};

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)

ヒント

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

public NewRelicApiClient() throws IOException, URISyntaxException {
    super(8080);

    // Set Dispatcher name and version.
    NewRelic.setServerInfo("NanoHttp", "2.3.1");

    // Set Appserver port for jvm identification
    NewRelic.setAppServerPort(8080);

    // Set JVM instance name
    NewRelic.setInstanceName("Client:8080");

    start(NanoHTTPD.SOCKET_READ_TIMEOUT, false);
    System.out.println("\nRunning on http://localhost:8080/ \n");
}

この機械翻訳は、参考として提供されています。

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

外部API

外部API

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

重要

分散型トレーシングAPI

ヘッダーのラッパー

ヘッダーの実装

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

分散型トレーシング。クライアントサイド

分散型トレーシング。サーバーサイド

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

重要

クライアント・ラッパー

OutbounderHeadersの実装

InboundHeadersの実装

サーバーラッパー

ExtendedRequestクラスの拡張

レスポンスインターフェースの実装

ラッパーによるCAT実装

クロスアプリケーショントレースクライアントサイド

クロスアプリケーショントレースサーバーサイド

Messaging API

重要

Messaging APIの実装

CATヘッダー実装のメッセージ

Datastore API

Datastore APIの実装

Datastore API。クエリが遅い

クエリの実装が遅いデータストア

WebFrameworksのAPI

ヒント

WebFrameworksのAPI実装

この機械翻訳は、参考として提供されています。

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

外部API .css-21sua1{background:none;border:none;width:0;padding:0;}

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

重要

分散型トレーシングAPI

ヘッダーのラッパー

ヘッダーの実装

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

分散型トレーシング。クライアントサイド

分散型トレーシング。サーバーサイド

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

重要

クライアント・ラッパー

OutbounderHeadersの実装

InboundHeadersの実装

サーバーラッパー

ExtendedRequestクラスの拡張

レスポンスインターフェースの実装

ラッパーによるCAT実装

クロスアプリケーショントレースクライアントサイド

クロスアプリケーショントレースサーバーサイド

Messaging API

重要

Messaging APIの実装

CATヘッダー実装のメッセージ

Datastore API

Datastore APIの実装

Datastore API。クエリが遅い

クエリの実装が遅いデータストア

WebFrameworksのAPI

ヒント

WebFrameworksのAPI実装

外部API