API del agente .NET

El agente .NET de New Relic incluye una API que le permite ampliar la funcionalidad estándar del agente. Por ejemplo, puede emplear la API del agente .NET para:

Personaliza el nombre de tu aplicación
Crear parámetro de transacción personalizado
Reportar errores personalizados y métricos

También puede personalizar parte del comportamiento predeterminado del agente .NET ajustando la configuración o utilizando instrumentación personalizada.

Requisitos

Para emplear la API del agente .NET, cerciorar de tener la última versión del agente .NET. Luego, agregue una referencia al agente en su proyecto usando una de las dos opciones siguientes:

Añade una referencia a NewRelic.Api.Agent.dll a tu proyecto.
O
Vea y descargue el paquete API desde la biblioteca de paquetes NuGet.

Lista de llamadas de API

La siguiente lista contiene las diferentes llamadas que puede realizar con la API, incluida la sintaxis, los requisitos, la funcionalidad y los ejemplos:

Sintaxis

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

Deshabilite la inyección automática de monitoreo de fragmentos del navegador en páginas específicas.

Requisitos

Compatible con todas las versiones de agente.
Debe llamarse dentro de una transacción.

Descripción

Agregue esta llamada para deshabilitar la inyección automática del script en páginas específicas. También puede agregar una anulación opcional para desactivar la inyección manual y automática. En cualquier caso, coloque esta API de llamada lo más cerca posible de la parte superior de la vista en la que desea desactivar browser .

Sugerencia

Compare GetBrowserTimingHeader(), que agrega el browser script a la página.

Parámetros

Parámetro	Descripción
`$override` booleano	Opcional. Cuando `true`, desactiva toda inserción de secuencias de comandos browser . Este indicador afecta tanto a la inyección manual como a la automática. Esto también anula la llamada `GetBrowserTimingHeader()` .

Parámetro

Descripción

$override

booleano

Opcional. Cuando true, desactiva toda inserción de secuencias de comandos browser . Este indicador afecta tanto a la inyección manual como a la automática. Esto también anula la llamada GetBrowserTimingHeader() .

Ejemplos

Desactivar la inyección automática

Este ejemplo deshabilita solo la inyección automática del fragmento:

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

Desactivar la inyección automática y manual.

Este ejemplo desactiva la inyección automática y manual del fragmento:

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

Sintaxis

NewRelic.Api.Agent.NewRelic.GetAgent()

Obtenga acceso al agente a través de la interfaz IAgent .

Requisitos

Versión del agente 8.9 o superior.
Compatible con todo tipo de aplicaciones.

Descripción

Obtenga acceso a los métodos API del agente a través de la interfaz IAgent .

Valores de retorno

Una implementación de IAgent que proporciona acceso a la API de IAgent.

Ejemplos

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

Sintaxis

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

Generar un fragmento HTML de monitoreo del navegador para instrumento usuario final del navegador.

Requisitos

Compatible con todas las versiones de agente.
Debe llamarse dentro de una transacción.

Descripción

Devuelve un fragmento de HTML empleado para habilitar . El fragmento indica al browser que busque un pequeño archivo JavaScript e inicie el temporizador de la página. Luego puede insertar el fragmento devuelto en el encabezado de sus sitios web HTML. Para obtener más información, consulte Agregar aplicaciones al monitoreo del browser.

Sugerencia

Compare DisableBrowserMonitoring(), que deshabilita la browser script en una página.

Parámetros

Parámetro	Descripción
`nonce` cadena	El nonce criptográfico por solicitud empleado por las políticas de política de seguridad de contenido.

Parámetro

Descripción

nonce

cadena

El nonce criptográfico por solicitud empleado por las políticas de política de seguridad de contenido.

Sugerencia

Esta llamada API requiere actualizaciones de la lista de seguridad de 'permitidos'. Para obtener más información sobre las consideraciones de la Política de seguridad de contenido (CSP), visite la página de monitoreo de compatibilidad y requisitos del navegador .

Valores de retorno

Una cadena HTML que se incrustará en el encabezado de una página.

Ejemplos

<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 no es compatible con Blazor Webassembly porque el agente no puede interpretar el código de Webassembly. Los siguientes ejemplos son solo para la aplicación Blazor Server. Utilice el método de copiar y pegar para agregar el agente del navegador a las páginas de Blazor Webassembly.

Importante

Esta API no se puede colocar en un elemento <HeadContent> de una página .razor . En su lugar, debería llamarse desde _Layout.cshtml o un archivo de diseño 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>
...

Sintaxis

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

Devuelve pares de valores principales que se pueden utilizar para vincular traza o entidad.

Requisitos

Versión del agente 8.19 o superior.
Compatible con todo tipo de aplicaciones.

Descripción

