Créer des transactions via XML (.NET)

Le frameworkNew Relic est automatiquement pris en charge par l'instrument. Cependant, vous pouvez également avoir d'autres frameworks pour lesquels certaines transactions ne sont pas créées automatiquement ou des méthodes supplémentaires que vous souhaiteriez instrument. Vous pouvez ajouter une instrumentation personnalisée à ces méthodes en créant des transactions. Les transactions créées via XML sont classées comme non Web dans l'UI de New Relic.

Ce document décrit comment créer des transactions avec un fichier XML. Vous pouvez également :

• Ajoutez des détails aux transactions existantes à l'aide de XML
• Créez des transactions et ajoutez des détails aux transactions existantes avec l' API .NET deagent.

Si vous disposez d'une application non IIS, l'instrumentation XML nécessite l'activation de l'option Instrument all lors de l'installation de l'agent .NET.

Créer des transactions à l'aide de XML

Les transactions personnalisées (transactions non instrumentées automatiquement) sont définies dans un fichier XML instrumentation personnalisée. Vous définissez une méthode qui déclenche la création d'une transaction. Vous pouvez également instrumenter des méthodes supplémentaires appelées par la méthode trigger.

Quelques règles importantes à connaître avant de créer une transaction personnalisée :

• La base de données et les appels externes ne nécessitent pas instrumentation personnalisée car ils sont automatiquement instrumentés.
• Assurez-vous que votre fichier XML se trouve dans le bon chemin. Pour définir son ensemble d’instrumentation, l’agent .NET lit chaque fichier XML dans le répertoire Extensions .
• Si une méthode que vous tentez d’instrumenter fait déjà partie d’une transaction existante, elle sera ajoutée en tant que segment à cette transaction. Aucune nouvelle transaction ne sera créée. Cela se produira même si la méthode parent est instrumentée à l'aide instrumentation personnalisée.
• Évitez les éléments instrumentés tels que Main(), car cette méthode ne se terminera pas tant que l'application ne se terminera pas et les données risquent de ne pas être envoyées à New Relic.

Pour créer un fichier instrumentation personnalisée :

1. Créez un nouveau fichier .xml dans le répertoire Extensions de votre répertoire d’agent .NET. L'emplacement de ce répertoire dépend de votre système d'exploitation :

   Pour le framework .NET ou agent Core sous Windows

   C:\ProgramData\New Relic\.NET Agent\Extensions

   Copier

   Important

   Utilisez le répertoire ProgramData , pas le répertoire Program Files .

   Pour .NET Core sur Linux

   PATH_TO_AGENT_DIRECTORY/Extensions

   Copier

   PATH_TO_AGENT_DIRECTORY sera la valeur par défaut /usr/local/newrelic-dotnet-agent (versions d'agent 10.0.0 ou supérieures), /usr/local/newrelic-netcore20-agent (versions d'agent 9.9.0 ou inférieures) ou le répertoire choisi lors de l'installation.

   Pour Azure App Services

   Agent pour .NET framework :

   D:\home\site\wwwroot\newrelic\extensions

   Copier

   Agent pour .NET Core :

   D:\home\site\wwwroot\newrelic_core\extensions

   Copier

2. Copiez ce modèle dans le fichier que vous avez créé. Ce modèle définit deux classes et méthodes distinctes en tant que transactions, mais d'autres peuvent être ajoutées :

   <?xml version="1.0" encoding="utf-8"?>
   <extension xmlns="urn:newrelic-extension">
     <instrumentation>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName">
           <exactMethodMatcher methodName="MethodName" />
         </match>
       </tracerFactory>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName2">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName2">
           <exactMethodMatcher methodName="MethodName2" />
         </match>
       </tracerFactory>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName3">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName3" minVersion="1.0.0" maxVersion="99.99.99">
           <exactMethodMatcher methodName="MethodName3" />
         </match>
       </tracerFactory>
     </instrumentation>
   </extension>

   Copier

3. Dans le fichier que vous avez créé, personnalisez les valeurs d’attribut TransactionName, AssemblyName, NameSpace.ClassName et MethodName. Personnalisez ces valeurs pour la méthode de déclenchement et pour toutes les méthodes appelées par la méthode de déclenchement. Vous pouvez également utiliser les valeurs d'attribut facultatives minVersion et maxVersion pour cibler des versions spécifiques d'un assemblage, comme indiqué dans le troisième exemple ci-dessus. Notez que cette fonctionnalité nécessite l'agent 10.6.0 ou supérieur.

   Conseil

   Ces valeurs sont sensibles à la casse.

   • TransactionName: Définit le nom de la transaction. L'attribut metricName est facultatif. Si omis, le nom de la transaction sera NameSpace.ClassName/MethodName. La catégorie de transaction sera Custom. Le nom métrique complet résultant sera OtherTransaction/Custom/TransactionName. Si vous souhaitez modifier la catégorie de transaction de Custom, utilisez l'appel d'API SetTransactionName. L'UI de New Relic regroupe les transactions sous des catégories dans le champ type de transaction.
   • AssemblyName: L'assembly qui contient la méthode de déclenchement.
   • NameSpace.ClassName: Le nom de classe complet qui contient la méthode de déclenchement.
   • MethodName: Le nom exact de la méthode de déclenchement.
   • minVersion: Facultatif (vous pouvez le supprimer). La version d'assemblage minimale à instrumenter (incluse). Si elle est omise, la version minimale est considérée comme 0. Nécessite l'agent 10.6.0 ou supérieur.
   • maxVersion: Facultatif (vous pouvez le supprimer). La version d'assemblage maximale à instrumenter (exclusive). Si omis, il n'y a pas de version maximale. Nécessite l'agent 10.6.0 ou supérieur.

