Guide de migration de l'agent .NET 8.x vers 9.x

Ce guide décrit les principaux changements entre les versions 8.x et 9.x de l'agent .NET, les problèmes que vous pouvez rencontrer lors de la mise à niveau et comment migrer avec succès vers la version 9.x.

Les principaux changements incluent :

• Le traçage distribué est activé par défaut
• Suppression de l'API publique obsolète de l'agent
• Suppression des paramètres d'agent configurables obsolètes

Traçage distribué activé par défaut

Le traçage distribué est une fonctionnalité qui existe dans l'agent .NET depuis juillet 2018. Il remplace leapplicationtraçage inter- (CAT) comme le meilleur moyen de comprendre rapidement ce qui arrive requests aux lorsqu'elles transitent par différents services dans une application architecture distribuée. CAT sera obsolète dans l'agent .NET à partir de la version 9.0 et sera supprimé lors d'une future sortie majeure.

Dans les versions 8.x de l'agent.NET, le fichier newrelic.config par défaut installé sur un hôte par tout programme d'installation agent .NET aurait l'élément crossApplicationTracer présent et défini sur enabled="true". L'élément distributedTracing n'était pas présent par défaut.

Dans 9.x, cela sera inversé : crossApplicationTracer ne sera pas présent par défaut et distributedTracing sera présent avec la valeur par défaut de enabled="true". Cependant, le programme d'installation de agent n'écrase pas un fichier newrelic.config existant lors de la mise à niveau d'une version vers une autre. Par conséquent, si vous mettez à niveau l'agent de 8.x vers 9.x sur un hôte donné, le comportement de l'agent sur cet hôte ne changera pas.

Suppression des méthodes API d'd'agent publiques obsolètes

Toutes les méthodes API obsolètes ont des méthodes API de remplacement avec des fonctionnalités équivalentes.

Exemples

Créer une trace distribuée

Si vous aviez auparavant un code qui ressemblait à ceci :

// Create an external web request to another instrumented service
HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");

// Create the trace payload 
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
IDistributedTracePayload payload = transaction.CreateDistributedTracePayload();

// Add the trace payload to the headers of the outgoing request
requestMessage.Headers.Set(NewRelic.Api.Agent.Constants.DistributedTracePayloadKey, payload.HttpSafe());

remplacez-le par ceci :

// Create an external web request to another instrumented service
HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");

// Insert the distributed trace headers to the message. The "setter"
// action tells the API how to add headers to the "carrier", which
// is the HttpWebRequest message in this example
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;
var setter = new Action<HttpWebRequest, string, string>((carrier, key, value) =>
{
    carrier.Headers?.Set(key, value);
});
currentTransaction.InsertDistributedTraceHeaders(requestMessage, setter);

AccepterDistributedTracePayload

Si vous aviez auparavant un code qui ressemblait à ceci :

// Obtain the payload from the upstream request object
HttpContext httpContext = HttpContext.Current;
string payload = httpContext.Request.Headers[NewRelic.Api.Agent.Constants.DistributedTracePayloadKey];

// Accept the payload
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
transaction.AcceptDistributedTracePayload(payload, TransportType.HTTP);

remplacez-le par ceci :

HttpContext httpContext = HttpContext.Current;
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// The "Getter" method defines how to get headers from the carrier, 
// which is the HttpContext in this example 
IEnumerable<string> Getter(HttpContext carrier, string key)
{
    string value = carrier.Request.Headers[key];
    return value == null ? null : new string[] { value };
}

// Call the API
currentTransaction.AcceptDistributedTraceHeaders(httpContext, Getter, TransportType.HTTP);

Ajouter un paramètre personnalisé

Si vous aviez auparavant un code qui ressemblait à ceci :

// Called in code that runs inside a transaction created by the
// agent, for example an ASP.NET WebApi endpoint
NewRelic.Api.Agent.NewRelic.AddCustomParameter("myCustomParameter", "myValue");

remplacez-le par ceci :

// Get the current transaction
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// Add the custom attribute to the current transaction
currentTransaction.AddCustomAttribute("myCustomParameter", "myValue");

Suppression des paramètres de configuration d'agent obsolètes

Les paramètres de configuration de l’agent suivants sont supprimés de l’agent. Afin de rendre le chemin de mise à niveau de 8.x vers 9.x aussi fluide que possible, nous ne supprimerons pas les paramètres du schéma XML du fichier newrelic.config . Cependant, la logique interne de l'agent configuration sera mise à jour pour ignorer ces paramètres et un message de envoyé log au agent fichier de de log vous avertissant que ces configuration valeurs n'ont plus aucun effet.

Quelques mots sur la notation : pour faciliter la description, le reste de cette section décrira les éléments de configuration avec une abréviation de « notation par points » plutôt qu'avec du XML complet.

Par exemple, un élément de configuration qui apparaît dans votre fichier newrelic.config peut ressembler à ceci :

<configuration>
  <parameterGroups>
    <identityParameters>
      …
    </identityParameters>
  </parameterGroups>
  …
</configuration>

Dans cet exemple, il sera écrit parameterGroups.IdentityParameters. Étant donné que tous ces éléments de configuration sont des enfants de l’élément <configuration> de niveau supérieur, celui-ci est omis par souci de concision.

La plupart des options de configuration supprimées concernent la capture ou l’exclusion des données d’attribut. Les documents suivants sont utiles pour comprendre la vue d’ensemble de la collecte de données d’attributs agent et la manière dont elle est configurée :

• attribut de l'agent
• Activer et désactiver l'attribut (.NET)
• Exemples d'attributs .NET

<parameterGroups>
  <identityParameter enabled="true"/>
</parameterGroups>

<attributes enabled="true">
  <include>identity.*</include>
</attributes>

<attributes>
  <include>request.parameters.*</include>
</attributes>

<attributes>
  <exclude>request.parameters.specificRequestParameter</exclude>
</attributes>

<attributes>
  <include>request.parameters.*</include>
</attributes>

<attributes>
  <exclude>request.parameters.specificRequestParamter</exclude>
</attributes>