API do agente .NET

O agente .NET da New Relic inclui uma API que permite estender a funcionalidade padrão do agente. Por exemplo, você pode usar a API do agente .NET para:

Personalize o nome do seu aplicativo
Criar parâmetro de transação personalizado
Relatar erros personalizados e métricas

Você também pode personalizar alguns dos comportamentos padrão do agente .NET ajustando as definições de configuração ou usando instrumentação personalizada.

Requisitos

Para usar a API do agente .NET, certifique-se de ter a versão mais recente do agente .NET. Em seguida, adicione uma referência ao agente no seu projeto usando uma das duas opções abaixo:

Adicione uma referência a NewRelic.Api.Agent.dll ao seu projeto.
OU
Visualize e baixe o pacote de API da biblioteca de pacotes NuGet.

Notas sobre Injeção de Dependência

Se você consumir a API do agente através de Microsoft.Extensions.DependencyInjection (ou um contêiner semelhante), existem duas armadilhas que desativarão silenciosamente sua instrumentação personalizada sem produzir nenhum erro. Ambos se devem ao fato de que IAgent é um identificador de longa duração, mas CurrentTransaction e CurrentSpan são visualizações com escopo de requisição que devem ser relidas a cada chamada.

Registre `IAgent` tardiamente, não antecipadamente

GetAgent() deve ser chamado depois que o profiler terminar de ser anexado. Se você resolvê-lo antecipadamente enquanto o contêiner de DI está sendo construído, poderá armazenar em cache o espaço reservado no-op que a API retorna antes que o agente esteja ativo, deixando o aplicativo com uma API silenciosamente desativada durante a vida útil do processo. Use uma factory lambda para que a chamada seja diferida para a primeira resolução:

// ❌ Eager — may capture the no-op placeholder
builder.Services.AddSingleton<IAgent>(NewRelic.Api.Agent.NewRelic.GetAgent());

// ✅ Lazy — GetAgent() runs on first resolution, after the profiler is ready
builder.Services.AddSingleton<IAgent>(_ => NewRelic.Api.Agent.NewRelic.GetAgent());

Não armazene `ITransaction` ou `ISpan` em cache nos campos

IAgent em si é seguro para armazenar, mas CurrentTransaction e CurrentSpan devem ser lidos novamente cada vez que você os usar. Capturá-los em um construtor ou campo vincula seu serviço a qualquer requisição que estivesse em andamento quando o campo foi atribuído pela primeira vez. Cada chamada subsequente então grava atributos, erros e eventos em uma transação que já foi encerrada, e os dados nunca aparecem nas transações que você está realmente analisando.

// ❌ Captures one request's transaction forever
public class BuggyService
{
    private readonly ITransaction _transaction;
    public BuggyService(IAgent agent) => _transaction = agent.CurrentTransaction;
}

// ✅ Fetch per-call
public class WorkService
{
    private readonly IAgent _agent;
    public WorkService(IAgent agent) => _agent = agent;

    public void DoWork()
    {
        var transaction = _agent.CurrentTransaction;
        transaction.AddCustomAttribute("key", "value");
    }
}

Para um passo a passo completo e executável, incluindo exemplos de antipadrões verificados na compilação, consulte o exemplo de injeção de dependência de API no repositório newrelic-dotnet-examples.

Lista de chamadas de API

A lista a seguir contém as diferentes chamadas que você pode fazer com a API, incluindo sintaxe, requisitos, funcionalidade e exemplos:

Sintaxe

NewRelic.Api.Agent.NewRelic.DisableBrowserMonitoring([boolean $override])

Desabilitar injeção automática de monitoramento de trecho do Browser em páginas específicas.

Requisitos

Compatível com todas as versões do agente.
Deve ser chamado dentro de uma transação.

Descrição

Adicione esta chamada para desativar a injeção automática do script em páginas específicas. Você também pode adicionar uma substituição opcional para desativar a injeção manual e automática. Em ambos os casos, coloque esta chamada de API o mais próximo possível do topo da visualização na qual você deseja desabilitar o navegador.

Dica

Compare GetBrowserTimingHeader(), que adiciona o script do navegador à página.

Parâmetro

Parâmetro	Descrição
`$override` boleano	Opcional. Quando `true`, desativa toda injeção de script do navegador. Este sinalizador afeta a injeção manual e automática. Isso também substitui a chamada `GetBrowserTimingHeader()` .

Descrição

$override

boleano

Opcional. Quando true, desativa toda injeção de script do navegador. Este sinalizador afeta a injeção manual e automática. Isso também substitui a chamada GetBrowserTimingHeader() .

Exemplos

Desativar injeção automática

Este exemplo desabilita apenas a injeção automática do trecho:

NewRelic.Api.Agent.NewRelic.DisableBrowserMonitoring();

Desativar injeção automática e manual

Este exemplo desativa a injeção automática e manual do trecho:

NewRelic.Api.Agent.NewRelic.DisableBrowserMonitoring(true);

Sintaxe

NewRelic.Api.Agent.NewRelic.GetAgent()

Obtenha acesso ao agente por meio da interface IAgent .

Requisitos

Versão do agente 8.9 ou superior.
Compatível com todos os tipos de aplicativos.

Descrição

Obtenha acesso aos métodos da API do agente por meio da interface IAgent .

Valores de retorno

Uma implementação do IAgent que fornece acesso à API do IAgent.

Exemplos

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();

Sintaxe

NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader();
NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader(string nonce);

Gerar um monitoramento de HTML do browser para browsers de usuários finais.

Requisitos

Compatível com todas as versões do agente.
Deve ser chamado dentro de uma transação.

Descrição

Retorna um trecho HTML usado para ativar . O trecho instrui o navegador a buscar um pequeno arquivo JavaScript e iniciar o cronômetro da página. Você pode então inserir o trecho retornado no cabeçalho de suas páginas HTML. Para obter mais informações, consulte Adicionando aplicativos ao monitoramento do navegador.

Dica

Compare DisableBrowserMonitoring(), que desativa o script do navegador em uma página.

Parâmetro

Parâmetro	Descrição
`nonce` corda	O nonce criptográfico por solicitação usado pelas políticas da Política de Segurança de Conteúdo.

Descrição

nonce

corda

O nonce criptográfico por solicitação usado pelas políticas da Política de Segurança de Conteúdo.

Dica

Esta chamada de API requer atualizações na lista de permissões de segurança. Para obter mais informações sobre as considerações da Política de Segurança de Conteúdo (CSP), visite a página de monitoramento de compatibilidade e requisitos do navegador .

Valores de retorno

Uma string HTML a ser incorporada em um cabeçalho de página.

Exemplos

<html>
<head>
    <%= NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader()%>
    ...
</head>
<body>
...

<html>
<head>
    <%= NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader("YOUR_NONCE_VALUE")%>
    ...
</head>
<body>
...

<!DOCTYPE html>
<html lang="en">
<head>
    @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader())
    ...
</head>
<body>
...

