API del agente Node.js

newrelic.setTransactionName(name)

Asigne un nombre a la solicitud actual, siguiendo los requisitos de nomenclatura de la solicitud. Puede llamar a esta función en cualquier lugar dentro del contexto de un controlador de solicitudes HTTP, en cualquier momento después de que haya comenzado el manejo de la solicitud, pero antes de que haya finalizado. En general, si los objetos de solicitud y respuesta están dentro del alcance, puede establecer el nombre.

Llamar explícitamente newrelic.setTransactionName() anulará cualquier nombre establecido por las rutas Express o Restify. Además, las llamadas a newrelic.setTransactionName() y newrelic.setControllerName() se sobrescribirán entre sí. El último en ejecutarse antes de que finalice la solicitud gana.

newrelic.setControllerName(name, [action])

Asigne un nombre a la solicitud actual utilizando un patrón de estilo de controlador, incluyendo opcionalmente la acción del controlador actual. Si se omite la acción, New Relic incluirá el método HTTP (GET, POST, etc.) como acción. Las reglas sobre cuándo puede llamar newrelic.setControllerName() son las mismas que para newrelic.setTransactionName(), incluidos los requisitos de denominación de la solicitud.

Llamar explícitamente newrelic.setControllerName() anulará cualquier nombre establecido por las rutas Express o Restify. Además, las llamadas a newrelic.setTransactionName() y newrelic.setControllerName() se sobrescribirán entre sí. El último en ejecutarse antes de que finalice la solicitud gana.

newrelic.instrument(moduleName, onRequire [, onError])

Establece una devolución de llamada de instrumentación para un módulo específico.

La devolución de llamada onRequire proporcionada se activará cuando el módulo dado se cargue con require. El parámetro moduleName debe ser la cadena que se pasará a require; por ejemplo, 'express' o 'amqplib/callback_api'. La devolución de llamada opcional onError se llama si el parámetro onRequire arroja un error. Esto es útil para depurar su instrumentación.

Utilice este método para:

• Agregue instrumentación para módulos que New Relic no instrumenta actualmente.
• Instrumenta tu propio código.
• Reemplace la instrumentación integrada del agente Node.js por la suya propia.

Para obtener más información, consulte el tutorial de instrumentación Node.js de New Relic en Github.

newrelic.instrumentDatastore(moduleName, onRequire [, onError])

Establece una devolución de llamada de instrumentación para un módulo de almacenamiento de datos.

Este método es similar a newrelic.instrument(), excepto que proporciona un ajuste especializado en almacenamiento de datos. Para obtener más información, consulte el tutorial de instrumentación de almacenamiento de datos Node.js de New Relic en Github.

newrelic.instrumentLoadedModule(moduleName, moduleInstance)

El método instrumentLoadedModule le permite agregar instrumentación estándar a módulos específicos en situaciones en las que es imposible tener require('newrelic'); como la primera línea del módulo principal de su aplicación.

// load the agent
const newrelic = require('newrelic');

// module loaded before newrelic
const expressModule = require('express');

// instrument express after the agent has been loaded
newrelic.instrumentLoadedModule(
  'express',    // the module's name, as a string
  expressModule // the module instance
);

newrelic.instrumentMessages(moduleName, onRequire [, onError])

Establece una devolución de llamada de instrumentación para un módulo cliente de servicio de mensajes.

Este método es similar a newrelic.instrument(), excepto que proporciona una corrección especializada en el servicio de mensajes. Para obtener más información, consulte el tutorial de instrumentación del servicio de mensajes Node.js de New Relic en Github.

newrelic.instrumentWebframework(moduleName, onRequire [, onError])

Establece una devolución de llamada de instrumentación para un módulo framework web.

Este método es similar a newrelic.instrument(), excepto que proporciona una corrección especializada en elframeworkweb. Para obtener más información, consulte el tutorial de instrumentación framework web Node.js de New Relic en Github.

newrelic.startWebTransaction(url, handle)

