agent Java API: appels externes d'instrument, messagerie, datastore, infrastructure Web

L'agent Java de New Relic collecte et rapporte des informations sur les transactions Web et non Web, telles que les tâches en arrière-plan. L'agent doit instrumenter automatiquement le framework pris en charge, sans qu'il soit nécessaire de modifier le code de votre application . Cependant, en plus du code personnalisé et du framework ou de la technologie non répertoriés dans la documentation Compatibilité et exigences de l'agent Java, certaines implémentations du framework pris en charge peuvent nécessiter instrumentation personnalisée.

Ce document décrit comment utiliser l'API de l'agent Java pour instrumenter les appels externes, l'infrastructure de messagerie, le traçage distribué, les magasins de données et l'infrastructure Web. Pour de meilleurs résultats lors de l'utilisation de l'API, assurez-vous que vous disposez de la dernière version agent Java . Plusieurs API utilisées dans les exemples nécessitent l’agent Java 3.36.0 ou supérieur.

API externe

Le External API permet à l'application de signaler les appels de service externes à New Relic. Ces informations apparaissent sur la pageExternal services dans APM. Pour signaler une activité externe HTTP, créez simplement une instance de ExternalParameters à l'aide du générateur HttpParameters et appelez reportAsExternal(ExternalParameters parameters) sur la méthode de trace que vous souhaitez signaler.

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);

Générateurs de paramètres externes

Il existe plusieurs constructeurs pour créer ExternalParameters:

DatastoreParameters
HttpParameters
GenericParameters
MessageConsumeParameters
MessageProduceParameters

Ces constructeurs créent l'objet de paramètre d'entrée pour TracedMethod reportAsExternal l'appel d'API. Ces objets de paramètres sont utilisés pour des choses comme la liaison des appels externes HTTP via le traçage distribué, le traçage des appels externes vers un datastore, le traçage des appels externes vers un datastore avec un traitement de requête lente supplémentaire, ainsi que le traçage des appels entre les producteurs de messages et le consommateur.

Important

Toutes les méthodes de cette classe ont le potentiel d’exposer des informations privées sensibles. Soyez prudent lors de la création des arguments, en accordant une attention particulière aux URI et aux valeurs de chaîne.

API de traçage distribué

L'API de traçage distribué permet à l'agent Java de New Relic de lier les transactions entre les applications qui sont instrumentées soit par l'agent Java de New Relic, soit par un autre instrumentation outil standard ouvert. Il utilise un wrapper pour permettre à l'agent de lire/écrire des en-têtes dans requests.

Enveloppe d'en-têtes

L'agent utilise l'interface Headers pour lire/écrire les en-têtes d'une requête. Le client et le serveur doivent tous deux implémenter cette interface en utilisant les classes de leur framework de communication. Par exemple:

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));
    }
}

Implémentation du traçage distribué à l'aide de wrappers

À l’aide de l’objet wrapper décrit dans la section précédente, vous pouvez permettre à l’ agent Java de signaler les traces côté client et côté serveur. Par exemple:

@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();
}

Dans cet exemple de code, l'agent est configuré pour signaler un appel externe à l'aide du traçage distribué sur le client qui lance la demande. Ces étapes peuvent être résumées comme suit :

Implémentez Headers à l’aide des classes framework sur le client.
Utilisez insertDistributedTraceHeaders(Headers headers) pour que l’agent ajoute les en-têtes appropriés à la demande sortante.

@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");
}

Dans cet exemple de code, l'agent est configuré pour lire les en-têtes de la demande. Ces étapes peuvent être résumées comme suit :

Implémentez Headers à l’aide des classes framework sur le serveur.
Utilisez acceptDistributedTraceHeaders(TransportType transportType, Headers headers) pour lier cette transaction à la transaction qui a effectué l’appel.

API de traçage inter-applications

Important

Le traçage inter-applications est obsolète à partir de la version 7.4.0 de l'agent et sera supprimé dans une future version de l'agent.

Au lieu d'utiliser le traçage inter-application, nous recommandons notre fonctionnalité de traçage distribué . tracing distribué est une amélioration de la fonctionnalité de tracing inter-applicationet est recommandé pour les grands systèmes distribués.

