Guía de migración del agente .NET 8.x a 9.x

Esta guía describe los cambios principales entre las versiones 8.x y 9.x del agente .NET, los problemas que puede encontrar durante la actualización y cómo migrar exitosamente a la versión 9.x.

Los principales cambios incluyen:

• Rastreo distribuido está habilitado por defecto
• Eliminación de la API pública del agente obsoleta
• Eliminación de configuraciones de agentes configurables obsoletas

Rastreo distribuido habilitado por defecto

rastreo distribuido es una característica que existe en el agente .NET desde julio de 2018. Reemplaza el rastreo de aplicaciones múltiples (CAT) como la mejor manera de comprender rápidamente qué sucede con las solicitudes a medida que viajan a través de varios servicios en una arquitectura de aplicaciones distribuidas. CAT quedará obsoleto en el agente .NET a partir de la versión 9.0 y se eliminará en una versión importante futura.

En las versiones 8.x del agente .NET, el archivo newrelic.config predeterminado instalado en un host por cualquier instalador del agente .NET tendría el elemento crossApplicationTracer presente y configurado enabled="true". El elemento distributedTracing no estaba presente de forma predeterminada.

En 9.x, esto se invertirá: crossApplicationTracer no estará presente de forma predeterminada y distributedTracing estará presente con el valor predeterminado de enabled="true". Sin embargo, el instalador del agente no sobrescribe un archivo newrelic.config existente al actualizar de una versión a otra. Por lo tanto, si actualiza el agente de 8.x a 9.x en un host determinado, el comportamiento del agente en ese host no cambiará.

Eliminación de métodos públicos obsoletos de API del agente

Todos los métodos API obsoletos tienen métodos API de reemplazo con funcionalidad equivalente.

Ejemplos

Crear carga útil de seguimiento distribuido

Si anteriormente tenía un código parecido a este:

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

reemplácelo con esto:

// 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);

AceptarDistributedTracePayload

Si anteriormente tenía un código parecido a este:

// 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);

reemplácelo con esto:

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

Agregar parámetro personalizado

Si anteriormente tenía un código parecido a este:

// 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");

reemplácelo con esto:

// 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");

Eliminación de ajustes de configuración del agente obsoletos

Las siguientes opciones de configuración del agente se están eliminando del agente. Para que la ruta de actualización de 8.x a 9.x sea lo más sencilla posible, no eliminaremos la configuración del esquema XML del archivo newrelic.config . Sin embargo, la lógica de configuración interna del agente se actualizará para ignorar estas configuraciones y se enviará un mensaje de registro al archivo de registro del agente advirtiéndole que estos valores de configuración ya no tienen ningún efecto.

Un poco sobre la notación: para facilitar la descripción, el resto de esta sección describirá los elementos de configuración con una abreviatura de "notación de puntos" en lugar de XML completo.

Por ejemplo, un elemento de configuración que aparece en su archivo newrelic.config puede verse así:

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

En este ejemplo, se escribirá como parameterGroups.IdentityParameters. Dado que todos estos elementos de configuración son hijos del elemento <configuration> de nivel superior, se omite por motivos de brevedad.

La mayoría de las opciones de configuración que se eliminan se relacionan con la captura o exclusión de datos de atributos. Los siguientes documentos son útiles para comprender el panorama general de la recopilación de datos de atributos del agente y cómo se configura:

• Agente Atributo
• Activar y desactivar atributo (.NET)
• Ejemplos de atributos .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>