Instrumento la transacción web especificada. Con esta llamada API, puede realizar transacciones con instrumentos que New Relic no detecta automáticamente.

• El url define el nombre de la transacción y debe ser estático. No incluya datos variables como el ID de usuario.
• El handle define la función que deseas instrumento.

New Relic capturará cualquier métrica que se capturaría mediante la instrumentación automática, así como la instrumentación manual a través de startSegment().

Usted must maneja transacciones personalizadas manualmente llamando newrelic.getTransaction() al comienzo de su transacción y luego llamando a transaction.end() cuando haya terminado. New Relic comienza a cronometrar la transacción cuando se llama a newrelic.startWebTransaction() y finaliza la transacción cuando se llama transaction.end() .

También puede devolver una promesa para indicar el final de la transacción. Tenga en cuenta que si esta promesa se rechaza, no se vincula automáticamente al rastreo de errores de New Relic. Esto debe hacerse manualmente con noticeError().

newrelic.startBackgroundTransaction(name, [group], handle)

Instrumento la transacción en segundo plano especificada. Con esta llamada API, puede ampliar la instrumentación de New Relic para capturar datos de transacciones en segundo plano.

• El name define el nombre de la transacción y debe ser estático. No incluya datos variables como el ID de usuario.

• El group es opcional y le permite agrupar trabajos similares a través del

  transaction type

  en la interfaz de usuario. Al igual que name, el group debe ser estático.

• El handle define una función que incluye todo el trabajo en segundo plano que deseas instrumentar.

New Relic capturará cualquier métrica que se capturaría mediante la instrumentación automática, así como la instrumentación manual a través de startSegment().

Usted must maneja transacciones personalizadas manualmente llamando newrelic.getTransaction() al comienzo de su transacción y luego llamando a transaction.end() cuando haya terminado. New Relic comienza a cronometrar la transacción cuando se llama a newrelic.startBackgroundTransaction() y finaliza la transacción cuando se llama transaction.end() .

También puede devolver una promesa para indicar el final de la transacción. Tenga en cuenta que si esta promesa se rechaza, no se vincula automáticamente al rastreo de errores de New Relic. Esto debe hacerse manualmente con noticeError().

newrelic.getTransaction()

Devuelve un identificador de la transacción que se está ejecutando actualmente. Este identificador se puede utilizar para interactuar con una transacción determinada de forma segura desde cualquier contexto. Se utiliza mejor con newrelic.startWebTransaction() y newrelic.startBackgroundTransaction().

Consulte la sección de manejo de transacciones para obtener más detalles.

newrelic.endTransaction()

Finalice la transacción personalizada web o en segundo plano actual. Este método requiere estar en el contexto de transacción correcto cuando se llama. Esta llamada API no acepta argumentos.

newrelic.startSegment(name, record, handler, callback)

Instrumento: método particular para mejorar la visibilidad de una transacción u, opcionalmente, convertirla en una métrica.

• El name define un nombre para el segmento. Este nombre será visible en la traza de la transacción y como una nueva métrica en la UI de New Relic.
• La marca record define si el segmento debe registrarse como una métrica.
• El handler es la función que desea rastrear como segmento.
• El callback opcional es una función que se pasa al controlador para que la active una vez finalizado su trabajo.

El agente comienza a cronometrar el segmento cuando se llama a startSegment . El segmento finaliza cuando handler termina de ejecutarse o cuando se activa callback , si se proporciona.

newrelic.recordMetric(name, value)

Utilice recordMetric para registrar una métrica basada en eventos, generalmente asociada con una duración particular. El name debe ser una cadena que siga las reglas de nomenclatura métrica estándar. El value normalmente será un número, pero también puede ser un objeto.