<!DOCTYPE html>
<html lang="en">
<head>
    @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader("YOUR_NONCE_VALUE"))
    ...
</head>
<body>
...

Importante

Esta API não é compatível com Blazor Webassembly, porque o agente não consegue instrumentar o código do Webassembly. Os exemplos a seguir são apenas para o aplicativo Blazor Server. Use o método copiar e colar para adicionar o agente browser às páginas do Blazor Webassembly.

Importante

Esta API não pode ser colocada em um elemento <HeadContent> de uma página .razor . Em vez disso, ele deve ser chamado de _Layout.cshtml ou de um arquivo de layout equivalente.

<!DOCTYPE html>
<html lang="en">
<head>
    @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader())
    ...
</head>
<body>
...

<!DOCTYPE html>
<html lang="en">
<head>
    @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader("YOUR_NONCE_VALUE"))
    ...
</head>
<body>
...

Sintaxe

NewRelic.Api.Agent.NewRelic.GetLinkingMetadata();

Retorna pares de valores principais que podem ser usados para vincular rastreamento ou entidade.

Requisitos

Versão do agente 8.19 ou superior.
Compatível com todos os tipos de aplicativos.

Descrição

O dicionário de pares de valores principais retornados inclui itens usados para vincular rastreamento e entidade no produto APM . Ele conterá apenas itens com valores significativos. Por exemplo, se distributed tracing estiver desabilitado, trace.id não será incluído.

Valores de retorno

Dictionary <string, string>() retornado inclui itens usados para vincular rastreamento e entidade no produto APM.

Exemplos

NewRelic.Api.Agent.IAgent Agent = NewRelic.Api.Agent.NewRelic.GetAgent();
var linkingMetadata = Agent.GetLinkingMetadata();
foreach (KeyValuePair<string, string> kvp in linkingMetadata)
{
    Console.WriteLine("Key = {0}, Value = {1}", kvp.Key, kvp.Value);
}

Sintaxe

public interface IAgent

Fornece acesso a artefatos e métodos do agente, como a transação em execução no momento.

Requisitos

Versão do agente 8.9 ou superior.
Compatível com todos os tipos de aplicativos.

Descrição

Fornece acesso a artefatos e métodos do agente, como a transação em execução no momento. Para obter uma referência a IAgent, use GetAgent.

Propriedades

Nome	Descrição
Transação Atual	Propriedade que fornece acesso à transação atualmente em execução por meio da interface ITransaction . Deve ser chamado dentro de uma transação.
Período Atual	Propriedade que fornece acesso ao intervalo atualmente em execução por meio da interface ISpan .

Exemplos

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;

Sintaxe

public interface ITransaction

Fornece acesso a métodos específicos de transação na API New Relic.

Descrição

Fornece acesso a métodos específicos de transação na API do agente .NET da New Relic. Para obter uma referência a ITransaction, use o método de transação atual disponível em IAgent.

Os seguintes métodos estão disponíveis em ITransaction:

Nome	Descrição
`InsertDistributedTraceHeaders`	Adiciona dados distributed tracing a uma solicitação de saída (veja abaixo para mais detalhes).
`AcceptDistributedTraceHeaders`	Aceita dados distributed tracing recebidos de outro serviço (veja abaixo para mais detalhes).
`AddCustomAttribute`	Adicione informações contextuais do seu aplicativo à transação atual na forma de atributo (veja abaixo para mais detalhes).
`CurrentSpan`	Fornece acesso ao span em execução no momento, que fornece acesso a métodos específicos do span na API do New Relic (veja abaixo para mais detalhes).
`SetUserId`	Associa um ID de usuário à transação atual (veja abaixo para mais detalhes).
`RecordDatastoreSegment`	Permite que um armazenamento de dados não suportado seja instrumentado (veja abaixo para mais detalhes).

Sintaxe

void InsertDistributedTraceHeaders(carrier, setter)

Adiciona dados distributed tracing a uma mensagem de saída para outro serviço instrumentado.

Descrição

ITransaction.InsertDistributedTraceHeaders modifica o objeto portador que é passado adicionando cabeçalhos de W3C Trace Context e cabeçalhos de rastreamento distribuídos New Relic . Os cabeçalhos do New Relic podem ser desabilitados com <distributedTracing excludeNewrelicHeader="true" /> na configuração.

Parâmetro

Nome	Descrição
`carrier` <T>	Obrigatório. Um armazenamento de pares de principais de valor onde dados distributed tracing são inseridos. Isso precisa existir em qualquer objeto de mensagem que esteja sendo passado do serviço de chamada para o serviço chamado, por meio de qualquer transporte que esteja sendo usado. Por exemplo, para mensagens do Azure Service Bus, o tipo `ServiceBusMessage` tem uma propriedade`ApplicationProperties` que é um `IDictionary<string,object>`. Quando você deseja implementar distributed tracing personalizado para um canal de comunicação não instrumentado (por exemplo, uma fila de mensagens), você precisa descobrir qual opção de armazenamento de par principal de valor (portadora) existe para esse canal.
`setter` Action<T, string, string>	Obrigatório. Uma ação definida pelo usuário para inserir dados de rastreamento na transportadora. Veja o exemplo abaixo.

Nome

Descrição

carrier

<T>

Obrigatório. Um armazenamento de pares de principais de valor onde dados distributed tracing são inseridos. Isso precisa existir em qualquer objeto de mensagem que esteja sendo passado do serviço de chamada para o serviço chamado, por meio de qualquer transporte que esteja sendo usado. Por exemplo, para mensagens do Azure Service Bus, o tipo ServiceBusMessage tem uma propriedadeApplicationProperties que é um IDictionary<string,object>. Quando você deseja implementar distributed tracing personalizado para um canal de comunicação não instrumentado (por exemplo, uma fila de mensagens), você precisa descobrir qual opção de armazenamento de par principal de valor (portadora) existe para esse canal.

setter

Action<T, string, string>

Obrigatório. Uma ação definida pelo usuário para inserir dados de rastreamento na transportadora. Veja o exemplo abaixo.

Considerações de uso

Distributed tracing deve estar ativado.
Esta API só pode ser usada no contexto de uma transação existente.

Exemplo

Você pode encontrar um exemplo completo que pode ser criado e executado para demonstrar o uso desta API aqui.

// Get a reference to the agent, which lets you get a reference to the current transaction
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// In this example, we are using Azure Service Bus.  The `ServiceBusMessage` type has an `ApplicationProperties` property for custom key/value pairs.

// Create the outbound message
ServiceBusMessage message = new ("Hello, world!");

// Define the setter Action.  The `ApplicationProperties` dictionary is the trace data carrier.
var setter = new Action<ServiceBusMessage, string, string>((carrier, key, value) => { carrier.ApplicationProperties?.Set(key, value); });

// Call the API to add the distributed tracing data to the message
currentTransaction.InsertDistributedTraceHeaders(message, setter);

// Send the message

Sintaxe

void AcceptDistributedTraceHeaders(carrier, getter, transportType)