El diccionario de pares principales de valor devuelto incluye elementos empleados para vincular traza y entidad en el producto APM . Sólo contendrá elementos con valores significativos. Para instancia, si rastreo distribuido está deshabilitado, trace.id no se incluirá.

Valores de retorno

Dictionary <string, string>() La devolución incluye elementos utilizados para vincular traza y entidad en el producto APM.

Ejemplos

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

Sintaxis

public interface IAgent

Proporciona acceso a los artefactos y métodos del agente, como la transacción que se está ejecutando actualmente.

Requisitos

Versión del agente 8.9 o superior.
Compatible con todo tipo de aplicaciones.

Descripción

Proporciona acceso a los artefactos y métodos del agente, como la transacción que se está ejecutando actualmente. Para obtener una referencia a IAgent, emplee GetAgent.

Propiedades

Nombre	Descripción
Transacción actual	Propiedad que proporciona acceso a la transacción que se está ejecutando actualmente a través de la interfaz ITransaction . Debe llamar dentro de una transacción.
Intervalo actual	Propiedad que proporciona acceso al tramo que se está ejecutando actualmente a través de la interfaz ISpan .

Ejemplos

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

Sintaxis

public interface ITransaction

Proporciona acceso a métodos específicos de transacciones en la API New Relic.

Descripción

Proporciona acceso a métodos específicos de transacciones en la New Relic .NET API del agente . Para obtener una referencia a ITransaction, emplee el método de transacción actual disponible en IAgent.

Los siguientes métodos están disponibles en ITransaction:

Nombre	Descripción
`AcceptDistributedTraceHeaders`	Acepta encabezados de contexto de traza entrantes de otro servicio.
`InsertDistributedTraceHeaders`	Agrega encabezados de contexto de traza a una solicitud saliente.
`AcceptDistributedTracePayload` (obsoleto)	Acepta una carga útil entrante de rastreo distribuido de otro servicio.
`CreateDistributedTracePayload` (obsoleto)	Crea una carga útil de rastreo distribuido para incluirla en una solicitud saliente.
`AddCustomAttribute`	Agregue información contextual de su aplicación a la transacción actual en forma de atributo.
`CurrentSpan`	Proporciona acceso al intervalo que se está ejecutando actualmente, que proporciona acceso a métodos específicos del intervalo en la API New Relic.
`SetUserId`	Asocia una ID de usuario a la transacción actual.

Sintaxis

void AcceptDistributedTraceHeaders(carrier, getter, transportType)

Instrumentar el servicio llamado para su inclusión en un rastreo distribuido.

Descripción

ITransaction.AcceptDistributedTraceHeaders se emplea para vincular los tramos en una traza aceptando una carga generada por InsertDistributedTraceHeaders o generada por algún otro rastreador compatible con W3C Trace Context . Este método acepta los encabezados de una solicitud entrante, busca los encabezados W3C Trace Context y, si no los encuentra, recurre a los encabezados distribuidos del rastreo New Relic . Este método reemplaza el método obsoleto AcceptDistributedTracePayload , que solo maneja la carga distribuida de rastreo New Relic .

Parámetros

Nombre	Descripción
`carrier` <T>	Requerido. Fuente de encabezados entrantes de contexto de traza.
`getter` Func<T, string, IEnumerable<string>>	Requerido. Función definida por la persona que llama para extraer datos del encabezado del operador.
`transportType` Enumeración tipo de transporte	Requerido. Describe el transporte de la carga útil entrante (por ejemplo `TransportType.HTTP`).

Nombre

Descripción

carrier

<T>

Requerido. Fuente de encabezados entrantes de contexto de traza.

getter

Func<T, string, IEnumerable<string>>

Requerido. Función definida por la persona que llama para extraer datos del encabezado del operador.

transportType

Enumeración tipo de transporte

Requerido. Describe el transporte de la carga útil entrante (por ejemplo TransportType.HTTP).

Consideraciones de uso

Rastreo distribuido debe estar habilitado.
AcceptDistributedTraceHeaders se ignorará si ya se ha llamado InsertDistributedTraceHeaders o AcceptDistributedTraceHeaders para esta transacción.

Ejemplo

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

Sintaxis

void InsertDistributedTraceHeaders(carrier, setter)

Implementar rastreo distribuido.

Descripción

ITransaction.InsertDistributedTraceHeaders modifica el objeto portador que se pasa agregando encabezados W3C Trace Context y encabezados distribuidos de rastreo New Relic . Los encabezados de New Relic se pueden desactivar con <distributedTracing excludeNewrelicHeader="true" /> en la configuración. Este método reemplaza el método obsoleto CreateDistributedTracePayload , que solo crea carga distribuida de rastreo New Relic .

Parámetros

Nombre	Descripción
`carrier` <T>	Requerido. contenedor donde se insertan los encabezados de contexto de traza.
`setter` Action<T, string, string>	Requerido. Acción definida por la persona que llama para insertar datos de encabezado en el operador.

