API de l'agent Java : instrumenter utilisant l'annotation

L'agent Java de New Relic fournit plusieurs options pour l'instrumentation personnalisée. L’une de ces options consiste à ajouter les annotations @Trace, @TraceLambda ou @TraceByReturnType de l’API de l’agent Java à votre code d’application. Ce document décrit comment utiliser les annotations.

Les annotations sont activées par défaut

Par défaut, le paramètre de configuration enable_custom_tracing est défini sur true dans l'agent Java, qui est le paramètre requis pour que les annotations @Trace fonctionnent.

Ce paramètre n'est pas inclus dans newrelic.yml par défaut. Si vous souhaitez désactiver les annotations, définissez enable_custom_tracing: false (préfacé par deux espaces) dans la section common de votre newrelic.yml.

@Tracer

L'annotation d'une méthode avec @Trace indique à l'agent Java que des mesures doivent être prises pour cette méthode.

Pour ajouter un appel de méthode en tant que trace personnalisée, ajoutez des annotations @Trace à votre méthode. Assurez-vous que newrelic-api.jar apparaît dans votre classpath car il contient toutes ces annotations.

import com.newrelic.api.agent.Trace;

...

  @Trace
  public void run() {
    // background task
  }

Créer une nouvelle transaction

Si les transactions n'apparaissent pas et que vous souhaitez démarrer une nouvelle transaction, incluez dispatcher=true avec l'annotation @Trace :

@Trace (dispatcher=true)
public void run() {
  // background task
}

Ajoutez des détails à vos transactions

Si votre trace de transaction montre de grands blocs de temps non instrumentés et que vous souhaitez inclure d'autres méthodes dans la trace, vous pouvez utiliser l'annotation @Trace sans paramètre :

@Trace
protected void methodWithinTransaction() {
  // work
}

Convertir une transaction en requête Web

Pour créer un rapport de tâche en arrière-plan sous forme de transaction de navigateur Web avec un appel d'API d'agent Java : Dans la méthode annotée avec @Trace(dispatcher=true), appelez :

NewRelic.setRequestAndResponse(Request request, Response response)

Les arguments sont des implémentations des interfaces Request et Response dans newrelic-api.jar.

Définissez votre propre classe d’annotation @Trace

Si vous définissez votre propre classe d'annotation @Trace, il n'y a aucune dépendance sur newrelic-api.jar. Pour définir la classe :

package com.test;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)

public @interface Trace {
  public static final String NULL = "";
  String metricName() default NULL;
  boolean dispatcher() default false;
  String tracerFactoryName() default NULL;
}

Ensuite, configurez l'agent pour utiliser cette annotation dans la section common de newrelic.yml:

class_transformer:
  trace_annotation_class_name: com.test.Trace

Propriétés pour @Trace

L'annotation @Trace prend en charge les propriétés suivantes.

@Trace(dispatcher=true)

@Trace(async=true)

@Trace(metricName="YourMetricName")

@Trace(excludeFromTransactionTrace=true)

@Trace(leaf=true)

@Trace(excludeFromTransactionTrace=true, leaf=true)

@TraceLambda

Cette fonctionnalité est désactivée par défaut et doit être explicitement activée (par exemple -Dnewrelic.config.instrumentation.trace_lambda.enabled=true) pour que les annotations prennent effet. La variable d’environnement équivalente est NEW_RELIC_INSTRUMENTATION_TRACE_LAMBDA_ENABLED.

Si votre trace de transaction montre de grands blocs de temps non instrumentés et que vous souhaitez inclure des expressions lambda dans la trace, vous pouvez utiliser l'annotation @TraceLambda sans paramètre :

import com.newrelic.api.agent.TraceLambda;

@TraceLambda
class ClassContainingLambdaExpressions() {
  // work
}

Les expressions Lambda deviennent des méthodes statiques de la classe contenante après la compilation. Par défaut, les méthodes statiques dans les classes marquées avec l'annotation @TraceLambda correspondant au modèle d'annotations seront marquées avec l'annotation @Trace .

Propriétés pour @TraceLambda

L'annotation @TraceLambda prend en charge les propriétés suivantes.

@TraceLambda(pattern="YourPattern")

@TraceLambda(includeNonstatic="true")

@TraceByReturnType

Pour inclure des méthodes avec un type de retour particulier dans la trace, vous pouvez utiliser l'annotation @TraceByReturnType pour marquer une classe transmettant les types de retour en tant que propriété. Les méthodes des classes annotées qui correspondent à l’un des types de retour spécifiés seront marquées avec l’annotation @Trace .

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  // ...
}

Propriétés pour @TraceByReturnType

L'annotation @TraceByReturnType prend en charge les propriétés suivantes.

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  public String doSomething() { // matches
    // ...
  }

  public Long somethingElse() { // does not match
    // ...
  }
}

Considérations relatives aux performances

Lorsque l'agent Java est présent dans la JVM, il injectera du code sur les méthodes annotées. La baisse de performances est négligeable dans les opérations lourdes, telles que les appels de bases de données ou de services Web, mais est perceptible dans les méthodes appelées fréquemment, comme un accesseur appelé des milliers de fois par seconde.

Plus de fonctions API

Pour en savoir plus sur l'API de l'agent Java et ses fonctionnalités, consultez l'introduction à l'API de l'agent Java.