Aceita dados distributed tracing de uma mensagem de entrada de outro serviço instrumentado.

Descrição

ITransaction.AcceptDistributedTraceHeaders é usado para vincular os intervalos em um trace aceitando uma carga gerada por ou gerada por algum InsertDistributedTraceHeaders outro W3C Trace Context compatível com tracer. Este método aceita o armazenamento principal de valor de uma solicitação recebida, procura W3C Trace Context dados e, se não forem encontrados, retorna aos New Relic distributed trace dados .

Parâmetro

Nome	Descrição
`carrier` <T>	Obrigatório. Um par de armazenamento de valores principais onde dados distributed tracing foram inseridos pelo serviço de chamada. Isso precisa existir em qualquer objeto de mensagem que esteja sendo passado do serviço de chamada para o serviço chamado, por meio de qualquer transporte que esteja sendo usado. Por exemplo, para mensagens do Azure Service Bus, o tipo `ServiceBusReceivedMessage` tem uma propriedade`ApplicationProperties` que é um `IDictionary<string,object>`. Quando você deseja implementar distributed tracing personalizado para um canal de comunicação não instrumentado (por exemplo, uma fila de mensagens), você precisa descobrir qual opção de armazenamento de par principal de valor (portadora) existe para esse canal.
`getter` Func<T, string, IEnumerable<string>>	Obrigatório. Uma função definida pelo usuário para extrair dados de rastreamento da transportadora. Veja o exemplo abaixo.
`transportType` Enumeração TransportType	Obrigatório. Descreve o transporte da carga útil de entrada (por exemplo `TransportType.Queue`). A lista completa está definida aqui.

Nome

Descrição

carrier

<T>

Obrigatório. Um par de armazenamento de valores principais onde dados distributed tracing foram inseridos pelo serviço de chamada. Isso precisa existir em qualquer objeto de mensagem que esteja sendo passado do serviço de chamada para o serviço chamado, por meio de qualquer transporte que esteja sendo usado. Por exemplo, para mensagens do Azure Service Bus, o tipo ServiceBusReceivedMessage tem uma propriedadeApplicationProperties que é um IDictionary<string,object>. Quando você deseja implementar distributed tracing personalizado para um canal de comunicação não instrumentado (por exemplo, uma fila de mensagens), você precisa descobrir qual opção de armazenamento de par principal de valor (portadora) existe para esse canal.

getter

Func<T, string, IEnumerable<string>>

Obrigatório. Uma função definida pelo usuário para extrair dados de rastreamento da transportadora. Veja o exemplo abaixo.

transportType

Enumeração TransportType

Obrigatório. Descreve o transporte da carga útil de entrada (por exemplo TransportType.Queue). A lista completa está definida aqui.

Considerações de uso

Distributed tracing deve estar ativado.
Esta API só pode ser usada no contexto de uma transação existente.
AcceptDistributedTraceHeaders será ignorado se InsertDistributedTraceHeaders ou AcceptDistributedTraceHeaders já tiver sido chamado para esta transação.

Exemplo

Você pode encontrar um exemplo completo que você pode construir e executar para demonstrar o uso desta API aqui

// Get a reference to the agent, which lets you get a reference to the current transaction
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// In this example, we are using Azure Service Bus.  The `ServiceBusMessage` type has an `ApplicationProperties` property for custom key/value pairs.

// Recieve an incoming message.  Assume that `receiver` is a previously-configured `ServiceBusReceiver`
ServiceBusReceivedMessage message = await receiver.ReceiveMessageAsync();

// Define the getter Func.  The `ApplicationProperties` dictionary is the trace data carrier.
IEnumerable<string> Getter(IDictionary<string, object> carrier, string key)
{
  var data = new List<string>();
  if (carrier == null)
  {
    return data;
  }
  object value;
  if (applicationProperties.TryGetValue(key, out value))
  {
    if (value != null)
    {
      data.Add(value.ToString());
    }
  }
  return data;
}

// Call the API to accept the distributed tracing data from the message
currentTransaction.AcceptDistributedTraceHeaders(message.ApplicationProperties, Getter, TransportType.Queue);

Sintaxe

ITransaction AddCustomAttribute(string key, object value)

Adiciona informações contextuais sobre sua aplicação à transação atual na forma de atributo.

Este método requer a versão do agente .NET e a API do agente .NET versão 8.24.244.0 ou superior. Ele substituiu o obsoleto AddCustomParameter.

Parâmetro

Parâmetro	Descrição
`key` corda	Identifica as informações que estão sendo relatadas. Também conhecido como nome. Chaves vazias não são suportadas. As chaves são limitadas a 255 bytes. atributo com chaves maiores que 255 bytes será ignorado.
`value` objeto	O valor que está sendo informado. Nota: `null` valores não serão registrados.

Descrição

key

corda

Identifica as informações que estão sendo relatadas. Também conhecido como nome.

Chaves vazias não são suportadas.
As chaves são limitadas a 255 bytes. atributo com chaves maiores que 255 bytes será ignorado.

value

objeto

O valor que está sendo informado.

Nota: null valores não serão registrados.

Tipo .NET	Como o valor será representado
`byte`, `Int16`, `Int32`, `Int64` `sbyte`, `UInt16`, `UInt32`, `UInt64`	Como valor integral.
`float`, `double`, `decimal`	Um número baseado em decimal.
`string`	Uma string truncada após 255 bytes. Strings vazias são suportadas.
`bool`	Verdadeiro ou falso.
`DateTime`	Uma representação de string seguindo o formato ISO-8601, incluindo informações de fuso horário: Exemplo: `2020-02-13T11:31:19.5767650-08:00`
`TimeSpan`	Um número decimal que representa o número de segundos.
`arrays`, `Lists` e outros tipos de `IEnumerable`	Serializado como um array JSON. Elementos individuais seguem as mesmas regras de conversão de tipos acima. Elementos nulos são filtrados. Arrays vazios e arrays contendo apenas valores nulos não são registrados. Requer o agente .NET versão 10.50.0 ou superior.
todo o resto	O método `ToString()` será aplicado. Os tipos personalizados devem ter uma implementação de `Object.ToString()` ou gerarão uma exceção.

Devoluções

Uma referência à transação atual.

Considerações de uso

Para obter detalhes sobre os tipos de dados suportados, consulte atributo personalizado.

Exemplo

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
transaction.AddCustomAttribute("customerName","Bob Smith")
    .AddCustomAttribute("currentAge",31)
    .AddCustomAttribute("birthday", new DateTime(2000, 02, 14))
    .AddCustomAttribute("waitTime", TimeSpan.FromMilliseconds(93842))
    .AddCustomAttribute("colors", new[] { "red", "green", "blue" })
    .AddCustomAttribute("ids", new List<int> { 1, 2, 3 });

Fornece acesso ao span em execução atualmente, disponibilizando métodos específicos do span na API New Relic.

Exemplo

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); 
ITransaction transaction = agent.CurrentTransaction; 
ISpan currentSpan = transaction.CurrentSpan;

Sintaxe

ITransaction SetUserId(string userId)