Nombre

Descripción

carrier

<T>

Requerido. contenedor donde se insertan los encabezados de contexto de traza.

setter

Action<T, string, string>

Requerido. Acción definida por la persona que llama para insertar datos de encabezado en el operador.

Consideraciones de uso

Rastreo distribuido debe estar habilitado.

Ejemplo

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

Advertencia

Esta API no está disponible en el agente .NET v9.0 o superior. Emplee AcceptDistributedTraceHeaders en su lugar.

Sintaxis

void AcceptDistributedPayload(payload, transportType)

Acepta una carga útil entrante de rastreo distribuido desde un servicio ascendente. Llamar a este método vincula la transacción del servicio ascendente a esta transacción.

Parámetros

Nombre	Descripción
`payload` cadena	Requerido. Una representación de cadena de la carga útil distribuida del rastreo entrante.
`transportType` Tipo de transporte enumeración	Recomendado. Describe el transporte de la carga útil entrante (por ejemplo, `http`). Predeterminado `TransportType.Unknown`.

Nombre

Descripción

payload

cadena

Requerido. Una representación de cadena de la carga útil distribuida del rastreo entrante.

transportType

Tipo de transporte
enumeración

Recomendado. Describe el transporte de la carga útil entrante (por ejemplo, http).

Predeterminado TransportType.Unknown.

Consideraciones de uso

Rastreo distribuido debe estar habilitado.
La carga útil puede ser una cadena de texto sin formato o codificada en Base64.
AcceptDistributedTracePayload se ignorará si ya se ha llamado CreateDistributedTracePayload para esta transacción.

Ejemplo

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

Advertencia

Esta API no está disponible en el agente .NET v9.0 o superior. Emplee InsertDistributedTraceHeaders en su lugar.

Sintaxis

IDistributedTracePayload CreateDistributedTracePayload()

Crea una carga útil de rastreo distribuido para incluirla en una solicitud saliente a un sistema descendente.

Devoluciones

Un objeto que implementa IDistributedTracePayload que proporciona acceso a la carga útil de rastreo distribuido que se creó.

Consideraciones de uso

Rastreo distribuido debe estar habilitado.
CreateDistributedTracePayload se ignorará si ya se ha llamado AcceptDistributedTracePayload para esta transacción.

Ejemplo

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

Sintaxis

ITransaction AddCustomAttribute(string key, object value)

Agrega información contextual sobre su aplicación a la transacción actual en forma de atributo.

Este método requiere la versión del agente .NET y la versión de API del agente .NET 8.24.244.0 o superior. Reemplazó al AddCustomParameter obsoleto.

Parámetros

Parámetro	Descripción
`key` cadena	Identifica la información que se reporta. También conocido como el nombre. No se admiten claves vacías. Las claves están limitadas a 255 bytes. Se ignorarán los atributos con claves mayores a 255 bytes.
`value` objeto	El valor que se informa. Nota: `null` valores no se registrarán.

Parámetro

Descripción

key

cadena

Identifica la información que se reporta. También conocido como el nombre.

No se admiten claves vacías.
Las claves están limitadas a 255 bytes. Se ignorarán los atributos con claves mayores a 255 bytes.

value

objeto

El valor que se informa.

Nota: null valores no se registrarán.

Tipo .NET	Cómo se representará el valor
`byte`, `Int16`, `Int32`, `Int64` `sbyte`, `UInt16`, `UInt32`, `UInt64`	Como valor integral.
`float`, `double`, `decimal`	Un número basado en decimales.
`string`	Una cadena truncada después de 255 bytes. Se admiten cadenas vacías.
`bool`	Verdadero o falso.
`DateTime`	Una representación de cadena que sigue el formato ISO-8601, incluida información de zona horaria: Ejemplo: `2020-02-13T11:31:19.5767650-08:00`
`TimeSpan`	Un número decimal que representa el número de segundos.
todo lo demas	Se aplicará el método `ToString()` . Los tipos personalizados deben tener una implementación de `Object.ToString()` o generarán una excepción.

Devoluciones

Una referencia a la transacción actual.

Consideraciones de uso

Para obtener detalles sobre los tipos de datos admitidos, consulte atributo personalizado.

Ejemplo

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

Proporciona acceso al span que se está ejecutando actualmente, lo que hace que los métodos específicos del span estén disponibles dentro de la API de New Relic.

Ejemplo

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

Sintaxis

ITransaction SetUserId(string userId)

Asocia una ID de usuario con la transacción actual.

Este método requiere el agente .NET y la API del agente .NET versión 10.9.0 o superior.

Parámetros

Parámetro	Descripción
`userId` cadena	El ID de usuario que se asociará con esta transacción. `null`, los valores vacíos y de espacios en blanco se ignorarán.