4. L'ajout de méthodes supplémentaires doit inclure l'attribut "NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" à définir comme une transaction. la balise sans cet attribut ajoutera des détails aux transactions existantes uniquement.

5. Facultatif : pour vérifier si le fichier XML est correctement formaté, vous pouvez le comparer au XSD (situé à C:\ProgramData\New Relic\.NET Agent\Extensions\extension.xsd) à l'aide de n'importe quel validateur XSD.

Afficher les transactions dans l'UI

La transaction personnalisée démarre lorsque la méthode spécifiée par methodName est appelée dans l'assembly spécifié par assemblyName. La transaction se termine lorsque la méthode renvoie ou lève une exception.

Vous pouvez visualiser ces métriques dans la pageTransactions et dans trace de transaction. Pour visualiser la transaction : Accédez à one.newrelic.com > All capabilities > APM & services > (select an app) > Monitor > Transactions > Type > (select a type). Le type sera Non-web/Custom sauf si vous utilisez l'API pour modifier la catégorie.

Exemple : instrumenter trois méthodes

Cet exemple présente une implémentation simple de la création de transactions.

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
  <instrumentation>
    <!-- Define the method which triggers the creation of a transaction. -->
    <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="Bars">
      <match assemblyName="Foo" className="Foo.Bar">
        <exactMethodMatcher methodName="Bar1" />
        <exactMethodMatcher methodName="Bar2" />
      </match>
    </tracerFactory>
    <!-- Instrument 0 or more methods called by the trigger method. These methods appear in the transaction breakdown table and in transaction traces. -->
    <tracerFactory>
      <match assemblyName="Foo" className="Foo.Bar">
        <exactMethodMatcher methodName="Bar3" />
      </match>
    </tracerFactory>
  </instrumentation>
</extension>

var bar = new Bar();
bar.Bar1(); // Creates a transaction named Bars in the Custom category.
bar.Bar2(); // Creates a transaction named Bars in the Custom category.
bar.Bar3(); // Won't create a new transaction. See `If Bar3 is called directly`, below.

namespace Foo
{
    public class Bar
    {
        // The agent creates a transaction that includes an external service request in its transaction traces.
        public void Bar1()
        {
            new WebClient().DownloadString("https://www.google.com/");
        }

        // Creates  a transaction containing one segment.
        public void Bar2()
        {
            // The Bar3 segment will contain your SQL query inside of it and possibly an execution plan.
            Bar3();
        }

        // If Bar3 is called directly, the agent will not create a transaction.
        // However, if Bar3 is called from Bar1 or Bar2, Bar3 will appear as a segment containing its SQL query.
        private void Bar3()
        {
            using (var connection = new SqlConnection(ConnectionStrings["MsSqlConnection"].ConnectionString))
            {
                connection.Open();
                using (var command = new SqlCommand("SELECT * FROM table", connection))
                using (var reader = command.ExecuteReader())
                {
                    reader.Read();
                }
            }
        }
    }
}

Exemple : instrumenter une application de console

Cette application de console simple démontre la création de transactions. Après avoir exécuté l'application plusieurs fois, vous voyez les transactions que vous avez créées dans la page Transactions (à one.newrelic.com > All capabilities > APM & services > (select an app) > Transactions > Type). Le segment Dummy sera visible dans le tableau de répartition des transactions et dans toute trace de transaction.

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
    <instrumentation>
        <!-- Define the method which triggers the creation of a transaction. -->
        <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="CustomTransaction">
          <match assemblyName="ConsoleApplication1" className="ConsoleApplication1.CustomTransaction">
            <exactMethodMatcher methodName="StartTransaction" />
          </match>
        </tracerFactory>
        <!-- Instrument 0 or more methods called by the trigger method. These methods appear in the transaction breakdown table and in transaction traces. -->
        <tracerFactory>
          <match assemblyName="ConsoleApplication1" className="ConsoleApplication1.CustomTransaction">
            <exactMethodMatcher methodName="Dummy" />
          </match>
        </tracerFactory>
    </instrumentation>
</extension>

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace ConsoleApplication1
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Custom Transactions");
            var t = new CustomTransaction();
            while (true)
                t.StartTransaction();
        }
    }
    class CustomTransaction
    {
        public void StartTransaction()
        {
            Console.WriteLine("StartTransaction");     
            Dummy();
        }
        void Dummy()
        {
            System.Threading.Thread.Sleep(5000);
        }
    }

}