Exemples d'instrumentation XML Java

Pour votre application Java monitorée par New Relic, une méthode d'instrumentation personnalisée consiste à utiliser un fichier XML qui répertorie les méthodes et les classes que vous souhaitez . Cette documentation montre un exemple de fichier d'instrumentation XML. Pour plus d'informations, voir Instrumentation Java par XML.

Modifier le fichier XML dans UI

Pour modifier votre fichier XML directement depuis l’UI de New Relic : accédez one.newrelic.com > All capabilities > APM & services > (select an app) > Settings > Instrumentation à. À partir d'ici vous pouvez :

Téléchargez un exemple de fichier XML.
Sélectionnez un fichier XML existant ou modifiez-le.
Rechercher l'historique de l'instrumentation.

Format de fichier XML

Le format de fichier XML inclut les nœuds racine et enfants.

Prudence

N'instrumenter pas toutes vos méthodes, car cela peut entraîner un problème de regroupement métrique.

Le nœud racine d’un fichier XML est extension. Il peut avoir trois attributs différents :

Valeur	Définition
`name`	Un nom unique mais descriptif identifiant votre extension XML.
`enabled`	Identifie si l'extension sera lue par l'agent Java. La valeur par défaut est `true`. Si `false`, New Relic ignorera l'extension.
`version`	La version de l'extension. Si deux extensions ont le même nom, seule l'extension avec la version la plus élevée sera utilisée.

Le pointcut est un nœud enfant de instrumentation et peut avoir plusieurs attributs. De plus, un pointcut peut avoir plusieurs nœuds enfants différents.

Valeur	Définition
`transactionStartPoint`	Si une transaction n'est pas déjà en cours lorsque ce point de coupure est atteint, alors une transaction sera démarrée. Si une transaction est déjà en cours, cette transaction continuera. Une nouvelle transaction ne sera pas créée.
`metricNameFormat`	Le format de nom à utiliser pour une métrique. S'il n'est pas présent, la valeur par défaut sera le nom de la classe suivi du nom de la méthode. Vous ne pouvez définir le `metricNameFormat` que sur les coupes ponctuelles où `transactionStartPoint` est défini sur `false`.
`excludeFromTransactionTrace`	Lorsque `true` la trace de transaction ne sera pas fournie si ce pointcut initie la transaction. Si le point de coupure est atteint au milieu d'une transaction, la trace de transaction sera toujours présente, mais cette méthode sera exclue du graphique d'appel.
`ignoreTransaction`	Lorsque `true` la transaction entière sera ignorée.
`transactionType`	Définit le type de transaction. Les valeurs possibles sont `background` (par défaut, signalé comme une transaction non Web) et `web` (signalée comme une transaction Web).

Un pointcut peut avoir plusieurs nœuds enfants différents :

Valeur	Définition
`nameTransaction`	Si cet élément est présent, l'agent nommera la transaction en utilisant le nom de la classe et la ou les méthodes instrumentées par ce pointcut.
`methodAnnotation`	Le nom complet sensible à la casse d'une classe d'annotation, y compris le nom du package. Toutes les méthodes marquées avec cette annotation seront mises en correspondance.
`className`	Le nom sensible à la casse de la classe à faire correspondre, y compris le nom du package. Associez ce nœud au nœud de méthode. Si ce nœud est présent sur un point de coupe, alors le nœud `interfaceName` ne peut pas être présent sur le même nœud de point de coupe. Le nœud `className` a l’attribut `includeSubclasses`. Si `true` les méthodes sur la classe avec le nom correspondant seront instrumentées avec les méthodes correspondantes sur n'importe quelle classe enfant de cette classe. Si `false` (par défaut), seules les méthodes sur la classe exacte spécifiée seront instrumentées. Le `className` doit suivre ces règles : Les classes internes peuvent être instrumentées. La structure complète package avec des points entre les packages doit être utilisée. Pour faire correspondre les sous-classes de la classe spécifiée, définissez l'attribut `includeSubclasses` sur `true`.
`interfaceName`	Le nom sensible à la casse d'une interface, y compris le nom du package, dont les classes d'implémentation seront mises en correspondance. Associez ce nœud au nœud de méthode. Si ce nœud est présent sur un point de coupe, alors le nœud `className` ne peut pas être présent sur le même nœud de point de coupe. Le `interfaceName` doit suivre cette règle : la structure complète package avec des points entre les packages doit être utilisée.
`method`	Une méthode sur la classe pour instrument. Associez ce nœud à un nœud `className` . De plus, le nœud `method` peut avoir des enfants.
`traceByReturnType`	Le nom de la classe, y compris le package, au format utilisé dans le bytecode, par exemple `Ljava/lang/String;`. Toutes les méthodes qui renvoient un objet de cette classe seront mises en correspondance.
`traceLambda`	Un booléen indiquant s'il faut faire correspondre les lambdas. Le nœud `traceLambda` a l'attribut : `includeNonstatic` - un booléen indiquant s'il faut faire correspondre les méthodes non statiques (la valeur par défaut est false) ; `pattern` - une chaîne avec le modèle pour rechercher les méthodes lambda.