Parámetro

Descripción

userId

cadena

El ID de usuario que se asociará con esta transacción.

null, los valores vacíos y de espacios en blanco se ignorarán.

Ejemplo

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

Sintaxis

Public interface ISpan

Proporciona acceso a métodos específicos de tramo en la API New Relic.

Descripción

Proporciona acceso a métodos específicos de tramo en la API del agente New Relic .NET. Para obtener una referencia a ISpan, utilice:

La propiedad CurrentSpan en IAgent (recomendado).
La propiedad CurrentSpan en ITransaction.

Esta sección contiene descripciones y parámetros de ISpan métodos:

Nombre	Descripción
`AddCustomAttribute`	Agregue información contextual de su aplicación al intervalo actual en forma de atributo.
`SetName`	Cambia el nombre del tramo/segmento/métrica actual que se informará a New Relic.

Agrega información contextual sobre su aplicación al intervalo actual en forma de atributo.

Este método requiere la versión del agente .NET y la versión API del agente .NET 8.25 o superior.

Sintaxis

ISpan AddCustomAttribute(string key, object value)

Parámetros

Parámetro

Descripción

key

cadena

Identifica la información que se reporta. También conocido como el nombre.

No se admiten claves vacías.
Las claves están limitadas a 255 bytes. Se ignorarán los atributos con claves mayores a 255 bytes.

value

objeto

El valor que se informa.

Nota: null valores no se registrarán.

Tipo .NET	Cómo se representará el valor
`byte`, `Int16`, `Int32`, `Int64` `sbyte`, `UInt16`, `UInt32`, `UInt64`	Como valor integral.
`float`, `double`, `decimal`	Un número basado en decimales.
`string`	Una cadena truncada después de 255 bytes. Se admiten cadenas vacías.
`bool`	Verdadero o falso.
`DateTime`	Una representación de cadena que sigue el formato ISO-8601, incluida información de zona horaria: Ejemplo: `2020-02-13T11:31:19.5767650-08:00`
`TimeSpan`	Un número decimal que representa el número de segundos.
todo lo demas	Se aplicará el método `ToString()` . Los tipos personalizados deben tener una implementación de `Object.ToString()` o generarán una excepción.

Devoluciones

Una referencia al lapso actual.

Consideraciones de uso

Para obtener detalles sobre los tipos de datos admitidos, consulte la guía de atributos personalizados.

Ejemplos

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

Cambia el nombre del segmento/tramo actual que se informará a New Relic. Para segmentos/tramos resultantes de instrumentación personalizada, el nombre de la métrica reportada a New Relic también se modificará.

Este método requiere la versión del agente .NET y la versión 10.1.0 de la API del agente .NET o mas alto.

Sintaxis

ISpan SetName(string name)

Parámetros

Parámetro	Descripción
`name` cadena	El nuevo nombre del tramo/segmento.

Parámetro

Descripción

name

cadena

El nuevo nombre del tramo/segmento.

Devoluciones

Una referencia al lapso actual.

Ejemplos

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

    currentSpan.SetName("MyCustomName");
}

Sintaxis

NewRelic.Api.Agent.NewRelic.IgnoreApdex()

Ignore la transacción actual al calcular Apdex.

Requisitos

Compatible con todas las versiones de agente.

Descripción

Ignora la transacción actual al calcular su puntuación Apdex. Esto es útil cuando tiene transacciones muy cortas o muy largas (como descargas de archivos) que pueden sesgar su puntuación Apdex.

Ejemplos

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

Sintaxis

NewRelic.Api.Agent.NewRelic.IgnoreTransaction()

No instrumente la transacción actual.

Requisitos

Compatible con todas las versiones de agente.
Debe llamarse dentro de una transacción.

Descripción

Ignora la transacción actual.

Sugerencia

También puede ignorar la transacción a través de un archivo XML de instrumentación personalizada.

Ejemplos

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

Sintaxis

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

Incrementa el contador de una métrica personalizada en 1.

Requisitos

Compatible con todas las versiones de agente.
Compatible con todo tipo de aplicaciones.

Descripción

Incrementa el contador de una métrica personalizada en 1. Para ver estas métricas personalizadas, emplee el generador de consultas para buscar métricas y crear gráficos personalizables. Consulte también RecordMetric() y RecordResponseTimeMetric().

Importante

Al crear una métrica personalizada, comience el nombre con Custom/ (por ejemplo, Custom/MyMetric). Para obtener más información sobre la denominación, consulte Recopilar métrica personalizada.

Parámetros

Parámetro	Descripción
`$metric_name` cadena	Requerido. El nombre de la métrica que se va a incrementar.

Parámetro

Descripción

$metric_name

cadena

Requerido. El nombre de la métrica que se va a incrementar.

Ejemplos

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