Associa um ID de usuário à transação atual.

Este método requer o agente .NET e a API do agente .NET versão 10.9.0 ou superior.

Parâmetro

Parâmetro	Descrição
`userId` corda	O ID do usuário a ser associado a esta transação. `null`, os valores vazios e de espaço em branco serão ignorados.

Descrição

userId

corda

O ID do usuário a ser associado a esta transação.

null, os valores vazios e de espaço em branco serão ignorados.

Exemplo

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); 
ITransaction transaction = agent.CurrentTransaction; 
transaction.SetUserId("BobSmith123");

Sintaxe

SegmentWrapper? RecordDatastoreSegment(string vendor, string model, string operation, string? commandText = null, string? host = null, string? portPathOrID = null, string? databaseName = null)

Permite que um armazenamento de dados não suportado seja instrumentado da mesma forma que o agente .NET instrumenta automaticamente seus datastores suportados.

Este método requer o agente .NET e a API do agente .NET versão 10.22.0 ou superior.

Parâmetro

Parâmetro	Descrição
`vendor` corda	Nome do fornecedor do armazenamento de dados, como MySQL, MSSQL ou MongoDB.
`model` corda	Nome da tabela ou identificador semelhante em um armazenamento de dados não relacional.
`operation` corda	Operação sendo executada, como "SELECT" ou "UPDATE" para SQL banco de dados.
`commandText` corda?	Opcional. Consulta, ou descritor semelhante em um armazenamento de dados não relacional.
`host` corda?	Opcional. Servidor que hospeda o armazenamento de dados.
`portPathOrID` corda?	Opcional. Porta, caminho ou outro identificador, pareado com o host para auxiliar na identificação do armazenamento de dados.
`databaseName` corda?	Opcional. Nome do armazenamento de dados ou identificador semelhante.

Devoluções

Wrapper de segmento IDisposable que cria e finaliza o segmento automaticamente.

Exemplo

var transaction = NewRelic.Api.Agent.NewRelic.GetAgent().CurrentTransaction;
using (transaction.RecordDatastoreSegment(vendor, model, operation,
     commandText, host, portPathOrID, databaseName))
{
     DatastoreWorker();
}

Sintaxe

Public interface ISpan

Fornece acesso a métodos específicos de span na API New Relic.

Descrição

Fornece acesso a métodos específicos de span na API do agente .NET da New Relic. Para obter uma referência a ISpan, use:

A propriedade CurrentSpan em IAgent (recomendado).
A propriedade CurrentSpan em ITransaction.

Esta seção contém descrições e parâmetros dos métodos ISpan :

Nome	Descrição
`AddCustomAttribute`	Adicione informações contextuais do seu aplicativo ao intervalo atual na forma de atributo (veja abaixo para mais detalhes).
`SetName`	Altera o nome do intervalo/segmento/métrica atual que será reportado ao New Relic (veja abaixo para mais detalhes).

Adiciona informações contextuais sobre sua aplicação ao intervalo atual na forma de atributo.

Este método requer a versão do agente .NET e a API do agente .NET versão 8.25 ou superior.

Sintaxe

ISpan AddCustomAttribute(string key, object value)

Parâmetro

Descrição

key

corda

Identifica as informações que estão sendo relatadas. Também conhecido como nome.

Chaves vazias não são suportadas.
As chaves são limitadas a 255 bytes. atributo com chaves maiores que 255 bytes será ignorado.

value

objeto

O valor que está sendo informado.

Nota: null valores não serão registrados.

Tipo .NET	Como o valor será representado
`byte`, `Int16`, `Int32`, `Int64` `sbyte`, `UInt16`, `UInt32`, `UInt64`	Como valor integral.
`float`, `double`, `decimal`	Um número baseado em decimal.
`string`	Uma string truncada após 255 bytes. Strings vazias são suportadas.
`bool`	Verdadeiro ou falso.
`DateTime`	Uma representação de string seguindo o formato ISO-8601, incluindo informações de fuso horário: Exemplo: `2020-02-13T11:31:19.5767650-08:00`
`TimeSpan`	Um número decimal que representa o número de segundos.
`arrays`, `Lists` e outros tipos de `IEnumerable`	Serializado como um array JSON. Elementos individuais seguem as mesmas regras de conversão de tipos acima. Elementos nulos são filtrados. Arrays vazios e arrays contendo apenas valores nulos não são registrados. Requer o agente .NET versão 10.50.0 ou superior.
todo o resto	O método `ToString()` será aplicado. Os tipos personalizados devem ter uma implementação de `Object.ToString()` ou gerarão uma exceção.

Devoluções

Uma referência ao intervalo atual.

Considerações de uso

Para obter detalhes sobre os tipos de dados suportados, consulte o guia de atributo personalizado.

Exemplos

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ISpan currentSpan = agent.CurrentSpan;

currentSpan
    .AddCustomAttribute("customerName","Bob Smith")
    .AddCustomAttribute("currentAge",31)
    .AddCustomAttribute("birthday", new DateTime(2000, 02, 14))
    .AddCustomAttribute("waitTime", TimeSpan.FromMilliseconds(93842))
    .AddCustomAttribute("colors", new[] { "red", "green", "blue" })
    .AddCustomAttribute("ids", new List<int> { 1, 2, 3 });

Altera o nome do segmento/span atual que será reportado ao New Relic. Para segmentos/extensões resultantes de instrumentação personalizada, o nome da métrica relatado à New Relic também será alterado.

Este método requer a versão do agente .NET e a API do agente .NET versão 10.1.0 ou mais alto.

Sintaxe

ISpan SetName(string name)

Parâmetro

Parâmetro	Descrição
`name` corda	O novo nome do intervalo/segmento.

Descrição

name

corda

O novo nome do intervalo/segmento.

Devoluções

Uma referência ao intervalo atual.

Exemplos

[Trace]
public void MyTracedMethod()
{
    IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); 
    ISpan currentSpan = agent.CurrentSpan; 

    currentSpan.SetName("MyCustomName");
}

Sintaxe

NewRelic.Api.Agent.NewRelic.IgnoreApdex()

Ignore a transação atual ao calcular o Apdex.

Requisitos

Compatível com todas as versões do agente.

Descrição

Ignora a transação atual ao calcular sua pontuação Apdex. Isso é útil quando você tem transações muito curtas ou muito longas (como downloads de arquivos) que podem distorcer sua pontuação Apdex.

Exemplos

NewRelic.Api.Agent.NewRelic.IgnoreApdex();

Sintaxe

NewRelic.Api.Agent.NewRelic.IgnoreTransaction()

Não instrumento a transação atual.

Requisitos

Compatível com todas as versões do agente.
Deve ser chamado dentro de uma transação.

Descrição

Ignora a transação atual.

Dica

Você também pode ignorar a transação através de um arquivo XML de instrumentação personalizado.

Exemplos

NewRelic.Api.Agent.NewRelic.IgnoreTransaction();

Sintaxe

NewRelic.Api.Agent.NewRelic.IncrementCounter(string $metric_name)