L'de traçage inter- (CAT)applicationAPI permet à l'agent Java de New Relic de lier les transactions à travers le moniteur d'applications par New Relic. L'API utilise des wrappers client et serveur qui permettent à l'agent de lire les en-têtes des requests et d'ajouter des en-têtes aux réponses.

Enveloppes client

Pour que l'agent écrive les en-têtes de requête sortante dans le client qui lance la requête, utilisez l'interface OutboundHeaders . Par exemple:

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;
    }
}

Pour que l'agent lise les en-têtes de réponse entrants dans le client recevant la réponse, implémentez InboundHeaders. Par exemple:

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();
   }
}

Enveloppeurs de serveur

Pour que l'agent obtienne les en-têtes de requête Web, vous devez étendre la classe 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();
    }
}

Pour que l'agent définisse les en-têtes de réponse Web, implémentez l'interface 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;
    }
}

Implémentation CAT à l'aide de wrappers

À l’aide des objets wrapper décrits dans les sections précédentes, vous pouvez permettre à l’agent Java d’effectuer un traçage inter-applications (CAT) côté client et côté serveur. Par exemple:

@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();
}

Dans cet exemple de code, l'agent est configuré pour signaler un appel externe à l'aide de CAT sur le client qui lance la demande. Ces étapes peuvent être résumées comme suit :

Implémentez OutboundHeaders et InboundHeaders à l’aide des classes framework sur le client.
Utilisez addOutboundRequestHeaders(OutboundHeaders outboundHeaders) pour que l’agent ajoute les en-têtes appropriés à la demande sortante.
Créez l'objet ExternalParameters à l'aide du générateur HttpParameters et fournissez des en-têtes de réponse entrants.
Signaler comme une demande externe en utilisant 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;
}

Dans cet exemple de code, l'agent est configuré pour signaler un appel externe à l'aide de CAT sur le serveur qui répond à la demande. Ces étapes peuvent être résumées comme suit :

Implémentez Response et étendez la classe ExtendedRequest à l’aide de classes framework sur le serveur.
Utilisez setWebRequest(ExtendedRequest request) et setWebResponse(Response response) pour convertir la transaction en un réseau de transactions et fournir ensemble à l'agent les en-têtes de demande entrants et un emplacement pour enregistrer les en-têtes sortants.
Il est important d'utiliser setWebRequest(ExtendedRequest request) et setWebResponse(Response response) ensemble, car le nom de la transaction dépend de l'objet de demande et le code de réponse dépend de l'objet de réponse.
Utilisez addOutboundResponseHeaders() pour que l’agent ajoute les en-têtes appropriés à la réponse sortante.
Marquez la fin de la réponse avec un appel à markResponseSent().

API de messagerie

L'API de messagerie permet aux applications de signaler l'interaction avec les courtiers du fichier d'attente des messages. Il s'appuie sur l'API externe en fournissant les MessageConsumerParametersMessage et MessageConsumerParameters.

Cette API génère les métriques nécessaires pour identifier l'interaction du courtier de messages. L'UI utilisera ces métriques pour afficher les données de messagerie, y compris les segments dans les transactions avec l'action et le nombre appropriés (message placé ou message pris), un onglet de messages dédié dans la trace de transaction, et plus encore. La fourniture d'en-têtes entrants et sortants à l'API permet également à l'agent d'ajouter des en-têtes CAT et d'enregistrer les métriques CAT, ce qui permet à l'UI de dessiner des cartes de service qui montrent les connexions entre les applications.

Important

L'API de messagerie repose sur une communication bidirectionnelle entre les producteurs et les consommateurs. Si votre producteur ne reçoit pas d'accusé de réception d'un consommateur, comme dans un modèle de type « fire-and-forget », l'API de messagerie ne reflétera pas avec précision l'interaction avec les courtiers du fichier d'attente des messages.

L'exemple suivant montre comment instrumenter une bibliothèque JMS fictive.

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);
    }
}