Sobrecargas

Observe un error e informe a New Relic, junto con el 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 llamada API es compatible con:

Todas las versiones del agente
Todos los tipos de aplicaciones

Descripción

Observe un error e infórmelo a New Relic junto con el atributo personalizado opcional. Para cada transacción, el agente solo conserva la excepción y el atributo de la primera llamada a NoticeError(). Puede pasar una excepción real o pasar una cadena para capturar un mensaje de error arbitrario.

Si este método se invoca dentro de una transacción, el agente informa la excepción dentro de la transacción principal. Si se invoca fuera de una transacción, el agente crea una traza de error y categoriza el error en la New Relic UI como una de NewRelic.Api.Agent.NoticeError llamada API. Si se invoca fuera de una transacción, la llamada NoticeError() no contribuirá a la tasa de errores de una aplicación.

El agente agrega el atributo sólo al error de traza; no los envía a New Relic. Para obtener más información, consulte AddCustomAttribute().

Los errores informados con esta API aún se envían a New Relic cuando se informan dentro de una transacción que genera un código de estado HTTP, como 404, que está configurado para ser ignorado por la configuración del agente. Para obtener más información, consulte nuestra documentación sobre la gestión de errores en APM.

Revise las secciones siguientes para ver ejemplos de cómo utilizar esta llamada.

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

Parámetro	Descripción
`$exception` Excepción	Requerido. El `Exception` que quieres instrumento. Sólo se conservan los primeros 10.000 caracteres del rastreo del stack.

Parámetro

Descripción

$exception

Excepción

Requerido. El Exception que quieres instrumento. Sólo se conservan los primeros 10.000 caracteres del rastreo del stack.

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

Parámetro	Descripción
`$exception` Excepción	Requerido. El `Exception` que quieres instrumento. Sólo se conservan los primeros 10.000 caracteres del rastreo del stack.
`$attributes` IDictionary<TKey, TValue>	Especifique los pares principales de valor del atributo para anotar el mensaje de error. El `TKey` debe ser una cadena, el `TValue` puede ser una cadena u un objeto.

Parámetro

Descripción

$exception

Excepción

Requerido. El Exception que quieres instrumento. Sólo se conservan los primeros 10.000 caracteres del rastreo del stack.

$attributes

IDictionary<TKey, TValue>

Especifique los pares principales de valor del atributo para anotar el mensaje de error. El TKey debe ser una cadena, el TValue puede ser una cadena u un objeto.

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

Parámetro	Descripción
`$error_message` cadena	Requerido. Especifique una cadena para informar a New Relic como si fuera una excepción. Este método crea tanto error evento como error traza. En error evento solo se retienen los primeros 1023 caracteres, mientras que error traza retiene el mensaje completo.
`$attributes` IDictionary<TKey, TValue>	Requerido (puede ser nulo). Especifique los pares principales de valor del atributo para anotar el mensaje de error. El `TKey` debe ser una cadena, el `TValue` puede ser una cadena u objeto, para enviar ningún atributo pasa `null`.

Parámetro

Descripción

$error_message

cadena

Requerido. Especifique una cadena para informar a New Relic como si fuera una excepción. Este método crea tanto error evento como error traza. En error evento solo se retienen los primeros 1023 caracteres, mientras que error traza retiene el mensaje completo.

$attributes

IDictionary<TKey, TValue>

Requerido (puede ser nulo). Especifique los pares principales de valor del atributo para anotar el mensaje de error. El TKey debe ser una cadena, el TValue puede ser una cadena u objeto, para enviar ningún atributo pasa null.

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

Parámetro	Descripción
`$error_message` cadena	Requerido. Especifique una cadena para informar a New Relic como si fuera una excepción. Este método crea tanto error evento como error traza. En error evento solo se retienen los primeros 1023 caracteres, mientras que error traza retiene el mensaje completo.
`$attributes` IDictionary<TKey, TValue>	Requerido (puede ser nulo). Especifique los pares principales de valor del atributo para anotar el mensaje de error. El `TKey` debe ser una cadena, el `TValue` puede ser una cadena u objeto, para enviar ningún atributo pasa `null`.
`$is_expected` bool	Marque el error como se esperaba para que no afecte la puntuación Apdex ni la tasa de errores.

Parámetro

Descripción

$error_message

cadena

$attributes

IDictionary<TKey, TValue>

$is_expected

bool

Marque el error como se esperaba para que no afecte la puntuación Apdex ni la tasa de errores.

Ejemplos

Pasar una excepción sin atributo personalizado

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

Pasar una excepción con 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);
}

Pasar una cadena de mensaje de error con 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);
}

Pasar una cadena de mensaje de error sin atributo personalizado

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

Pase una cadena de mensaje de error y márquela como se esperaba

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

Sintaxis

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

