Ajoutez des détails aux transactions via XML (.NET)

New Relic collecte et rapporte des informations sur les transactions du navigateur Web et les transactions non Web (tâches d'arrière-plan). Normalement, l'agent .NET produit automatiquement des informations complètes, sans que vous ayez besoin de modifier le code de votre application. Cependant, si New Relic ne prend pas en charge votre framework, vous devrez peut-être ajouter une instrumentation personnalisée.

New Relic utilise la méthode traceur pour mettre en œuvre instrumentation personnalisée. Un traceur de méthode est une sonde logicielle que vous pouvez placer sur une méthode de n'importe quelle classe. L'agent .NET charge les directives instrumentation qui définissent les méthodes à suivre à partir de tous les fichiers XML du répertoire des extensions.

Ce document décrit le travail instrumenté lorsque l'agent collecte déjà des transactions, mais que vous souhaitez ajouter plus de détails à ces transactions. Pour instrumenter le travail lorsque l'agent ne crée pas de transactions automatiquement, voir Créer des transactions via XML. Vous pouvez également ajouter des détails et créer des transactions en décorant votre code avec l'attribut.

Ajoutez des détails avec une instrumentation personnalisée

Les fichiers d'extension définissent un certain nombre d'usines de traceurs dans un élément instrumentation . Chaque fabrique de traceurs contient des éléments de correspondance qui définissent l'assembly, le nom de classe entièrement qualifié et le nom de méthode à faire correspondre. Pour définir un nouveau fichier XML instrumentation personnalisée :

Créez un nouveau fichier .xml dans le répertoire d’extensions utilisé par l’agent .NET pour lire chaque fichier XML et définir son ensemble d’instrumentation. Pour l'agent.NET Framework, utilisez l'emplacement suivant :
```
C:\ProgramData\New Relic\.NET Agent\Extensions
```
Important
Ne mettez pas le .xml fichier dans le répertoire C:\Program Files\New Relic\.NET agent\Extensions . Le fichier doit se trouver à l'emplacement de fichier ProgramData pour que l'instrumentation personnalisée fonctionne.
Ne modifiez pas les fichiers XML distribués. Ces fichiers sont écrasés chaque fois que l'agent est mis à niveau.
Copiez ce modèle dans le fichier que vous avez créé et utilisez l'échantillon comme exemple. Cet instrument comporte deux méthodes, mais vous pouvez ajouter des méthodes à votre fichier d'instrumentation.
Conseil
Les valeurs AssemblyName, NameSpace.ClassName et MethodName sont sensibles à la casse.
```
<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
  <instrumentation>
    
    <tracerFactory metricName="Category/Name">
      <match assemblyName="AssemblyName" className="NameSpace.ClassName">
        <exactMethodMatcher methodName="MethodName" />
      </match>
    </tracerFactory>
    <tracerFactory metricName="Category/Name2"> 
       <match assemblyName="AssemblyName" className="NameSpace.ClassName2"> 
        <exactMethodMatcher methodName="MethodName2" /> 
       </match>
    </tracerFactory>
  </instrumentation>
</extension>
```
Valider le fichier d’instrumentation .xml par rapport à extension.xsd.
Applications non IIS (telles qu'une application de console ou un processus d'arrière-plan) : vous devez également créer des transactions via XML pour contenir les méthodes que vous instrument. Les méthodes personnalisées instrumentées en dehors d'une transaction ne seront pas signalées à New Relic.
Important
Si votre version d’agent .NET est 7.0 ou supérieure, c’est la fin de la procédure.
Si la version de votre agent .NET est inférieure à 7.0, passez aux étapes suivantes.
Si votre application est hébergée par IIS, redémarrez IIS.
Pour les applications non IIS, redémarrez le processus hôte de votre application ou l'application elle-même.

Important

Si certaines de vos méthodes n'apparaissent toujours pas dans la trace après l'ajout instrumentation XML personnalisée, désactivez l'intégration de méthode pour ces méthodes avec [MethodImpl(MethodImplOptions.NoInlining)].

Ignorer une transaction

Vous pouvez empêcher qu'une transaction soit signalée en utilisant un fichier instrumentation personnalisée. Chaque fois qu’une méthode ignorée est appelée, l’agent .NET ignore l’intégralité de la transaction parent. C'est la même chose que d'appeler IgnoreTransaction().

Pour ignorer une transaction :

Ajouter une instrumentation personnalisée.

Ajoutez un tracerFactory dont le nom est NewRelic.Agent.Core.Tracer.Factories.IgnoreTransactionTracerFactory:

<tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.IgnoreTransactionTracerFactory">
  <match assemblyName="System.Web.Extensions" className="System.Web.Handlers.ScriptResourceHandler">
    <exactMethodMatcher methodName="Throw404" />
  </match>
</tracerFactory>

Suivre le travail asynchrone dans une transaction distincte

Dans certains cas, le travail asynchrone peut être suivi comme une transaction distincte en appliquant l'instrumentation AsyncForceNewTransactionWrapper :

<tracerFactory name="AsyncForceNewTransactionWrapper">
  <match assemblyName="AssemblyName" className="Namespace.ClassName">
    <exactMethodMatcher methodName="MethodName" />
  </match>
</tracerFactory>

Considérations sur l'utilisation asynchrone	Commentaires
méthode instrumentée	La méthode instrumentée doit être invoquée en utilisant `Task.Run`, `Task.Factory.StartNew` ou `new Thread()`. Il ne peut pas être invoqué à l'aide du mot-clé `await` .
Type de retour	Il n’est pas nécessaire que la méthode instrumentée soit `async`. Cependant, s'il s'agit de `async`, il doit avoir un type de retour de `Task` ou `Task<T>`. Il ne peut pas avoir un type de retour `void` .
instrumentationd'attribut	La méthode instrumentée ne peut pas avoir instrumentation d’attribut qui lui est appliquée. Il ne peut pas être décoré avec l'attribut `[Transaction]` ou `[Trace]` .

Les méthodes suivantes peuvent être instrumentées à l'aide de l'instrumentation personnalisée AsyncForceNewTransactionWrapper :

private void SyncMethod()
{
}

private async Task AsyncMethod_Task()
{
}

private async Task<string> AsyncMethod_TypedTask()
{
    return "ok";
}

Les méthodes suivantes cannot peuvent être instrumentées à l'aide de l'instrumentation personnalisée AsyncForceNewTransactionWrapper :

private async void AsyncMethod_Void()
{
}

[Transaction]
private void TransactionAttributedMethod()
{
}

[Trace]
private void TracedAttributedMethod()
{
}

Les appels de méthode suivants peuvent être utilisés avec l'instrumentation AsyncForceNewTransactionWrapper :

Task.Run(SyncMethod);

Task.Factory.StartNew(AsyncMethod_Task);

var newThread = new Thread(new ThreadStart(SyncMethod));
newThread.Start();

La méthode suivante appelle cannot à utiliser avec l'instrumentation AsyncForceNewTransactionWrapper :

SyncMethod();              // This is not an asynchronous call

await AsyncMethod_Task();  // Not started with Task.Run, Task.Factor.StartNew, or new Thread()

AsyncMethod_Void();        // Async Void is not supported

Exemple MyInstrumentation.xml

Cet exemple utilise deux méthodes et ignore une autre méthode :

Instrument: CustomInstrumentDemo.Controllers.FirstController.FirstExample()
Instrument: CustomInstrumentDemo.Controllers.SecondController.SecondExample()
Ignore: CustomInstrumentDemo.Controllers.SecondController.ThirdExample()
Instrument: CustomInstrumentDemo.Controllers.SecondController.FourthExample(int id, string name)

Pour implémenter ce schéma instrumentation personnalisé, utilisez le fichier d'exemple suivant et les méthodes instrumentées :

Voici un exemple de fichier instrumentation personnalisée nommé MyInstrumentation.xml:

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
  <instrumentation>
    <!-- instrument CustomInstrumentDemo.Controllers.FirstController.FirstExample and creates metric named Custom/Foo1 -->
    <tracerFactory metricName="Custom/Foo1">
      <match assemblyName="CustomInstrumentDemo" className="CustomInstrumentDemo.Controllers.FirstController">
        <exactMethodMatcher methodName="FirstExample" />
      </match>
    </tracerFactory>

    <!-- instrument CustomInstrumentDemo.Controllers.SecondController.SecondExample -->
    <tracerFactory>
      <match assemblyName="CustomInstrumentDemo" className="CustomInstrumentDemo.Controllers.SecondController">
        <exactMethodMatcher methodName="SecondExample" />
      </match>
    </tracerFactory>

    <!-- ignore CustomInstrumentDemo.Controllers.SecondController.ThirdExample -->
    <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.IgnoreTransactionTracerFactory">
      <match assemblyName="CustomInstrumentDemo" className="CustomInstrumentDemo.Controllers.SecondController">
        <exactMethodMatcher methodName="ThirdExample" />
      </match>
    </tracerFactory>

    <!-- instrument CustomInstrumentDemo.Controllers.SecondController.FourthExample and creates metric named Custom/{value},
         where {value} is the value of the first string parameter of the instrumented method
         (in this case, the first string parameter is "name"). -->
    <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.CustomSegmentTracerFactory">
      <match assemblyName="CustomInstrumentDemo" className="CustomInstrumentDemo.Controllers.SecondController">
        <exactMethodMatcher methodName="FourthExample" />
      </match>
    </tracerFactory>
  </instrumentation>
</extension>

Ce code contient les trois méthodes spécifiées par le fichier d'exemple instrumentation personnalisée:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Threading;

namespace CustomInstrumentDemo.Controllers
{
    public class FirstController : Controller
    {
        public ActionResult Foo1()
        {
            ViewBag.Message = "Your Sample Page";
            FirstExample();
            return View();
        }

        public void FirstExample()
        {
            int firstVar = 1;
            for (int i = 0; i <= 500; i++)
            {
                firstVar *= 5;
                Thread.Sleep(50);
            } 
        }
    }

    public class SecondController : Controller
    {
        public ActionResult Foo2()
        {
            ViewBag.Message = "This view will include detailed information on the SecondExample method";
            SecondExample();
            return view;
        }

        public ActionResult Foo3()
        {
            ViewBag.Message = "This view will be ignored because of the inclusion of the ThirdExample method";
            ThirdExample();
        }

        public void SecondExample()
        {
            int secondVar = 2;

            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();
                }
            }
        }

        public void ThirdExample()
        {
            try
            {
                var ImNotABool = "43";
                bool.Parse(ImNotABool);
            }
            catch (Exception ex)
            {
                NewRelic.Api.Agent.NewRelic.NoticeError(ex);
            }
        }

        public void FourthExample(int id, string name)
        {
            Console.WriteLine("The ID passed in was " + id + " and the name passed in was " + name);
        }
    }
}

