Éditeur instrumentation personnalisée : instrumenter depuis l'UI

L'éditeur d'instrumentation personnalisée de New Relic permet à l'utilisateur de l'application Java d'implémenter une instrumentation personnalisée via l'interface utilisateur de New Relic. L'éditeur est le choix privilégié lorsque vous ne pouvez pas modifier le code de votre application et que vous n'avez pas beaucoup de méthodes à instrument. Consultez l’instrumentation personnalisée Java pour d’autres options d’instrumentation et les raisons d’utiliser chacune d’elles.

Pour utiliser l'éditeur instrumentation personnalisée : Accédez à one.newrelic.com > All capabilities > APM & services > (select a Java app) > Settings > Instrumentation. Utilisez l'éditeur instrumentation personnalisée pour :

Instrumenter un framework non pris en charge.
Obtenez des informations supplémentaires détaillées sur les méthodes non instrumentées.
Ignorer les transactions particulières.

Exigences

Pour utiliser l'éditeur instrumentation personnalisée, vous devez répondre aux exigences suivantes :

Requirement	Comments
agent	agent Java version 3.17.0 ou supérieure
Sécurité	l'utilisateur du mode haute sécurité doit exporter son instrumentation et l'importer manuellement sur son serveur d'applications.

Définir une instrumentation personnalisée

Pour définir instrumentation personnalisée à partir de l'interface utilisateur New Relic, utilisez une session de profilage de thread pour collecter des traces d'appels détaillées de chaque thread de votre application. Si possible, testez votre instrumentation personnalisée dans un pré-environnement de production avant de modifier les règles instrumentation dans votre application de production.

Dans l'un ou l'autre environnement, utilisez l'éditeur instrumentation personnalisée pour définir les méthodes que vous souhaitez instrumenter et appliquez vos modifications :

Créer une nouvelle session de profileur de thread. Pour garantir la collecte d'un ensemble de données suffisant, la durée de la session doit être d'au moins deux minutes.
Allez à one.newrelic.com > All capabilities > APM & services > (select an app) > Settings > Instrumentation. Faites défiler la page jusqu’à ce que vous voyiez la liste Recently collected thread profiles, puis sélectionnez le profil de thread le plus récent.
Développer des méthodes individuelles pour localiser les objets non instrumentés méthodes.
Pour définir des règles d'instrumentation pour des nœuds particuliers, sélectionnez Instrument ou Ignore et personnalisez les règles si nécessaire.
Pour enregistrer vos paramètres, sélectionnez Confirm instrumentation changes.
déployez vos modifications depuis la pageInstrumentation :
- Pour déployer vos modifications automatiquement, sélectionnez Deploy instrumentation changes.
- Pour déployer vos modifications manuellement, sélectionnez Export XML et consultez l'exportation de votre instrumentation.

Prudence

Évitez autant que possible le sur-instrumentation. Avec chaque méthode supplémentaire instrumentée, l'agent utilisera plus de ressources et votre application subira plus de frais généraux. De plus, le déploiement de votre instrumentation entraînera une brève période de surcharge plus élevée. Cela peut ralentir sensiblement application requests pendant plusieurs secondes.

Si vous avez appliqué vos modifications depuis l'UI, l'agent commencera à instrumenter vos méthodes dans quelques cycles de collecte (généralement quelques minutes).

instrumentation manuelle à l'aide de l'éditeur

Vous pouvez également créer des points d'instrumentation directement dans l'éditeur sans utiliser de profil de filetage :

Depuis l'éditeur instrumentation personnalisée, sélectionnez Add manual instrumentation pour saisir manuellement une classe et une méthode à instrumenter ou à ignorer.
Suivez l'instrumentation personnalisée selon les règles XML lors de la définition de vos points d'instrumentation.
déployez vos modifications depuis l'éditeur instrumentation .