Aumente o contador de uma métrica personalizada em 1.

Requisitos

Compatível com todas as versões do agente.
Compatível com todos os tipos de aplicativos.

Descrição

Aumente o contador de uma métrica personalizada em 1. Para visualizar essas métricas personalizadas, utilize o criador de consulta para pesquisar métricas e criar gráficos customizáveis. Consulte também RecordMetric() e RecordResponseTimeMetric().

Importante

Ao criar uma métrica personalizada, comece o nome com Custom/ (por exemplo, Custom/MyMetric). Para mais informações sobre nomenclatura, veja Coletar métrica personalizada.

Parâmetro

Parâmetro	Descrição
`$metric_name` corda	Obrigatório. O nome da métrica a ser incrementada.

Descrição

$metric_name

corda

Obrigatório. O nome da métrica a ser incrementada.

Exemplos

NewRelic.Api.Agent.NewRelic.IncrementCounter("Custom/ExampleMetric");

Sobrecargas

Observe um erro e reporte à New Relic, juntamente com um atributo personalizado opcional.

NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception);
NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception, IDictionary<TKey, TValue> $attributes);
NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes);
NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes, bool $is_expected);

Requisitos

Esta chamada de API é compatível com:

Todas as versões do agente
Todos os tipos de aplicativos

Descrição

Observe um erro e relate-o à New Relic junto com um atributo personalizado opcional. Para cada transação, o agente retém apenas a exceção e o atributo da primeira chamada para NoticeError(). Você pode passar uma exceção real ou uma string para capturar uma mensagem de erro arbitrária.

Se este método for invocado em uma transação, o agente reportará a exceção na transação pai. Se for invocado fora de uma transação, o agente cria um tracede erro e categoriza o erro na interface do New Relic como uma NewRelic.Api.Agent.NoticeError chamada de API. Se invocada fora de uma transação, a chamada NoticeError() não contribuirá para a taxa de erros de um aplicativo.

O agente adiciona o atributo apenas ao erro de rastreamento; ele não os envia para New Relic. Para obter mais informações, consulte AddCustomAttribute().

Ao passar uma exceção para NoticeError(), determine a exceção mais interna usando a API Exception.GetBaseException() da Microsoft. Essa exceção mais interna representa a causa raiz do erro e é o que é exibido no APM. Todo o stack trace da exceção de nível superior é relatado, pois fornece contexto relevante e detalhes de execução. Essa abordagem oferece as informações de erro mais específicas da exceção base, preservando o contexto completo de como o erro se propagou pelo aplicativo.

Os erros relatados com esta API ainda são enviados para a New Relic quando são relatados em uma transação que resulta em um código de status HTTP, como 404, configurado para ser ignorado pela configuração do agente. Para obter mais informações, consulte nossa documentação sobre gerenciamento de erros no APM.

Revise as seções abaixo para ver exemplos de como usar esta chamada.

NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception)

Parâmetro	Descrição
`$exception` Exceção	Obrigatório. O `Exception` que você deseja instrumento. Somente os primeiros 10.000 caracteres do stack trace são retidos.

Parâmetro

Descrição

$exception

Exceção

Obrigatório. O Exception que você deseja instrumento. Somente os primeiros 10.000 caracteres do stack trace são retidos.

NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception, IDictionary<TKey, TValue> $attributes)

Parâmetro	Descrição
`$exception` Exceção	Obrigatório. O `Exception` que você deseja instrumento. Somente os primeiros 10.000 caracteres do stack trace são retidos.
`$attributes` IDictionary<TKey, TValue>	Especifique pares de valor principal de atributo para anotar a mensagem de erro. O `TKey` deve ser uma string, o `TValue` pode ser uma string ou um objeto.

Parâmetro

Descrição

$exception

Exceção

Obrigatório. O Exception que você deseja instrumento. Somente os primeiros 10.000 caracteres do stack trace são retidos.

$attributes

IDictionary<TKey, TValue>

Especifique pares de valor principal de atributo para anotar a mensagem de erro. O TKey deve ser uma string, o TValue pode ser uma string ou um objeto.

NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes)

Parâmetro	Descrição
`$error_message` corda	Obrigatório. Especifique uma string para reportar ao New Relic como se fosse uma exceção. Este método cria evento de erro e rastreamento de erro. Somente os primeiros 1.023 caracteres são retidos no evento de erro, enquanto o rastreamento de erro retém a mensagem completa.
`$attributes` IDictionary<TKey, TValue>	Obrigatório (pode ser nulo). Especifique pares de valor principal de atributo para anotar a mensagem de erro. O `TKey` deve ser uma string, o `TValue` pode ser uma string ou objeto, para não enviar nenhum atributo passe `null`.

Parâmetro

Descrição

$error_message

corda

Obrigatório. Especifique uma string para reportar ao New Relic como se fosse uma exceção. Este método cria evento de erro e rastreamento de erro. Somente os primeiros 1.023 caracteres são retidos no evento de erro, enquanto o rastreamento de erro retém a mensagem completa.

$attributes

IDictionary<TKey, TValue>

Obrigatório (pode ser nulo). Especifique pares de valor principal de atributo para anotar a mensagem de erro. O TKey deve ser uma string, o TValue pode ser uma string ou objeto, para não enviar nenhum atributo passe null.

NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes, bool $is_expected)

Parâmetro	Descrição
`$error_message` corda	Obrigatório. Especifique uma string para reportar ao New Relic como se fosse uma exceção. Este método cria evento de erro e rastreamento de erro. Somente os primeiros 1.023 caracteres são retidos no evento de erro, enquanto o rastreamento de erro retém a mensagem completa.
`$attributes` IDictionary<TKey, TValue>	Obrigatório (pode ser nulo). Especifique pares de valor principal de atributo para anotar a mensagem de erro. O `TKey` deve ser uma string, o `TValue` pode ser uma string ou objeto, para não enviar nenhum atributo passe `null`.
`$is_expected` bool	Marque o erro como esperado para que não afete a pontuação do Apdex e a taxa de erros.

Parâmetro

Descrição

$error_message

corda

$attributes

IDictionary<TKey, TValue>

$is_expected

bool

Marque o erro como esperado para que não afete a pontuação do Apdex e a taxa de erros.

Exemplos

Passe uma exceção sem atributo personalizado

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

Passe uma exceção com atributo personalizado

try
{
    string ImNotABool = "43";
    bool.Parse(ImNotABool);
}
catch (Exception ex)
{
    var errorAttributes = new Dictionary<string, string>() {{"foo", "bar"},{"baz", "luhr"}};
    NewRelic.Api.Agent.NewRelic.NoticeError(ex, errorAttributes);
}

Passar uma string de mensagem de erro com atributo personalizado

try
{
    string ImNotABool = "43";
    bool.Parse(ImNotABool);
}
catch (Exception ex)
{
    var errorAttributes = new Dictionary<string, string>{{"foo", "bar"},{"baz", "luhr"}};
    NewRelic.Api.Agent.NewRelic.NoticeError("String error message", errorAttributes);
}