Graba un evento personalizado con el nombre de pila y atributo.

Requisitos

Compatible con todas las versiones de agente.
Compatible con todo tipo de aplicaciones.

Descripción

Registra un evento personalizado con el nombre de pila y atributo, que puedes consultar en el generador de consultas. Para verificar si un evento se está registrando correctamente, busque los datos en el tablero.

Importante

Enviar muchos eventos puede aumentar la sobrecarga de memoria del agente.
Además, las publicaciones con un tamaño superior a 1 MB (10^6 bytes) no se registrarán independientemente del número máximo de eventos.
evento personalizado están limitados a 64 atributos.
Para obtener más información sobre cómo se procesan los valores de atributo personalizado, consulte la guía de atributo personalizado .

Parámetros

Parámetro	Descripción
`eventType` cadena	Requerido. El nombre del tipo de evento a registrar. Las cadenas de más de 255 caracteres darán como resultado que la llamada API no se envíe a New Relic. El nombre solo puede contener caracteres alfanuméricos, guiones bajos `_` y dos puntos `:`. Para conocer restricciones adicionales sobre nombres de tipos de eventos, consulte Palabras reservadas.
`attributeValues` IEnumerable<string, object>	Requerido. Especifique el valor principal de los pares de atributos para anotar el evento.

Parámetro

Descripción

eventType

cadena

Requerido. El nombre del tipo de evento a registrar. Las cadenas de más de 255 caracteres darán como resultado que la llamada API no se envíe a New Relic. El nombre solo puede contener caracteres alfanuméricos, guiones bajos _ y dos puntos :. Para conocer restricciones adicionales sobre nombres de tipos de eventos, consulte Palabras reservadas.

attributeValues

IEnumerable<string, object>

Requerido. Especifique el valor principal de los pares de atributos para anotar el evento.

Ejemplos

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

Sintaxis

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

Registra una métrica personalizada con el nombre de pila.

Requisitos

Compatible con todas las versiones de agente.
Compatible con todo tipo de aplicaciones.

Descripción

Registra una métrica personalizada con el nombre de pila. Para ver estas métricas personalizadas, emplee el generador de consultas para buscar métricas y crear gráficos personalizables. Consulte también IncrementCounter() y RecordResponseTimeMetric().

Importante

Al crear una métrica personalizada, comience el nombre con Custom/ (por ejemplo, Custom/MyMetric).

Parámetros

Parámetro	Descripción
`$metric_name` cadena	Requerido. El nombre de la métrica a registrar. Sólo se conservan los primeros 255 caracteres.
`$metric_value` soltero	Requerido. La cantidad que se registrará para la métrica.

Parámetro

Descripción

$metric_name

cadena

Requerido. El nombre de la métrica a registrar. Sólo se conservan los primeros 255 caracteres.

$metric_value

soltero

Requerido. La cantidad que se registrará para la métrica.

Ejemplos