Utilisez cette méthode pour ajouter à l'exposant instrumentation des fonctionnalités supplémentaires au-delà de ce qui est disponible à partir d'un profil de thread. En plus de faire correspondre les méthodes par signature, vous pouvez également instrumenter les méthodes par type de retour, les méthodes sur les interfaces et par annotation Java .

Ces types d’instrumentation plus complexes peuvent être créés et supprimés dans l’éditeur, mais pas modifiés.

Important

Si une méthode est marquée Instrumentation not allowed, suivez les procédures de dépannage de New Relic pour l'instrumentation personnalisée.

annuler les modifications manuellement

Vous pouvez également utiliser l'éditeur instrumentation personnalisée pour créer un ensemble instrumentation personnalisée, puis exporter un fichier instrumentation et l'importer manuellement sur votre serveur d'applications. Ceci est requis pour les utilisateurs du mode haute sécurité.

Pour exporter votre instrumentation, définissez instrumentation personnalisée via l'UI. Sélectionnez ensuite Export xml sur la page Instrumentation et importez le fichier sur votre serveur d’applications.

Fonctions de page

La page Instrumentation prend en charge la fonctionnalité suivante :

Si vous voulez...	Fais ceci...
Mettre en pause ou désactiver l'instrumentation personnalisée	Sélectionner Disable instrumentation pour désactiver temporairement UItoute instrumentation personnalisée définie . Sélectionnez Enable instrumentation pour réactiver vos paramètres d’instrumentation.
Importer l'instrumentation existante	Vous pouvez importer un fichier xmlinstrumentation personnalisée existant en sélectionnant Import xml. Vous pouvez également Export xml si vous ne souhaitez pas déployer vos modifications automatiquement.
Modifier ou supprimer des points d'instrumentation	Vous ne pouvez pas modifier l'instrumentation manuelle, seulement la supprimer. Sélectionnez Remove pour arrêter l'instrumentation d'une méthode particulière. Sélectionnez Edit pour modifier les règles d’instrumentation.
Afficher l'historique de l'instrumentation	Vous pouvez visualiser chaque itération précédente de votre instrumentation personnalisée à partir de l'onglet Instrumentation history, y compris qui a déployé les modifications et quand. Vous pouvez restaurer une ancienne version en sélectionnant export pour télécharger une copie du fichier instrumentation personnalisée, puis en l'important dans l'éditeur instrumentation .

Options d'instrumentation

Vous pouvez définir les options suivantes avec l'éditeur instrumentation personnalisée :

Instrumentation options	Comments
méthodes instrumentales	Commencer à instrumenter la méthode sélectionnée. Les méthodes instrumentées seront visibles dans l'UI de New Relic. Instrument prend en charge les options enfants suivantes : Name the transaction (transaction name): Remplacer le nom de transaction standard, défini par les règles de dénomination automatique. L'UI utilisera plutôt le nom répertorié. Start the transaction when this method executes: Plutôt que d'inclure les métriques de cette métrique dans sa transaction parent, créez une nouvelle transaction pour cette méthode. Le comportement de l'agent avec cette option dépend de l'existence ou non d'une transaction préexistante sur le thread.
Rapport d'attribut personnalisé	Le paramètre de méthode peut être capturé comme attribut sur une transaction. New Relic signale ces attributs comme trace de transaction, erreurs de trace et `Transaction` événement. Pour des raisons de sécurité, la capture d'attributs personnalisés à l'aide de l'éditeur d'instrumentation personnalisée est disabled par défaut et ne peut pas être activée lorsque vous utilisez le mode haute sécurité. Si vous souhaitez signaler un attribut personnalisé à l'aide de l'éditeur instrumentation personnalisée et que vous ne souhaitez pas que l'agent Java soit en mode Haute sécurité, désactivez le mode Haute sécurité puis ajoutez le texte suivant dans le bloc `common:` de votre newrelic.yml: `reinstrument: attributes_enabled: true`
Ignorer les transactions	Ignorez complètement cette méthode. L'agent ne signalera pas les métriques de cette méthode et la méthode ne contribuera pas aux calculs Apdex.