Passar uma string de mensagem de erro sem atributo personalizado

try
{
    string ImNotABool = "43";
    bool.Parse(ImNotABool);
}
catch (Exception ex)
{
    NewRelic.Api.Agent.NewRelic.NoticeError("String error message", null);
}

Passe uma string de mensagem de erro e marque-a como esperado

try
{
    string ImNotABool = "43";
    bool.Parse(ImNotABool);
}
catch (Exception ex)
{
    NewRelic.Api.Agent.NewRelic.NoticeError("String error message", null, true);
}

Sintaxe

NewRelic.Api.Agent.NewRelic.RecordCustomEvent(string eventType, IEnumerable<string, object> attributeValues)

Registra um evento personalizado com o nome e atributo fornecidos.

Requisitos

Compatível com todas as versões do agente.
Compatível com todos os tipos de aplicativos.

Descrição

Registra um evento personalizado com o nome e atributo fornecido, que você pode consultar no criador de consulta. Para verificar se um evento está sendo registrado corretamente, procure os dados no dashboard.

Importante

O envio de muitos eventos pode aumentar a sobrecarga de memória do agente.
Além disso, postagens com tamanho superior a 1MB (10^6 bytes) não serão gravadas independente do número máximo de eventos.
evento personalizado estão limitados a 64 atributo.
Para mais informações sobre como são processados os valores de atributo personalizado, consulte o guia atributo personalizado .

Parâmetro

Parâmetro	Descrição
`eventType` corda	Obrigatório. O nome do tipo de evento a ser registrado. Strings com mais de 255 caracteres farão com que a chamada de API não seja enviada para o New Relic. O nome só pode conter caracteres alfanuméricos, sublinhados `_` e dois pontos `:`. Para restrições adicionais sobre nomes de tipos de eventos, consulte Palavras reservadas.
`attributeValues` IEnumerable<string, object>	Obrigatório. Especifique pares de valores principais de atributo para anotar o evento.

Descrição

eventType

corda

Obrigatório. O nome do tipo de evento a ser registrado. Strings com mais de 255 caracteres farão com que a chamada de API não seja enviada para o New Relic. O nome só pode conter caracteres alfanuméricos, sublinhados _ e dois pontos :. Para restrições adicionais sobre nomes de tipos de eventos, consulte Palavras reservadas.

attributeValues

IEnumerable<string, object>

Obrigatório. Especifique pares de valores principais de atributo para anotar o evento.

Exemplos