• Cuando value es un valor numérico, debe representar la magnitud de una medición asociada con un evento; por ejemplo, la duración de una llamada a un método particular.
• Cuando value es un objeto, debe contener claves count, total, min, max y sumOfSquares , todas con valores numéricos. Este formulario es útil para métrica agregada por su cuenta y reportarlas periódicamente; por ejemplo, de un setInterval. Estos valores se agregarán con cualquier valor recopilado previamente para la misma métrica. Los nombres de estas claves coinciden con los nombres de las claves utilizadas por la API de la plataforma.

newrelic.incrementMetric(name, [amount])

Utilice incrementMetric para actualizar una métrica que actúa como un contador simple. El recuento de la métrica seleccionada se incrementará en la cantidad especificada, por defecto en 1.

newrelic.recordCustomEvent(eventType, attributes)

Utilice recordCustomEvent para registrar una métrica basada en eventos, generalmente asociada con una duración particular.

• El eventType debe ser una cadena alfanumérica de menos de 255 caracteres.
• El attributes debe ser un objeto de pares clave y valor. Las claves deben tener menos de 255 caracteres y los valores deben ser cadenas, números o booleanos.

const attributes = {
  attribute1: 'value1',
  attribute2: 2
};

newrelic.recordCustomEvent('MessagingEvent', attributes);

newrelic.recordLogEvent({message, level})

Utilice recordLogEvent para registrar un registro de eventos, en caso de que la instrumentación de registro automático sea insuficiente para su framework de registro. Consulte la documentación generada automáticamente para conocer los detalles de los tipos de parámetros aceptados.

const error = new SystemError('invalid state');
const timestamp = Date.now();

newrelic.recordLogEvent({message: 'an error happened', level: 'error', timestamp, error});

transactionHandle.end([callback])

Utilice transactionHandle.end para finalizar la transacción a la que hace referencia la instancia de identificador.

El callback se invoca cuando la transacción ha finalizado por completo. La transacción finalizada pasó a la devolución de llamada como primer argumento.

transactionHandle.ignore()

Utilice transactionHandle.ignore para ignorar la transacción a la que hace referencia la instancia del identificador.

transactionHandle.insertDistributedTraceHeaders(headers)

Para obtener contexto sobre cómo utilizar esta llamada y su llamada asociada acceptDistributedTraceHeaders, primero lea Habilitar rastreo distribuido con API de agente.

transactionHandle.insertDistributedTraceHeaders Se utiliza para implementar rastreo distribuido. Modifica el mapa headers que se pasa agregando encabezados W3C Trace Context y encabezados distribuidos de rastreo New Relic. Los encabezados de New Relic se pueden desactivar con distributed_tracing.exclude_newrelic_header: true en la configuración. Este método reemplaza el método obsoleto createDistributedTracePayload , que solo crea carga distribuida de rastreo New Relic.

// Call newrelic.getTransaction to retrieve a handle on the current transaction.
const transactionHandle = newrelic.getTransaction();

// This could be a header object from an incoming request as well
const headersObject = {};
newrelic.startBackgroundTransaction('background task', function executeTransaction() {
  const transaction = newrelic.getTransaction();
  // generate the headers
  transaction.insertDistributedTraceHeaders(headersObject);
});

transactionHandle.acceptDistributedTraceHeaders(transportType, headers)

Para obtener contexto sobre cómo utilizar esta llamada y su llamada asociada insertDistributedTraceHeaders, primero lea Habilitar rastreo distribuido con API de agente.

transactionHandle.acceptDistributedTraceHeaders se utiliza para instrumentar el servicio llamado para su inclusión en un rastreo distribuido. Vincula los tramos en una traza aceptando una carga útil 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 de New Relic. Este método reemplaza el obsoleto (y ahora eliminado a partir de la versión 7.0.0) Método acceptDistributedTracePayload , que solo maneja la carga distribuida de rastreo de New Relic.

transportType debe ser una de las siguientes cadenas:

• AMQP
• HTTP
• HTTPS
• HierroMQ
• JMS
• kafka
• Otro
• Cola
• Desconocido

headers debe ser un objeto que contenga todos los encabezados de la solicitud entrante. Las claves deben estar en minúsculas.

