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.

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
`AcceptDistributedTraceHeaders`	Aceita cabeçalhos de contexto do trace recebidos de outro serviço.
`InsertDistributedTraceHeaders`	Adiciona cabeçalhos de contexto do trace a uma solicitação de saída.
`AcceptDistributedTracePayload` (obsoleto)	Aceita uma carga útil distributed trace de entrada de outro serviço.
`CreateDistributedTracePayload` (obsoleto)	Cria uma carga de distributed trace para inclusão em uma solicitação de saída.
`AddCustomAttribute`	Adicione informações contextuais da sua aplicação à transação atual em forma de atributo.
`CurrentSpan`	Fornece acesso ao span em execução atualmente, que fornece acesso a métodos específicos de span na API New Relic.
`SetUserId`	Associa um ID de usuário à transação atual.

Sintaxe

void AcceptDistributedTraceHeaders(carrier, getter, transportType)

Instrumentar o chamado serviço para inclusão em um distributed trace.

Descrição

ITransaction.AcceptDistributedTraceHeaders é usado para vincular os períodos 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 os cabeçalhos de uma solicitação recebida, procura W3C Trace Context cabeçalhos e, se não for encontrado, recorre aos New Relic distributed trace cabeçalhos . Este método substitui o método obsoleto, que lida apenas AcceptDistributedTracePayload com New Relic distributed trace carga .

Parâmetro

Nome	Descrição
`carrier` <T>	Obrigatório. Fonte do contexto de entrada dos cabeçalhos de rastreamento.
`getter` Func<T, string, IEnumerable<string>>	Obrigatório. Função definida pelo chamador para extrair dados de cabeçalho da operadora.
`transportType` Enumeração TransportType	Obrigatório. Descreve o transporte da carga de entrada (por exemplo `TransportType.HTTP`).

Nome

Descrição

carrier

<T>

Obrigatório. Fonte do contexto de entrada dos cabeçalhos de rastreamento.

getter

Func<T, string, IEnumerable<string>>

Obrigatório. Função definida pelo chamador para extrair dados de cabeçalho da operadora.

transportType

Enumeração TransportType

Obrigatório. Descreve o transporte da carga de entrada (por exemplo TransportType.HTTP).

Considerações de uso

Distributed tracing deve estar ativado.
AcceptDistributedTraceHeaders será ignorado se InsertDistributedTraceHeaders ou AcceptDistributedTraceHeaders já tiver sido chamado para esta transação.

Exemplo

HttpContext httpContext = HttpContext.Current;
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;
currentTransaction.AcceptDistributedTraceHeaders(httpContext, Getter, TransportType.HTTP);
IEnumerable<string> Getter(HttpContext carrier, string key) 
{ 
    string value = carrier.Request.Headers[key];   
    return value == null ? null : new string[] { value }; 
}

Sintaxe

void InsertDistributedTraceHeaders(carrier, setter)

Implementar distributed tracing.

Descrição

ITransaction.InsertDistributedTraceHeaders modifica o objeto transportador que é transmitido adicionando W3C Trace Context cabeçalhos e New Relic distributed trace cabeçalhos . Os cabeçalhos New Relic podem ser desativados com <distributedTracing excludeNewrelicHeader="true" /> na configuração. Este método substitui o método obsoleto, que cria CreateDistributedTracePayload apenas New Relic distributed trace carga .

Parâmetro

Nome	Descrição
`carrier` <T>	Obrigatório. contêiner onde são inseridos os cabeçalhos do contexto do trace .
`setter` Action<T, string, string>	Obrigatório. Ação definida pelo chamador para inserir dados de cabeçalho na operadora.

Nome

Descrição

carrier

<T>

Obrigatório. contêiner onde são inseridos os cabeçalhos do contexto do trace .

setter

Action<T, string, string>

Obrigatório. Ação definida pelo chamador para inserir dados de cabeçalho na operadora.

Considerações de uso

Distributed tracing deve estar ativado.

Exemplo

HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");
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);

Cuidado

Esta API não está disponível no agente .NET v9.0 ou superior. Use AcceptDistributedTraceHeaders em vez disso.

Sintaxe

void AcceptDistributedPayload(payload, transportType)

Aceita uma carga útil distributed trace de entrada de um serviço upstream. Chamar esse método vincula a transação do serviço upstream a essa transação.

Parâmetro

Nome	Descrição
`payload` corda	Obrigatório. Uma representação de cadeia de caracteres da carga útil distributed trace de entrada.
`transportType` Tipo de transporte enumeração	Recomendado. Descreve o transporte da carga de entrada (por exemplo, `http`). Padrão `TransportType.Unknown`.

Nome

Descrição

payload

corda

Obrigatório. Uma representação de cadeia de caracteres da carga útil distributed trace de entrada.

transportType

Tipo de transporte
enumeração

Recomendado. Descreve o transporte da carga de entrada (por exemplo, http).

Padrão TransportType.Unknown.

Considerações de uso

Distributed tracing deve estar ativado.
A carga útil pode ser uma string de texto simples ou codificada em Base64.
AcceptDistributedTracePayload será ignorado se CreateDistributedTracePayload já tiver sido chamado para esta transação.

Exemplo

//Obtain the information from the request object from the upstream caller.
//The method by which this information is obtain is specific to the transport 
//type being used. For example, in an HttpRequest, this information is
//contained in the 
header.KeyValuePair<string, string> metadata = GetMetaDataFromRequest("requestPayload");
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); 
ITransaction transaction = agent.CurrentTransaction; 
transaction.AcceptDistributedTracePayload(metadata.Value, TransportType.Queue);

Cuidado

Esta API não está disponível no agente .NET v9.0 ou superior. Use InsertDistributedTraceHeaders em vez disso.

Sintaxe

IDistributedTracePayload CreateDistributedTracePayload()

Cria uma carga distributed trace para inclusão em uma solicitação de saída para um sistema downstream.

Devoluções

Um objeto que implementa IDistributedTracePayload que fornece acesso à carga distributed trace que foi criada.

Considerações de uso

Distributed tracing deve estar ativado.
CreateDistributedTracePayload será ignorado se AcceptDistributedTracePayload já tiver sido chamado para esta transação.

Exemplo

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

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

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

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 da sua aplicação ao período atual em forma de atributo.
`SetName`	Altera o nome do intervalo/segmento/métrica atual que será relatado ao New Relic.

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

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().

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

Define o nome da transação atual. Antes de usar esta chamada, certifique-se de compreender 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

NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", "MyTransaction");

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

Define 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;}

Lista de chamadas de API

Obter Agente

GetBrowserTimingHeader

GetLinkingMetadata

Agente IA

ITransação

ISpan

IgnoreApdex

IgnoreTransaction

IncrementCounter

NoticeError

RecordCustomEvent

RecordMetric

RecordResponseTimeMetric

Requisitos