Instrumentation options

Comments

méthodes instrumentales

Commencer à instrumenter la méthode sélectionnée. Les méthodes instrumentées seront visibles dans l'UI de New Relic. Instrument prend en charge les options enfants suivantes :

Name the transaction (transaction name): Remplacer le nom de transaction standard, défini par les règles de dénomination automatique. L'UI utilisera plutôt le nom répertorié.
Start the transaction when this method executes: Plutôt que d'inclure les métriques de cette métrique dans sa transaction parent, créez une nouvelle transaction pour cette méthode. Le comportement de l'agent avec cette option dépend de l'existence ou non d'une transaction préexistante sur le thread.

Rapport d'attribut personnalisé

Le paramètre de méthode peut être capturé comme attribut sur une transaction. New Relic signale ces attributs comme trace de transaction, erreurs de trace et Transaction événement.

Pour des raisons de sécurité, la capture d'attributs personnalisés à l'aide de l'éditeur d'instrumentation personnalisée est disabled par défaut et ne peut pas être activée lorsque vous utilisez le mode haute sécurité. Si vous souhaitez signaler un attribut personnalisé à l'aide de l'éditeur instrumentation personnalisée et que vous ne souhaitez pas que l'agent Java soit en mode Haute sécurité, désactivez le mode Haute sécurité puis ajoutez le texte suivant dans le bloc common: de votre newrelic.yml:

reinstrument:
    attributes_enabled: true

Ignorer les transactions

Ignorez complètement cette méthode. L'agent ne signalera pas les métriques de cette méthode et la méthode ne contribuera pas aux calculs Apdex.

Résultats avec l'option "démarrer"

Si vous sélectionnez Instrument methods > Start the transaction when this method executes, le comportement de l'agent dépend de l'existence ou non d'une transaction préexistante sur le thread.

Lorsque la classe ou la méthode est instrumentée :

L'indicateur « Start the transaction" » est-il coché ?
Si une transaction préexistante is sur ce thread et l'indicateur Start the transaction is sont cochés : L'agent ignore l'indicateur Start the transaction . L'agent inclut la classe/méthode dans la transaction préexistante.	Si une transaction préexistante is existe sur ce thread et que l'indicateur Start the transaction n'est pas coché, l'agent inclut la classe/méthode dans la transaction préexistante.
Si une transaction n'est pas sur ce thread et que l'indicateur Start the transaction is est coché : L'agent découvre qu'il n'y a aucune transaction en cours. L'agent crée une nouvelle transaction en commençant par la classe/méthode que vous avez instrumentée.	Si une transaction n'est pas sur ce thread et que l'indicateur Start the transaction n'est pas coché : L'agent recherche une transaction sur ce thread et n'en trouve pas. La métrique est abandonnée.

L'indicateur « Start the transaction" » est-il coché ?

Yes

Si une transaction préexistante is sur ce thread et l'indicateur Start the transaction is sont cochés :

L'agent ignore l'indicateur Start the transaction .
L'agent inclut la classe/méthode dans la transaction préexistante.

Si une transaction préexistante is existe sur ce thread et que l'indicateur Start the transaction n'est pas coché, l'agent inclut la classe/méthode dans la transaction préexistante.

Si une transaction n'est pas sur ce thread et que l'indicateur Start the transaction is est coché :

L'agent découvre qu'il n'y a aucune transaction en cours.
L'agent crée une nouvelle transaction en commençant par la classe/méthode que vous avez instrumentée.

Si une transaction n'est pas sur ce thread et que l'indicateur Start the transaction n'est pas coché :

L'agent recherche une transaction sur ce thread et n'en trouve pas.
La métrique est abandonnée.

Cette traduction automatique est fournie pour votre commodité.