Registrar el tiempo de respuesta de un proceso de sueño. [#record-stopwatch]

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

Sintaxis

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

Registra una métrica personalizada con el nombre de pila y el tiempo de respuesta en milisegundos.

Requisitos

Compatible con todas las versiones de agente.
Compatible con todo tipo de aplicaciones.

Descripción

Registra el tiempo de respuesta en milisegundos para una métrica personalizada. Para ver estas métricas personalizadas, emplee el generador de consultas para buscar métricas y crear gráficos personalizables. Consulte también IncrementCounter() y RecordMetric().

Importante

Al crear una métrica personalizada, comience el nombre con Custom/ (por ejemplo, Custom/MyMetric).

Parámetros

Parámetro	Descripción
`$metric_name` cadena	Requerido. El nombre de la métrica de tiempo de respuesta que se va a registrar. Sólo se conservan los primeros 255 caracteres.
`$metric_value` Int64	Requerido. El tiempo de respuesta para grabar en milisegundos.

Parámetro

Descripción

$metric_name

cadena

Requerido. El nombre de la métrica de tiempo de respuesta que se va a registrar. Sólo se conservan los primeros 255 caracteres.

$metric_value

Int64

Requerido. El tiempo de respuesta para grabar en milisegundos.

Ejemplos

Registrar el tiempo de respuesta de un proceso de sueño. [#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);

Sintaxis

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

Establezca el nombre de la aplicación para la acumulación de datos.

Requisitos

Compatible con todas las versiones de agente.
Compatible con todo tipo de aplicaciones.

Descripción

Establezca los nombres de las aplicaciones reportadas a New Relic. Para obtener más información sobre la denominación de aplicaciones, consulte Asigne un nombre a su aplicación .NET. Este método está pensado para llamarse una vez, durante el inicio de una aplicación.

Importante

La actualización del nombre de la aplicación obliga al agente a reiniciarse. El agente descarta cualquier dato no informado asociado con nombres de aplicaciones anteriores. No se recomienda cambiar el nombre de la aplicación varias veces durante el ciclo de vida de una aplicación debido a la pérdida de datos asociada.

Parámetros

Parámetro	Descripción
`$name` cadena	Requerido. El nombre de la aplicación principal.
`$name_2` `$name_3` cadena	Opcional. Segundo y tercer nombre para la acumulación de aplicaciones. Para obtener más información, consulte Usar varios nombres para una aplicación.

Parámetro

Descripción

$name

cadena

Requerido. El nombre de la aplicación principal.

$name_2

$name_3

cadena

Opcional. Segundo y tercer nombre para la acumulación de aplicaciones. Para obtener más información, consulte Usar varios nombres para una aplicación.

Ejemplos

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

Sintaxis

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

Proporcione un método de devolución de llamada que tome un IReadOnlyDictionary<string,object> de datos de atributo y devuelva un nombre de grupo de error.

Requisitos

Esta llamada API es compatible con:

Versión del agente 10.9.0 o superior.
Todos los tipos de aplicaciones

Descripción

Establezca un método de devolución de llamada que el agente utilizará para determinar el nombre del grupo de errores para el evento de error y la traza. Este nombre se utiliza en la Errors Inbox para agrupar errores en grupos lógicos.

El método de devolución de llamada debe aceptar un único argumento de tipo IReadOnlyDictionary<string,object> y devolver una cadena (el nombre del grupo de errores). El IReadOnlyDictionary es una colección de datos de atributos asociados con cada evento de error, incluido el atributo personalizado.

La lista exacta de atributos disponibles para cada error variará dependiendo de:

¿Qué código de aplicación generó el error?
Ajustes de configuración del agente
Si se agregó algún atributo personalizado

Sin embargo, siempre debe existir el siguiente atributo:

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

Se puede devolver una cadena vacía para el nombre del grupo de errores cuando el error no se puede asignar a un grupo de errores lógicos.

Parámetros

Parámetro	Descripción
`$callback` 'Func<IReadOnlyDictionary<string,object>,string>'	La devolución de llamada para determinar el nombre del grupo de errores en función de los datos del atributo.

Parámetro

Descripción

$callback

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

La devolución de llamada para determinar el nombre del grupo de errores en función de los datos del atributo.

Ejemplos

Errores de grupo por nombre de clase de error:

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

Errores de grupo por nombre de transacción:

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

Sintaxis

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

Establece el nombre de la transacción actual.

Requisitos

Compatible con todas las versiones de agente.
Debe llamarse dentro de una transacción.

Descripción

Establece el nombre de la transacción actual. Antes de utilizar esta llamada, asegúrese de comprender las implicaciones de los problemas de agrupación métrica.

Si utiliza esta llamada varias veces dentro de la misma transacción, cada llamada sobrescribe la llamada anterior y la última llamada establece el nombre.

Importante

No utilice corchetes [suffix] al final del nombre de su transacción. New Relic elimina automáticamente los corchetes del nombre. En su lugar, utilice paréntesis (suffix) u otros símbolos si es necesario.

Valor único como URL, títulos de páginas, valores hexadecimales, ID de sesión y valores identificables de forma única no deben usar para nombrar su transacción. En su lugar, agregue esos datos a la transacción como un parámetro personalizado con la llamada AddCustomAttribute() .

Importante

No cree más de 1000 nombres de transacciones únicos (por ejemplo, evite nombrar por URL si es posible). Esto hará que sus gráficos sean menos útiles y es posible que se encuentre con los límites que New Relic establece en la cantidad de nombres de transacciones únicos por cuenta. También puede ralentizar el rendimiento de su aplicación.

Parámetros

Parámetro	Descripción
`$category` cadena	Requerido. La categoría de esta transacción, que puede utilizar para distinguir diferentes tipos de transacciones. El valor predeterminado es `Custom`. Sólo se conservan los primeros 255 caracteres.
`$name` cadena	Requerido. El nombre de la transacción. Sólo se conservan los primeros 255 caracteres.

Parámetro

Descripción

$category

cadena

Requerido. La categoría de esta transacción, que puede utilizar para distinguir diferentes tipos de transacciones. El valor predeterminado es Custom. Sólo se conservan los primeros 255 caracteres.

$name

cadena

Requerido. El nombre de la transacción. Sólo se conservan los primeros 255 caracteres.

Ejemplos

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

Sintaxis

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

Establece el URI de la transacción actual.

Requisitos

Debe llamarse dentro de una transacción.
Versión del agente 6.16 o superior.

Importante

Este método solo funciona cuando se usa dentro de una transacción creada usando el atributo Transaction con la propiedad Web establecido en true. (Ver instrumentación personalizada vía atributo.) Proporciona soporte para marcos sitio web personalizados que el agente no admite automáticamente.

Descripción

Establece el URI de la transacción actual. El URI aparece en el atributo request.uri de la traza de la transacción y del evento de transacción, y también puede afectar el nombre de la transacción.

Si utiliza esta llamada varias veces dentro de la misma transacción, cada llamada sobrescribe la llamada anterior. La última llamada establece el URI.

Nota: a partir de la versión 8.18 del agente, el valor del atributo request.uri se establece en el valor de la propiedad Uri.AbsolutePath del objeto System.Uri pasado a la API.

Parámetros

Parámetro	Descripción
`$uri` Uri	El URI de esta transacción.

Parámetro

Descripción

$uri

Uri

El URI de esta transacción.

Ejemplos

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

Sintaxis

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

Crear atributo personalizado relacionado con el usuario. AddCustomAttribute es más flexible.

Requisitos

Compatible con todas las versiones de agente.
Debe llamarse dentro de una transacción.

Descripción

Sugerencia

Esta llamada solo le permite asignar valores a claves preexistentes. Para obtener un método más flexible para crear pares de valores principales, emplee AddCustomAttribute().

Defina un atributo personalizadorelacionado con el usuario para asociarlo con una vista de página browser (nombre del usuario, nombre de cuenta y nombre del producto). Los valores se asocian automáticamente con claves preexistentes (user, account y product) y luego se anexan a la transacción APM principal. También puede anexar (o "reenviar") estos atributos al browser evento PageView .

Parámetros

Parámetro	Descripción
`$user_value` cadena	Requerido (puede ser nulo). Especifique un nombre o nombre de usuario para asociarlo con esta vista de página. Este valor se asigna a la clave `user` .
`$account_value` cadena	Requerido (puede ser nulo). Especifique el nombre de una cuenta de usuario para asociarla con esta vista de página. Este valor se asigna a la clave `account` .
`$product_value` cadena	Requerido (puede ser nulo). Especifique el nombre de un producto para asociarlo con esta vista de página. Este valor se asigna a la clave `product` .

Parámetro

Descripción

$user_value

cadena

Requerido (puede ser nulo). Especifique un nombre o nombre de usuario para asociarlo con esta vista de página. Este valor se asigna a la clave user .

$account_value

cadena

Requerido (puede ser nulo). Especifique el nombre de una cuenta de usuario para asociarla con esta vista de página. Este valor se asigna a la clave account .

$product_value

cadena

Requerido (puede ser nulo). Especifique el nombre de un producto para asociarlo con esta vista de página. Este valor se asigna a la clave product .

Ejemplos

Grabar tres atributos de usuario.

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

Registre dos atributos de usuario y un atributo vacío

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

Sintaxis

NewRelic.Api.Agent.NewRelic.StartAgent()

Inicie el agente si aún no lo ha hecho. Generalmente innecesario.

Requisitos

Compatible con todas las versiones de agente.
Compatible con todo tipo de aplicaciones.

Descripción

Inicia el agente si aún no se inició. Esta llamada suele ser innecesaria, ya que el agente se inicia automáticamente cuando llega a un método instrumentado a menos que deshabilite autoStart. Si usa SetApplicationName(), cerciorar de configurar el nombre de la aplicación antes de iniciar el agente.

Sugerencia

Este método inicia el agente de forma asincrónica (lo que significa que no bloqueará el inicio de la aplicación) a menos que habilite syncStartup o sendDataOnExit.

Ejemplos

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

Sintaxis

NewRelic.Api.Agent.TraceMetadata;

Devuelve propiedades en el entorno de ejecución actual utilizado para admitir el seguimiento.

Requisitos

Versión del agente 8.19 o superior.
Compatible con todo tipo de aplicaciones.
Rastreo distribuido debe estar habilitado para obtener valores significativos.

Descripción

Proporciona acceso a las siguientes propiedades:

Propiedades

Nombre	Descripción
`TraceId`	Devuelve una cadena que representa la traza que se está ejecutando actualmente. Si la traza ID no está disponible, o el rastreo distribuido está deshabilitado, el valor será `string.Empty`.
`SpanId`	Devuelve una cadena que representa el intervalo de ejecución actual. Si el span ID no está disponible o el rastreo distribuido está deshabilitado, el valor será `string.Empty`.
`IsSampled`	Devuelve `true` si se toma una muestra de la traza actual para su inclusión, `false` si se toma una muestra.

Ejemplos

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

Te ofrecemos esta traducción automática para facilitar la lectura.

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

Lista de llamadas de API

ObtenerAgente

GetBrowserTimingHeader

Obtener metadatos de enlace

Agente

ITransacción

España

IgnoreApdex

IgnoreTransaction

IncrementCounter

NoticeError

RecordCustomEvent

RecordMetric

RecordResponseTimeMetric

Requisitos