Guia de migração do agente .NET 8.x para 9.x

Este guia descreve as principais alterações entre as versões 8.xe 9.x do agente .NET, os problemas que você pode encontrar durante a atualização e como migrar com êxito para a versão 9.x.

As principais mudanças incluem:

• Distributed tracing está ativado por padrão
• Remoção da API pública obsoleta do agente
• Remoção de configurações de agente configuráveis obsoletas

Distributed tracing ativado por padrão

distributed tracing é um recurso que existe no agente .NET desde julho de 2018. Ele substitui o rastreamento multiaplicativo (CAT) como a melhor maneira de entender rapidamente o que acontece com as solicitações à medida que elas trafegam por vários serviços em uma arquitetura de aplicativo distribuída. O CAT será descontinuado no agente .NET a partir da versão 9.0 e será removido em uma versão principal futura.

Nas versões 8.x do agente .NET, o arquivo newrelic.config padrão instalado em um host por qualquer instalador do agente .NET teria o elemento crossApplicationTracer presente e definido como enabled="true". O elemento distributedTracing não estava presente por padrão.

Na versão 9.x, isso será revertido: crossApplicationTracer não estará presente por padrão e distributedTracing estará presente com o valor padrão de enabled="true". Entretanto, o instalador do agente não substitui um arquivo newrelic.config existente ao atualizar de uma versão para outra. Portanto, se você estiver atualizando o agente da versão 8.x para a 9.x em um determinado host, o comportamento do agente nesse host não será alterado.

Remoção de API pública obsoleta dos métodos do agente

Todos os métodos de API obsoletos possuem métodos de API de substituição com funcionalidade equivalente.

Exemplos

CreateDistributedTracePayload

Se você já tinha um código parecido com 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());

substitua-o por isto:

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

AcceptDistributedTracePayload

Se você já tinha um código parecido com 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);

substitua-o por isto:

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

AdicionarParâmetro Personalizado

Se você já tinha um código parecido com 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");

substitua-o por isto:

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

Remoção das definições de configuração do agente obsoleto

As seguintes definições de configuração do agente estão sendo removidas do agente. Para tornar o caminho de atualização de 8.x para 9.x o mais tranquilo possível, não removeremos as configurações do esquema XML do arquivo newrelic.config . Porém, a lógica de configuração interna do agente será atualizada para ignorar essas configurações, e uma mensagem do log no arquivo de log do agente avisará que esses valores de configuração não terão mais efeito.

Um pouco sobre notação: para facilitar a descrição, o restante desta seção descreverá os elementos de configuração com uma abreviação de “notação de ponto” em vez de XML completo.

Por exemplo, um elemento de configuração que aparece no arquivo newrelic.config pode ter esta aparência:

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

Neste exemplo, será escrito como parameterGroups.IdentityParameters. Como todos esses elementos de configuração são filhos do elemento <configuration> de nível superior, eles são omitidos por questões de brevidade.

A maioria das opções de configuração removidas estão relacionadas à captura ou exclusão de dados de atributo. Os documentos a seguir são úteis para compreender o panorama geral da coleta de dados de atributo do agente e como ela é configurada:

• Atributo do agente
• Habilitar e desabilitar atributo (.NET)
• Exemplos 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>