Le nœud method peut avoir plusieurs enfants. Pour plus d'informations et d'exemples, voir dépannage Java instrumentation personnalisée.

Valeur	Définition
`name`	Le nom exact, sensible à la casse, de la méthode à faire correspondre. Un nœud de méthode `name` doit suivre ces règles : Les méthodes publiques, protégées, privées et package peuvent toutes être instrumentées. Les méthodes statiques et instance peuvent être instrumentées. Les constructeurs ne peuvent pas être instrumentés.
`parameters`	Les types de paramètres de la méthode spécifiés dans l'ordre. Si l'élément `parameters` n'est pas présent, toutes les méthodes correspondant au nom seront mises en correspondance. Cela inclut les déclarations privées et protégées. Un nœud de méthode `parameters` contient une liste des paramètres de la méthode, spécifiés par les éléments `type` . Voici les principales règles pour les éléments `type` : Les primitives sont spécifiées en utilisant leur nom normal : int, virgule flottante, double, long, byte, short, boolean, char. Les objets nécessitent une structure de package complète. Par exemple, n'utilisez pas `String` dans le XML ; utilisez plutôt `java.lang.String`. N'utilisez pas de génériques avec des objets de collection. Par exemple, écrivez `java.util.List` au lieu de `java.util.List<String>`. Inclure des parenthèses pour l'éventail. Par exemple, un éventail d’entiers sera `int[ ]` et un éventail de chaînes sera `java.lang.String[ ]`. Inclure deux jeux de supports pour un éventail d'éventail. Par exemple, un éventail d'éventails de longs serait `long[ ][ ]`. Pour envoyer le paramètre en tant qu'événement analytique à New Relic, ajoutez un attribut XML à l'élément de type appelé `attributeName`. Pour utiliser une méthode sans paramètre, le nœud `parameters` doit être présent pour correspondre à une méthode « sans arguments ».
`returnType`	Le nom sensible à la casse d'une classe indiquant un type de retour à faire correspondre. Toutes les méthodes qui renvoient ce type de classe seront mises en correspondance.

Valeur

Définition

name

Le nom exact, sensible à la casse, de la méthode à faire correspondre.

Un nœud de méthode name doit suivre ces règles :

Les méthodes publiques, protégées, privées et package peuvent toutes être instrumentées.
Les méthodes statiques et instance peuvent être instrumentées.
Les constructeurs ne peuvent pas être instrumentés.

parameters

Les types de paramètres de la méthode spécifiés dans l'ordre. Si l'élément parameters n'est pas présent, toutes les méthodes correspondant au nom seront mises en correspondance. Cela inclut les déclarations privées et protégées.

Un nœud de méthode parameters contient une liste des paramètres de la méthode, spécifiés par les éléments type . Voici les principales règles pour les éléments type :

Les primitives sont spécifiées en utilisant leur nom normal : int, virgule flottante, double, long, byte, short, boolean, char.
Les objets nécessitent une structure de package complète. Par exemple, n'utilisez pas String dans le XML ; utilisez plutôt java.lang.String.
N'utilisez pas de génériques avec des objets de collection. Par exemple, écrivez java.util.List au lieu de java.util.List<String>.
Inclure des parenthèses pour l'éventail. Par exemple, un éventail d’entiers sera int[ ] et un éventail de chaînes sera java.lang.String[ ].
Inclure deux jeux de supports pour un éventail d'éventail. Par exemple, un éventail d'éventails de longs serait long[ ][ ].
Pour envoyer le paramètre en tant qu'événement analytique à New Relic, ajoutez un attribut XML à l'élément de type appelé attributeName.
Pour utiliser une méthode sans paramètre, le nœud parameters doit être présent pour correspondre à une méthode « sans arguments ».

