Java instrumentation par XML

Pour votre application Java monitorée par New Relic, une méthode d'instrumentation personnalisée consiste à utiliser un fichier XML pour spécifier les méthodes de votre application qui doivent être instrumentées. L'agent Java lira le fichier XML et instrumentera les classes pertinentes au démarrage ; les fichiers XML ajoutés au répertoireextensions après le démarrage ne nécessitent pas de redémarrage de JVM pour être détectés.

Consultez l’instrumentation personnalisée de l’agent Java pour obtenir une description des options d’instrumentation personnalisée et les raisons de leur utilisation.

Accéder à votre fichier XML

Allez à 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. (Vous pouvez le faire à partir de la fenêtre contextuelle qui apparaît lorsque vous cliquez sur Import an XML file.)
• Sélectionnez un fichier XML existant ou modifiez-le.
• Rechercher l'historique de l'instrumentation.

Structure du fichier XML

Votre package de téléchargement d'agent New Relic (newrelic_agent.zip) contient deux modèles pour l'utilisation de l'instrumentation XML :

• Le modèle extension.xsd est la définition de schéma XML que toutes les extensions personnalisées doivent suivre.
• Le modèle extension-example.xml est un exemple. Ce fichier instrumente certaines des méthodes de base du JDK. Si vous modifiez et renommez ce fichier, assurez-vous de modifier l'attribut name="extension-example" pour qu'il corresponde au nouveau nom de fichier.

Pour plus d'informations sur les propriétés du modèle extension.xsd, consultez la présentation du format de fichier XML.

Validation du fichier XML

Avant de démarrer votre application, validez votre fichier XML à l'aide de l'outil de ligne de commande de New Relic. L'outil de ligne de commande ne peut être utilisé que lorsque vos classes sont dans un fichier jar. Il existe deux manières de valider votre instrumentation XML :

$
java -Djava.ext.dirs=/path/to/jarred/classes -jar newrelic.jar instrument -file /path/to/file.xml -debug true

$
java -cp /path/to/your-app.jar:/path/to/newrelic.jar com.newrelic.bootstrap.BootstrapAgent instrument -file /path/to/file.xml -debug true

L'application est exécutée avec le newrelic.jar. L'appel doit contenir le mot-clé instrument suivi de l'indicateur -file avec le chemin vers votre fichier XML. La propriété -debug est facultative et peut être définie sur true pour fournir plus d'informations lors de la validation.

L'outil permettra de :

• Valider la syntaxe XML.
• Vérifiez que chaque classe à instrumenter est présente sur le chemin de classe.
• Vérifiez que chaque méthode est contenue dans la classe appropriée.

Si le fichier XML est valide, vous verrez une instruction de réussite imprimée sur le terminal :

PASS: The extension at file.txt was successfully validated.

Si la validation du XML échoue, vous verrez un message d'échec imprimé sur le terminal :

FAIL: reason

Emplacement du fichier XML

L'agent Java lit tous les fichiers XML dans le répertoire extensions au démarrage du processus. Le répertoire extensions est également lu à chaque cycle de collecte. Les fichiers XML ajoutés à ce répertoire pendant l'exécution seront lus en quelques minutes, ils ne nécessitent donc pas de redémarrage de la JVM.

Il existe deux manières de spécifier l'emplacement du fichier XML :

Vérifiez que le fichier a été lu

Pour vérifier que l'agent a lu le fichier XML, définissez d'abord la gestion des logs sur finer:

1. Modifiez le fichier de configuration newrelic.yml et modifiez la propriété log_level :

   log_level: finer

   Copier

2. Démarrez ou redémarrez l'application.

Si la lecture a réussi, logs/newrelic_agent.log l'indiquera dans une instruction similaire à :

Reading custom extension file /path/to/file.xml

Si aucune instruction n'apparaît dans logs/newrelic_agent.log, alors le fichier XML n'a pas été trouvé. Vérifiez l’emplacement du fichier XML et assurez-vous que le processus New Relic dispose d’un accès en lecture au fichier.

Plusieurs fichiers XML

Bien que l’utilisation d’un seul fichier XML soit préférable, vous pouvez utiliser plusieurs fichiers XML personnalisés. Ces fichiers seront tous instrumentés à condition que le nom d'extension dans les fichiers soit unique.

• Si deux fichiers XML personnalisés contiennent le même nom d'extension, celui avec la version la plus élevée sera implémenté et l'autre sera ignoré.
• Si les deux fichiers ont le même nom et la même version, alors le premier fichier lu par l'agent sera implémenté et l'autre sera ignoré.

XML et YAML

Avant la version 2.10.0, Les fichiers YAML peuvent être utilisés pour une instrumentation personnalisée. Ces fichiers YAML legacy sont toujours pris en charge. Cependant, les nouveaux utilisateurs doivent utiliser des fichiers XML pour instrumentation personnalisée.

Legacy users: Si un fichier YAML et un fichier XML existent avec le même nom d'extension, seul le fichier XML sera instrumenté. Le fichier YAML sera ignoré. Si vous souhaitez que les fichiers YAML et XML soient instrumentés, donnez à chaque fichier un nom d'extension différent.

Exemple de fichier XML

Pour un exemple de fichier XML instrumentation personnalisée, voir Exemples XMLJava .