Pour simplifier les choses, l’agent suppose que sendMessageToQueue place toujours un message dans une file d’attente nommée. En réalité, un message peut être envoyé à différents types de destinations, notamment des files d'attente nommées, des files d'attente temporaires, des sujets et des sujets temporaires. L'API fournit une énumération pour signaler des messages à différents types de destination : NAMED_QUEUE, TEMP_QUEUE, NAMED_TOPIC, TEMP_TOPIC. Il est important de spécifier le type de destination approprié car l'UI affichera les noms des files d'attente nommées et des rubriques nommées et omettra les noms des files d'attente temporaires et des rubriques temporaires.

Si la bibliothèque est capable de transmettre des en-têtes CAT, un objet OutboundHeaders sera fourni à l'API afin que l'agent puisse ajouter des en-têtes CAT.

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;
    }
}

API de la banque de données

Lorsqu'une méthode de trace est signalée comme un appel externe, l'appel est affiché datastore dans la APM page de base de données . Étant donné que les magasins de données sont externes à l’ application en cours d’exécution, la méthode est signalée comme activité datastore à l’aide de la méthode reportAsExternal(ExternalParameters params). La seule différence est qu'un constructeur différent, DatastoreParameters, est utilisé pour créer l'objet ExternalParameters approprié.

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());

API de banque de données : requête lente

Cet appel d'API fournit le même comportement que l'appel d'API du datastore et l'étend pour permettre le suivi des informations des requêtes lentes . La même méthode reportAsExternal(ExternalParameters params) et le même générateur sont utilisés, mais avec une méthode de générateur supplémentaire.

La création de l’objet ExternalParameters approprié est illustrée ci-dessous :

// 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);
    }
};

API WebFrameworks

L'API WebFrameworks permet à l'agent de signaler des informations d'identification supplémentaires sur l'application.

// 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)

Conseil

Ces valeurs ne peuvent être définies qu'une seule fois. Les appels ultérieurs n'auront aucun effet.

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");
}

Cette traduction automatique est fournie pour votre commodité.

agent Java API: appels externes d'instrument, messagerie, datastore, infrastructure Web

API externe

API externe

Générateurs de paramètres externes

Important

API de traçage distribué

Enveloppe d'en-têtes

Implémentation des en-têtes

Implémentation du traçage distribué à l'aide de wrappers

Traçage distribué : côté client

traçage distribué : côté serveur

API de traçage inter-applications

Important

Enveloppes client

Implémentation d'OutbounderHeaders

Implémentation d'InboundHeaders

Enveloppeurs de serveur

Étendre la classe ExtendedRequest

Implémentation de l'interface de réponse

Implémentation CAT à l'aide de wrappers

Traçage inter-applications : côté client

Traçage inter-applications : côté serveur

API de messagerie

Important

Implémentation de l'API de messagerie

Message avec implémentation des en-têtes CAT

API de la banque de données

implémentation API du datastore

API de banque de données : requête lente

banque de données avec implémentation de requête lente

API WebFrameworks

Conseil

Implémentation de l'API WebFrameworks

Cette traduction automatique est fournie pour votre commodité.

agent Java API: appels externes d'instrument, messagerie, datastore, infrastructure Web

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

Générateurs de paramètres externes

Important

API de traçage distribué

Enveloppe d'en-têtes

Implémentation des en-têtes

Implémentation du traçage distribué à l'aide de wrappers

Traçage distribué : côté client

traçage distribué : côté serveur

API de traçage inter-applications

Important

Enveloppes client

Implémentation d'OutbounderHeaders

Implémentation d'InboundHeaders

Enveloppeurs de serveur

Étendre la classe ExtendedRequest

Implémentation de l'interface de réponse

Implémentation CAT à l'aide de wrappers

Traçage inter-applications : côté client

Traçage inter-applications : côté serveur

API de messagerie

Important

Implémentation de l'API de messagerie

Message avec implémentation des en-têtes CAT

API de la banque de données

implémentation API du datastore

API de banque de données : requête lente

banque de données avec implémentation de requête lente

API WebFrameworks

Conseil

Implémentation de l'API WebFrameworks

API externe