returnType

Le nom sensible à la casse d'une classe indiquant un type de retour à faire correspondre. Toutes les méthodes qui renvoient ce type de classe seront mises en correspondance.

Exemple

Voici un exemple de classe et un fichier XML qui pourraient être utilisés pour instrumenter cette classe.

package test;

import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;

public class SampleTester {

    private String configName;
    private Map<String, Long> maxSampleTimes;

    public SampleTester(String pConfigName) {
        configName = pConfigName;
        maxSampleTimes = new HashMap<>();
    }

    public void checkSample(String name, long[] times) {
        if (times != null) {
            maxSampleTimes.put(name, getFirst(times));
        } else {
            maxSampleTimes.put(name, (long) getFirst());
        }
    }

    private Long getFirst(long[] times) {
        return times[0];
    }

    private int getFirst() {
        return 0;
    }

    public void printMaxRepeat(final long max) throws Exception {
        Runnable myRunnable = new Runnable() {
            public void run() {
                try {
                    printMax(max);
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        };

        ScheduledExecutorService scheduledExecutor = Executors.newScheduledThreadPool(1);
        scheduledExecutor.scheduleWithFixedDelay(myRunnable, 0, 10000, TimeUnit.MILLISECONDS);
    }

    private void printMax(long max) {
        System.out.println("max is " + max);
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="https://newrelic.com/docs/java/xsd/v1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="newrelic-extension extension.xsd"
  name="customExtension" version="1.0">

  <instrumentation metricPrefix="EXAMPLE">
    <pointcut transactionStartPoint="true">

      <!--class name is preceded by package name-->
      <className>test.SampleTester</className>
      <method>
        <name>checkSample</name>
        <parameters>
          <type attributeName="sampleName">java.lang.String</type>
          <type>long[]</type>
        </parameters>
      </method>
      <!--two methods with the same name but different signatures can share one node-->
      <method>
        <name>getFirst</name>
      </method>
      <method>
        <name>run</name>
      </method>
    </pointcut>

    <pointcut transactionStartPoint="false" 
      ignoreTransaction="false"
      excludeFromTransactionTrace="false"
      metricNameFormat="SampleTester/methods">
  
      <className>test.SampleTester</className>
      <method>
        <name>printMaxRepeat</name>
      </method>
      <method>
        <name>printMax</name>
      </method>
    </pointcut>

  </instrumentation>
</extension>

Le premier bloc du fichier XML spécifie le nom et la version de l'extension. Comme l'extension XML par défaut est enabled, cet attribut n'est pas spécifié.

Le deuxième bloc spécifie les méthodes dans SampleClass qui doivent être instrumentées. Une transaction est démarrée au début du bloc. Il convient de noter que dans la classe d'exemple, il existe deux méthodes qui partagent un nom (getFirst) mais ont des signatures différentes. Ceux-ci sont instrumentés avec un seul nœud de méthode. En supprimant le nœud parameters, toutes les méthodes portant le même nom peuvent être associées sous un seul nœud de méthode.

Dans le troisième bloc, les méthodes spécifiées n’ont pas de transaction démarrée sur elles. C'est parce que la transaction a déjà été démarrée dans run. La transaction ne sera pas ignorée et sera incluse dans la trace de transaction.

Cette traduction automatique est fournie pour votre commodité.

Modifier le fichier XML dans UI

Format de fichier XML

Prudence

Nœud racine : extension

instrumentation (enfant de l'extension)

Pointcut (enfant de l'instrumentation)

Nœuds enfants pour pointcut

Nœuds enfants pour la méthode

Exemple

Exemple de cours

Exemple de fichier d'instrumentation XML et explication

Cette traduction automatique est fournie pour votre commodité.

Exemples d'instrumentation XML Java

Modifier le fichier XML dans UI .css-21sua1{background:none;border:none;width:0;padding:0;}

Format de fichier XML

Prudence

instrumentation (enfant de l'extension)

Pointcut (enfant de l'instrumentation)

Nœuds enfants pour pointcut

Nœuds enfants pour la méthode

Exemple

Exemple de cours

Exemple de fichier d'instrumentation XML et explication

Modifier le fichier XML dans UI