Nom métriques

Les métriques créées à partir de traceur seront nommées en utilisant le nom de la classe et le nom de la méthode correspondante. Vous pouvez remplacer ce nom avec l'attribut metricName . Commencez metricName par Custom/ (par exemple, metricName="Custom/OrderSubmissions").

<!-- instruments MyCompany.Order.Submit() and creates a metric named Custom/OrderSubmissions -->
<tracerFactory metricName="Custom/OrderSubmissions">
  <match assemblyName="MyCompany" className="MyCompany.Order">
    <exactMethodMatcher methodName="Submit" />
  </match>
</tracerFactory>

Transactions de nom

L'agent nomme les transactions à l'aide du traceur dans la transaction avec la priorité de dénomination la plus élevée.

La transaction Web peut être nommée à l'aide du gestionnaire HTTP, du nom ASP, du nom du contrôleur MVC ou du nom du service Web, en fonction du traceur invoqué dans l'exécution de la transaction.
Les transactions en arrière-plan sans traceur qui nomme explicitement la transaction sont regroupées dans un seul nom de transaction.

Utilisez l’attribut transactionNamingPriority pour indiquer à l’agent d’attribuer une priorité de dénomination de transaction de traceur. Les valeurs valides sont 1 à 7, où 7 a priorité sur 1 à 6. De plus, l'attribut metricName doit commencer par Custom/ (par exemple, metricName="Custom/instance").