// incoming Kafka message headers
const headersObject = message.headers;

// Call newrelic.getTransaction to retrieve a handle on the current transaction.
const transactionHandle = newrelic.getTransaction();

newrelic.startBackgroundTransaction('background task', function executeTransaction() {
  const transaction = newrelic.getTransaction();

  // accept the headers
  transaction.acceptDistributedTraceHeaders('Kafka', headersObject);
});

transactionHandle.createDistributedTracePayload()

Para obtener instrucciones sobre cómo utilizar esta llamada, junto con su llamada de socio acceptDistributedTracePayload, consulte Habilitar rastreo distribuido con API de agente.

Esta convocatoria se utiliza para implementar rastreo distribuido. Genera una carga útil que la aplicación receptora lee con acceptDistributedTracePayload.

El objeto DistributedTracePayload tiene dos métodos disponibles que se utilizan para generar la carga útil en diferentes formatos:

• DistributedTracePayload#text: devuelve una representación JSON de la carga útil.

  Vincular una transacción en segundo plano anidada

  // Call newrelic.getTransaction to retrieve a handle on the current transaction.
  var transactionHandle = newrelic.getTransaction();
  var payload = transactionHandle.createDistributedTracePayload();
  var jsonPayload = payload.text();
  newrelic.startBackgroundTransaction('background task', function executeTransaction() {
    var backgroundHandle = newrelic.getTransaction();
    // Link the nested transaction by accepting the payload with the background transaction's handle
    backgroundHandle.acceptDistributedTracePayload(jsonPayload);
  });

  Copia

• DistributedTracePayload#httpSafe: devuelve una representación JSON codificada en base64 de la carga útil.

  Colocar carga útil en una solicitud saliente

  // Call newrelic.getTransaction to retrieve a handle on the current transaction.
  var transactionHandle = newrelic.getTransaction();
  var payload = transactionHandle.createDistributedTracePayload();
  // Place the base64 encoded value on an outbound request header.
  req.headers[myTracingHeader] = payload.httpSafe();

  Copia

transactionHandle.acceptDistributedTracePayload(payload)

Para obtener contexto sobre cómo utilizar esta llamada y su llamada asociada createDistributedTracePayload, primero lea Habilitar rastreo distribuido con API de agente.

transactionHandle.acceptDistributedTracePayload se utiliza para instrumentar el servicio llamado para su inclusión en un rastreo distribuido. Vincula los tramos en una traza aceptando la carga útil generada por createDistributedTracePayload.

transactionHandle.isSampled()

Devuelve si esta traza está siendo muestreada.

newrelic.addCustomAttribute(name, value)

Establezca un valor de atributo personalizado que se mostrará junto con la traza de la transacción en la UI de New Relic. Esto debe llamarse dentro del contexto de una transacción para que tenga un lugar para configurar el atributo personalizado. El atributo personalizado aparecerá en la vista detallada de la traza de la transacción de APM y en los errores de la transacción.

newrelic.addCustomAttribute('attribute1', 'value1')

newrelic.addCustomAttributes(attributes)

Establezca múltiples valores personalizados de atributos que se mostrarán junto con la traza de la transacción en la UI de New Relic. El atributo debe pasarse como un único objeto. Esto debe llamarse dentro del contexto de una transacción para que tenga un lugar para configurar el atributo personalizado. El atributo personalizado aparecerá en la vista detallada de la traza de la transacción y en los errores de la transacción.

const attributes = {
  attribute1: 'value1',
  attribute2: 2
};

newrelic.addCustomAttributes(attributes);

newrelic.addCustomSpanAttribute(name, value)

Establezca un valor de atributo de intervalo personalizado que se mostrará junto con una traza de la transacción en la UI de New Relic. Esto debe llamarse dentro del contexto de un segmento/intervalo activo para que tenga un lugar para configurar el atributo de intervalo personalizado. El atributo de tramo personalizado aparecerá en la sección de atributos de la vista detallada del tramo.