Valores de registro [#record-strings]

var eventAttributes = new Dictionary<string, object>() 
{
    {"foo", "bar"},
    {"alice", "bob"}, 
    {"age", 32}, 
    {"height", 21.3f}
};

NewRelic.Api.Agent.NewRelic.RecordCustomEvent("MyCustomEvent", eventAttributes);

Sintaxe

NewRelic.Api.Agent.NewRelic.RecordMetric(string $metric_name, single $metric_value)

Registra uma métrica personalizada com o nome fornecido.

Requisitos

Compatível com todas as versões do agente.
Compatível com todos os tipos de aplicativos.

Descrição

Registra uma métrica personalizada com o nome fornecido. Para visualizar essas métricas personalizadas, utilize o criador de consulta para pesquisar métricas e criar gráficos customizáveis. Consulte também IncrementCounter() e RecordResponseTimeMetric().

Importante

Ao criar uma métrica personalizada, comece o nome com Custom/ (por exemplo, Custom/MyMetric).

Parâmetro

Parâmetro	Descrição
`$metric_name` corda	Obrigatório. O nome da métrica a ser registrada. Apenas os primeiros 255 caracteres são mantidos.
`$metric_value` solteiro	Obrigatório. A quantidade a ser registrada para a métrica.

Descrição

$metric_name

corda

Obrigatório. O nome da métrica a ser registrada. Apenas os primeiros 255 caracteres são mantidos.

$metric_value

solteiro

Obrigatório. A quantidade a ser registrada para a métrica.

Exemplos

Registrar o tempo de resposta de um processo adormecido [#record-stopwatch]

Stopwatch stopWatch = Stopwatch.StartNew();
System.Threading.Thread.Sleep(5000);
stopWatch.Stop();
NewRelic.Api.Agent.NewRelic.RecordMetric("Custom/DEMO_Record_Metric", stopWatch.ElapsedMilliseconds);

Sintaxe

NewRelic.Api.Agent.NewRelic.RecordResponseTimeMetric(string $metric_name, Int64 $metric_value)

Registra uma métrica personalizada com o nome fornecido e o tempo de resposta em milissegundos.

Requisitos

Compatível com todas as versões do agente.
Compatível com todos os tipos de aplicativos.

Descrição

Registra o tempo de resposta em milissegundos para uma métrica personalizada. Para visualizar essas métricas personalizadas, utilize o criador de consulta para pesquisar métricas e criar gráficos customizáveis. Consulte também IncrementCounter() e RecordMetric().

Importante

Ao criar uma métrica personalizada, comece o nome com Custom/ (por exemplo, Custom/MyMetric).

Parâmetro

Parâmetro	Descrição
`$metric_name` corda	Obrigatório. O nome da métrica de tempo de resposta a ser registrada. Apenas os primeiros 255 caracteres são mantidos.
`$metric_value` Int64	Obrigatório. O tempo de resposta para gravar em milissegundos.

Descrição

$metric_name

corda

Obrigatório. O nome da métrica de tempo de resposta a ser registrada. Apenas os primeiros 255 caracteres são mantidos.

$metric_value

Int64

Obrigatório. O tempo de resposta para gravar em milissegundos.

Exemplos

Registrar o tempo de resposta de um processo adormecido [#record-stopwatch]

Stopwatch stopWatch = Stopwatch.StartNew();
System.Threading.Thread.Sleep(5000);
stopWatch.Stop();
NewRelic.Api.Agent.NewRelic.RecordResponseTimeMetric("Custom/DEMO_Record_Response_Time_Metric", stopWatch.ElapsedMilliseconds);

Sintaxe

NewRelic.Api.Agent.NewRelic.SetApplicationName(string $name[, string $name_2, string $name_3])

Defina o nome do aplicativo para agregar dados.

Requisitos

Compatível com todas as versões do agente.
Compatível com todos os tipos de aplicativos.

Descrição

Defina os nomes dos aplicativos relatados à New Relic. Para obter mais informações sobre nomenclatura de aplicativos, consulte Nomeie seu aplicativo .NET. Este método deve ser chamado uma vez, durante a inicialização de um aplicativo.

Importante

A atualização do nome do aplicativo força a reinicialização do agente. O agente descarta quaisquer dados não relatados associados a nomes de aplicativos anteriores. Alterar o nome do aplicativo várias vezes durante o ciclo de vida de um aplicativo não é recomendado devido à perda de dados associada.

Parâmetro

Parâmetro	Descrição
`$name` corda	Obrigatório. O nome do aplicativo principal.
`$name_2` `$name_3` corda	Opcional. Segundo e terceiro nomes para app agregar. Para obter mais informações, consulte Usar vários nomes para um aplicativo.

Descrição

$name

corda

Obrigatório. O nome do aplicativo principal.

$name_2

$name_3

corda

Opcional. Segundo e terceiro nomes para app agregar. Para obter mais informações, consulte Usar vários nomes para um aplicativo.

Exemplos

NewRelic.Api.Agent.NewRelic.SetApplicationName("AppName1", "AppName2");

Sintaxe

NewRelic.Api.Agent.NewRelic.SetErrorGroupCallback(Func<IReadOnlyDictionary<string,object>, string> errorGroupCallback);

Forneça um método de retorno de chamada que receba um IReadOnlyDictionary<string,object> de dados de atributo e retorne um nome de grupo de erros.

Requisitos

Esta chamada de API é compatível com:

Versão do agente 10.9.0 ou superior.
Todos os tipos de aplicativos

Descrição

Configure um método de retorno de chamada que o agente usará para determinar o nome do grupo de erros para evento de erro e rastreio. Este nome é usado na Errors Inbox para agrupar erros em grupos lógicos.

O método de retorno de chamada deve aceitar um único argumento do tipo IReadOnlyDictionary<string,object> e retornar uma string (o nome do grupo de erros). O IReadOnlyDictionary é uma coleção de dados de atributo associados a cada evento de erro, incluindo atributo personalizado.

A lista exata de atributos disponíveis para cada erro irá variar dependendo de:

Qual código do aplicativo gerou o erro
Definições de configuração do agente
Se algum atributo personalizado foi adicionado

Contudo, deverá sempre existir o seguinte atributo:

error.class
error.message
stack_trace
transactionName
request.uri
error.expected

Uma cadeia de caracteres vazia pode ser retornada para o nome do grupo de erros quando o erro não pode ser atribuído a um grupo de erros lógicos.

Parâmetro

Parâmetro	Descrição
`$callback` {'Func<IReadOnlyDictionary<string,object>,string>'}	O retorno de chamada para determinar o nome do grupo de erros com base nos dados do atributo.

Descrição

$callback

{'Func<IReadOnlyDictionary<string,object>,string>'}

O retorno de chamada para determinar o nome do grupo de erros com base nos dados do atributo.

Exemplos

Agrupar erros por nome de classe de erro:

Func<IReadOnlyDictionary<string, object>, string> errorGroupCallback = (attributes) => {
    string errorGroupName = string.Empty;
    if (attributes.TryGetValue("error.class", out var errorClass))
    {
        if (errorClass.ToString() == "System.ArgumentOutOfRangeException" || errorClass.ToString() == "System.ArgumentNullException")
        {
            errorGroupName = "ArgumentErrors";
        }
        else
        {
            errorGroupName = "OtherErrors";
        }
    }
    return errorGroupName;
};

NewRelic.Api.Agent.NewRelic.SetErrorGroupCallback(errorGroupCallback);

Erros de grupo por nome de transação:

Func<IReadOnlyDictionary<string, object>, string> errorGroupCallback = (attributes) => {
    string errorGroupName = string.Empty;
    if (attributes.TryGetValue("transactionName", out var transactionName))
    {
    if (transactionName.ToString().IndexOf("WebTransaction/MVC/Home") != -1)
    {
    errorGroupName = "HomeControllerErrors";
    }
        else
        {
            errorGroupName = "OtherControllerErrors";
        }
    }
    return errorGroupName;
};

NewRelic.Api.Agent.NewRelic.SetErrorGroupCallback(errorGroupCallback);

Sintaxe

NewRelic.Api.Agent.NewRelic.SetTransactionName(string $category, string $name)

Define o nome da transação atual.

Requisitos

Compatível com todas as versões do agente.
Deve ser chamado dentro de uma transação.

Descrição

Defina um nome de transação personalizado, a ser anexado após um prefixo inicial (WebTransaction ou OtherTransaction) com base no tipo da transação atual. Antes de usar esta chamada, certifique-se de entender as implicações dos problemas de agrupamento métrico.

Se você usar essa chamada diversas vezes na mesma transação, cada chamada substituirá a chamada anterior e a última chamada definirá o nome.

Importante

Não use colchetes [suffix] no final do nome da sua transação. O New Relic remove automaticamente os colchetes do nome. Em vez disso, use parênteses (suffix) ou outros símbolos, se necessário.

Valor exclusivo como URLs, títulos de páginas, valores hexadecimais, IDs de sessão e valores identificáveis exclusivamente não devem ser usados na nomenclatura de sua transação. Em vez disso, adicione esses dados à transação como um parâmetro personalizado com a chamada AddCustomAttribute() .

Importante

Não crie mais de 1000 nomes de transação exclusivos (por exemplo, evite nomear por URL se possível). Isso tornará seus gráficos menos úteis e você poderá atingir os limites definidos pela New Relic quanto ao número de nomes de transação exclusivos por conta. Também pode diminuir o desempenho do seu aplicativo.

Parâmetro

Parâmetro	Descrição
`$category` corda	Obrigatório. A categoria desta transação, que você pode usar para distinguir diferentes tipos de transações. O padrão é `Custom`. Apenas os primeiros 255 caracteres são mantidos.
`$name` corda	Obrigatório. O nome da transação. Apenas os primeiros 255 caracteres são mantidos.

Descrição

$category

corda

Obrigatório. A categoria desta transação, que você pode usar para distinguir diferentes tipos de transações. O padrão é Custom. Apenas os primeiros 255 caracteres são mantidos.

$name

corda

Obrigatório. O nome da transação. Apenas os primeiros 255 caracteres são mantidos.

Exemplos

Este exemplo mostra o uso desta API em um controlador ASP..NET Core MVC. A transação é criada automaticamente pela instrumentação do agente para ASP..NET Core. A primeira parte do nome da transação continuará sendo WebTransaction.

public class HomeController : Controller
{

  public IActionResult Order(string product)
  { 

    // The commented-out API call below is probably a bad idea and will lead to a metric grouping issue (MGI)
    // because too many transaction names will be created. Don't do this.
    //NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", $"ProductOrder-{product}");

    // Do this instead if you want to record request-specific data about this MVC endpoint
    var tx = NewRelic.Api.Agent.NewRelic.GetAgent().CurrentTransaction;
    tx.AddCustomAttribute("productName", product);

    // The default transaction name at this point will be: WebTransaction/MVC/Home/Order

    // Set custom transaction name
    NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", "OrderProduct");

    // Transaction name is now: WebTransaction/Other/OrderProduct

    return View();
  }
}

Este exemplo mostra o uso desta API em um aplicativo de console. Observe a [Transaction] instrumentação personalizada atributo, que é necessária para criar uma transação para o método exemplo. A primeira parte do nome da transação continuará sendo OtherTransaction.

using NewRelic.Api.Agent;

namespace SetApplicationNameConsoleExample
{
  internal class Program
  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello, World!");

        var start = DateTime.Now;
        while (DateTime.Now - start < TimeSpan.FromMinutes(2))
        {
            DoSomething();
            Thread.Sleep(TimeSpan.FromSeconds(5));
        }
    }

    [Transaction]  // Attribute-based custom instrumentation to create a transaction for this method
    static void DoSomething()
    {
        Console.WriteLine("Doing something: " + Guid.NewGuid().ToString());

        // Transaction name from default naming at this point is: OtherTransaction/Custom/SetApplicationNameConsoleExample.Program/DoSomething

        NewRelic.Api.Agent.NewRelic.SetTransactionName("Console", "MyCustomTransactionName");

        // Transaction name at this point is: OtherTransaction/Console/MyCustomTransactionName

        // Note, however, that this transaction will still have a child segment (span) named "SetApplicationNameConsoleExample.Program.DoSomething"
    }
  }
}

Sintaxe

NewRelic.Api.Agent.NewRelic.SetTransactionUri(Uri $uri)

Define o URI da transação atual.

Requisitos

Deve ser chamado dentro de uma transação.
Versão do agente 6.16 ou superior.

Importante

Este método só funciona quando usado em uma transação criada usando o atributo Transaction com a propriedade Web definida como true. (Ver instrumentação personalizada via atributo.) Ele fornece suporte para estrutura personalizada baseada na Web que o agente não suporta automaticamente.

Descrição

Defina o URI da transação atual. O URI aparece no atributo request.uri do trace da transação e do evento de transação e também pode afetar a nomenclatura da transação.

Se você usar essa chamada diversas vezes na mesma transação, cada chamada substituirá a chamada anterior. A última chamada define o URI.

Observação: a partir da versão 8.18 do agente, o valor do atributo request.uri é definido como o valor da propriedade Uri.AbsolutePath do objeto System.Uri passado para a API.

Parâmetro

Parâmetro	Descrição
`$uri` Uri	O URI desta transação.

Descrição

$uri

Uri

O URI desta transação.

Exemplos

var uri = new System.Uri("https://www.mydomain.com/path");
NewRelic.Api.Agent.NewRelic.SetTransactionUri(uri);

Sintaxe

NewRelic.Api.Agent.NewRelic.SetUserParameters(string $user_value, string $account_value, string $product_value)

Crie um atributo personalizado relacionado ao usuário. AddCustomAttribute é mais flexível.

Requisitos

Compatível com todas as versões do agente.
Deve ser chamado dentro de uma transação.

Descrição

Dica

Esta chamada permite apenas atribuir valores a chaves pré-existentes. Para um método mais flexível para criar pares de valores principais, use AddCustomAttribute().

Definir atributo personalizadorelacionado ao usuário para associar à visualização da página do navegador (nome do usuário, nome da conta e nome do produto). Os valores são automaticamente associados a chaves pré-existentes (user, account e product) e, em seguida, anexados à transação APM pai. Você também pode anexar (ou "encaminhar") esses atributos ao evento PageView do navegador.

Parâmetro

Parâmetro	Descrição
`$user_value` corda	Obrigatório (pode ser nulo). Especifique um nome ou nome de usuário para associar a esta visualização de página. Este valor é atribuído à chave `user` .
`$account_value` corda	Obrigatório (pode ser nulo). Especifique o nome de uma conta de usuário a ser associada a esta visualização de página. Este valor é atribuído à chave `account` .
`$product_value` corda	Obrigatório (pode ser nulo). Especifique o nome de um produto a ser associado a esta visualização de página. Este valor é atribuído à chave `product` .

Descrição

$user_value

corda

Obrigatório (pode ser nulo). Especifique um nome ou nome de usuário para associar a esta visualização de página. Este valor é atribuído à chave user .

$account_value

corda

Obrigatório (pode ser nulo). Especifique o nome de uma conta de usuário a ser associada a esta visualização de página. Este valor é atribuído à chave account .

$product_value

corda

Obrigatório (pode ser nulo). Especifique o nome de um produto a ser associado a esta visualização de página. Este valor é atribuído à chave product .

Exemplos

Registre três atributos de usuários

NewRelic.Api.Agent.NewRelic.SetUserParameters("MyUserName", "MyAccountName", "MyProductName");

Registre dois atributos de usuário e um atributo vazio

NewRelic.Api.Agent.NewRelic.SetUserParameters("MyUserName", "", "MyProductName");

Sintaxe

NewRelic.Api.Agent.NewRelic.StartAgent()

Inicie o agente se ele ainda não tiver sido iniciado. Geralmente desnecessário.

Requisitos

Compatível com todas as versões do agente.
Compatível com todos os tipos de aplicativos.

Descrição

Inicia o agente se ainda não tiver sido iniciado. Essa chamada geralmente é desnecessária, pois o agente inicia automaticamente quando atinge um método instrumentado, a menos que você desative autoStart. Se você usar SetApplicationName(), certifique-se de definir o nome do aplicativo antes de iniciar o agente.

Dica

Este método inicia o agente de forma assíncrona (o que significa que não bloqueará a inicialização do aplicativo), a menos que você habilite syncStartup ou sendDataOnExit.

Exemplos

NewRelic.Api.Agent.NewRelic.StartAgent();

Sintaxe

NewRelic.Api.Agent.TraceMetadata;

Retorna propriedades no ambiente de execução atual usado para dar suporte ao rastreamento.

Requisitos

Versão do agente 8.19 ou superior.
Compatível com todos os tipos de aplicativos.
Distributed tracing deve ser ativado para obter valores significativos.

Descrição

Fornece acesso às seguintes propriedades:

Propriedades

Nome	Descrição
`TraceId`	Retorna uma string representando o trace atualmente em execução. Se o ID trace não estiver disponível ou distributed tracing estiver desativado, o valor será `string.Empty`.
`SpanId`	Retorna uma string que representa o intervalo em execução no momento. Se o ID do período não estiver disponível ou distributed tracing estiver desativado, o valor será `string.Empty`.
`IsSampled`	Retornará `true` se o trace atual for amostrado para inclusão, `false` se for amostrado.

Exemplos

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITraceMetadata traceMetadata = agent.TraceMetadata;
string traceId = traceMetadata.TraceId;
string spanId = traceMetadata.SpanId;
bool isSampled = traceMetadata.IsSampled;

Esta tradução de máquina é fornecida para sua comodidade.

Requisitos.css-21sua1{background:none;border:none;width:0;padding:0;}

Notas sobre Injeção de Dependência

Registre IAgent tardiamente, não antecipadamente

Não armazene ITransaction ou ISpan em cache nos campos

Lista de chamadas de API

Obter Agente

GetBrowserTimingHeader

GetLinkingMetadata

Agente IA

ITransação

ISpan

IgnoreApdex

IgnoreTransaction

IncrementCounter

NoticeError

RecordCustomEvent

RecordMetric

RecordResponseTimeMetric

Requisitos

Registre `IAgent` tardiamente, não antecipadamente

Não armazene `ITransaction` ou `ISpan` em cache nos campos