<!-- instructs the agent to create a metric for MyControllerBase.Execute and to name the transaction using this tracer's metric name -->
<tracerFactory metricName="Custom/instance" transactionNamingPriority="7">
  <match assemblyName="MyCompany" className="MyCompany.MyControllerBase">
    <exactMethodMatcher methodName="Execute" />
  </match>
</tracerFactory>

Validation XSD

Le fichier d'instrumentation XML peut être vérifié par rapport au fichier XSD (situé à C:\ProgramData\New Relic\.NET Agent\Extensions\extension.xsd) avec n'importe quel validateur XSD.

Dépannage

L'agent .NET écrira un message de log dans NewRelic.Profiler.####.log (où #### est le PID du processus instrumenté) au fur et à mesure qu'il réécrit les méthodes. Cela permet de vérifier que instrumentation personnalisée est lue et que les méthodes appropriées sont instrumentées.

Conseil

Évitez d’utiliser l’attribut name de l’élément tracerFactory dans l’instrumentation personnalisée. Pour plus d’informations, consultez le fichier de schéma extension.xsd dans le répertoire de l’agent.

Cette traduction automatique est fournie pour votre commodité.

Ajoutez des détails aux transactions via XML (.NET)

Ajoutez des détails avec une instrumentation personnalisée

Important

Conseil

Important

Important

Ignorer une transaction

Suivre le travail asynchrone dans une transaction distincte

Exemples de définitions de méthodes

Exemples d'invocations de méthodes

Exemple MyInstrumentation.xml

Exemple de fichier d'instrumentation personnalisée

Exemples de méthodes à instrumenter

Nom métriques

Transactions de nom

Validation XSD

Dépannage

Conseil

Cette traduction automatique est fournie pour votre commodité.

Ajoutez des détails aux transactions via XML (.NET)

Ajoutez des détails avec une instrumentation personnalisée .css-21sua1{background:none;border:none;width:0;padding:0;}

Important

Conseil

Important

Important

Ignorer une transaction

Suivre le travail asynchrone dans une transaction distincte

Exemples d'invocations de méthodes

Exemple MyInstrumentation.xml

Exemple de fichier d'instrumentation personnalisée

Exemples de méthodes à instrumenter

Nom métriques

Transactions de nom

Validation XSD

Dépannage

Conseil

Ajoutez des détails avec une instrumentation personnalisée