newrelic.addCustomSpanAttribute('attribute1', 'value')

newrelic.addCustomSpanAttributes(attributes)

Establezca múltiples valores de atributos de intervalo personalizados que se mostrarán junto con la traza de la transacción en la UI de New Relic. El atributo debe pasarse como un único objeto. Esto debe llamarse dentro del contexto de un segmento/intervalo activo para que tenga un lugar para configurar el atributo de intervalo personalizado. El atributo de tramo personalizado aparecerá en la sección de atributos de la vista detallada del tramo.

const attributes = {
  attribute1: 'value1',
  attribute2: 'value2'
};

newrelic.addCustomSpanAttributes(attributes);

newrelic.getBrowserTimingHeader()

Devuelve el fragmento de HTML que se insertará en el encabezado de las páginas HTML para habilitar monitoreo de browser. El HTML le indicará al browser que busque un pequeño archivo JavaScript e inicie el temporizador de la página.

newrelic.noticeError(error, [customAttributes], [expected])

Utilice esta llamada si su aplicación realiza su propio manejo de errores con cláusulas de dominio o try/catch, pero desea que toda la información sobre cuántos errores surgen de la aplicación se administre de manera centralizada. A diferencia de otras llamadas de Node.js, esto se puede usar fuera de los controladores de ruta, pero tendrá contexto adicional si se llama desde dentro del alcance de la transacción.

error debe ser un Error o uno de sus subtipos, pero la API manejará cadenas y objetos que tengan una propiedad .message o .stack adjunta.

customAttributes es un objeto opcional de cualquier atributo personalizado que se mostrará en la UI de New Relic.

expected es un booleano opcional para clasificar el error como un error esperado. Si un error recopilado con noticeError es expected, se recopilará y reportará, pero no afectará Apdex ni a la tasa de errores métrica. De forma predeterminada, expected es false.

Example:

try {
  performSomeTask();
} catch(err) {
  newrelic.noticeError(
    err,
    { extraInformation: "error already handled in the application" },
    true
  );
}

newrelic.setErrorGroupCallback(callback)

Este método le permite definir una devolución de llamada personalizada para generar nombres de grupos de errores, que serán utilizados por Errors Inbox para agrupar errores similares a través del atributo de agente error.group.name.

Las funciones proporcionadas deben devolver una cadena y recibir un objeto como argumento. El objeto contiene información relacionada con el error ocurrido y tiene el siguiente formato:

{
  "customAttributes": object,
  "request.uri": string,
  "http.statusCode": string,
  "http.method": string,
  "error": Error,
  "error.expected": boolean
}

Llamar a esta función varias veces reemplazará las versiones definidas previamente de esta función de devolución de llamada.

Para obtener más información sobre esta función, consulte nuestra aplicación de ejemplo.

newrelic.setIgnoreTransaction(ignored)

Indique al módulo si debe ignorar o no una solicitud determinada. Esto le permite filtrar explícitamente rutas o solicitudes irrelevantes y de sondeo largo que sabe que consumirán mucho tiempo. Esto también le permite recopilar métricas para solicitudes que de otro modo serían ignoradas.

• Para ignorar la transacción, establezca el parámetro en true: esto ignorará la transacción.
• Para evitar que una transacción sea ignorada con esta función, pase el parámetro false.
• Pasar null o undefined no cambiará si se ignora la transacción.

newrelic.setUserID(string)

Este método le brinda una manera de asociar un identificador único con un evento de transacción, traza de la transacción y errores dentro de la transacción. Se agregará una nueva propiedad, enduser.id, al error y se informará a Errors Inbox.

newrelic.shutdown(options, callback)

Utilice este método para cerrar correctamente el agente; ambos parámetros son opcionales. Aquí hay una tabla general que muestra el parámetro:

Aquí hay una tabla detallada que muestra las opciones de apagado del objeto:

Example:

newrelic.shutdown({collectPendingData: true, timeout: 10000}, (error) => {
  process.exit();
});

newrelic.getLinkingMetadata()

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

Sólo contendrá elementos con valores significativos. Para instancia, si rastreo distribuido está deshabilitado, trace.id no se incluirá.

newrelic.getTraceMetadata()

Devuelve un objeto que contiene el ID de traza actual y el ID de tramo.

Una lista de reglas del formato {pattern : "pattern", name : "name"} para hacer coincidir las URL de solicitud entrantes con pattern y nombrar la transacción New Relic coincidente name. Esto actúa como un reemplazo de expresiones regulares, donde puede establecer el patrón como una cadena o como un literal de expresión regular de JavaScript, y tanto el patrón como el nombre son obligatorios.

Al pasar una expresión regular como una cadena, escape las barras invertidas, ya que el agente no las conserva cuando se las proporciona como una cadena en un patrón. Defina sus reglas de configuración desde las más específicas hasta las más generales, ya que los patrones se evaluarán en orden y son de naturaleza terminal. Para obtener más información, consulte las pautas de nomenclatura.

Esto también se puede configurar con la variable de entorno NEW_RELIC_NAMING_RULES, con múltiples reglas pasadas como una lista de literales de objetos JSON delimitados por comas:

NEW_RELIC_NAMING_RULES='{"pattern":"^t","name":"u"},{"pattern":"^u","name":"t"}'

Atributo de reglas opcionales

Hay disponibles atributos opcionales adicionales:

pattern: '[0-9]+',
replace_all: true

Probando tus reglas de nomenclatura

El agente de Node.js viene con una herramienta de línea de comando para probar reglas de nomenclatura. Para obtener más información, ejecute el siguiente comando en la ventana de terminal en un directorio donde esté instalada su aplicación:

$
node node_modules/.bin/newrelic-naming-rules

Ejemplos de reglas de nomenclatura [#examples-rules]

A continuación se muestran algunos ejemplos de reglas de nomenclatura y los resultados.

pattern: "^/items/[0-9]+$",
name: "/items/:id"

/items/123   =>  /items/:id
/orders/123  =>  /orders/123   (not replaced since the rule is a full match)

pattern: "[0-9]+",
name: ":id"

/orders/123            =>  /orders/:id
/items/123             =>  /items/:id
/orders/123/items/123  =>  /orders/:id/items/123

pattern: "[0-9]+",
name: ":id",
replace_all: true

/orders/123/items/123  =>  /orders/:id/items/:id

pattern: '^/(items|orders)/[0-9]+$',
name: '/\\1/:id'

/orders/123  =>  /orders/:id
/items/123   =>  /items/:id

Esto también se puede configurar mediante la variable de entorno NEW_RELIC_IGNORING_RULES, con múltiples reglas pasadas como una lista de patrones delimitados por comas. Actualmente no hay forma de escapar de las comas en los patrones.

NEW_RELIC_IGNORING_RULES='^/socket\.io/\*/xhr-polling,ignore_me'

Si está utilizando socket.io, tendrá un caso de uso para ignorar reglas desde el primer momento. Para evitar que el sondeo prolongado de socket.io domine su métrica de tiempo de respuesta y afecte la métrica de Apdex de su aplicación, agregue una regla como:

// newrelic.js
exports.config = {
  // other configuration
  rules : {
    ignore : [
      '^\/socket\.io\/.*\/xhr-polling'
    ]
  }
};

Versión programática de rules.name. Una vez que se agregan las reglas de nomenclatura, no se pueden eliminar hasta que se reinicie el proceso de Node.js. También se pueden agregar mediante la configuración del agente de Node.js. Ambos parámetros son obligatorios.

Versión programática de rules.ignore. Una vez que se agregan reglas para ignorar, no se pueden eliminar hasta que se reinicie el proceso de Node.js. También se pueden agregar mediante la configuración del agente de Node.js. Este parámetro es obligatorio.