API do agente Node.js

newrelic.setTransactionName(name)

Nomeie a solicitação atual, seguindo os requisitos de nomenclatura da solicitação. Você pode chamar essa função em qualquer lugar dentro do contexto de um manipulador de solicitação HTTP, a qualquer momento após o início do processamento da solicitação, mas antes da conclusão da solicitação. Em geral, se os objetos de solicitação e resposta estiverem no escopo, você poderá definir o nome.

Chamar newrelic.setTransactionName() explicitamente substituirá quaisquer nomes definidos pelas rotas Express ou Restify. Além disso, as chamadas para newrelic.setTransactionName() e newrelic.setControllerName() substituirão uma à outra. O último a ser executado antes do término da solicitação vence.

newrelic.setControllerName(name, [action])

Nomeie a solicitação atual usando um padrão estilo controlador, incluindo opcionalmente a ação atual do controlador. Se a ação for omitida, o New Relic incluirá o método HTTP (GET, POST, etc.) como a ação. As regras para quando você pode chamar newrelic.setControllerName() são as mesmas de newrelic.setTransactionName(), incluindo os requisitos de nomenclatura da solicitação.

Chamar newrelic.setControllerName() explicitamente substituirá quaisquer nomes definidos pelas rotas Express ou Restify. Além disso, as chamadas para newrelic.setTransactionName() e newrelic.setControllerName() substituirão uma à outra. O último a ser executado antes do término da solicitação vence.

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

Define um retorno de chamada de instrumentação para um módulo específico.

O retorno de chamada onRequire fornecido será acionado quando o módulo fornecido for carregado com require. O parâmetro moduleName deve ser a string que será passada para require; por exemplo, 'express' ou 'amqplib/callback_api'. O retorno de chamada onError opcional será chamado se o parâmetro onRequire gerar um erro. Isso é útil para depurar sua instrumentação.

Use este método para:

• Adicione instrumentação para módulos não instrumentados atualmente pela New Relic.
• Instrumento seu próprio código.
• Substitua a instrumentação integrada do agente Node.js pela sua própria.

Para obter mais informações, consulte o tutorial de instrumentação Node.js da New Relic no Github.

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

Define um retorno de chamada de instrumentação para um módulo de armazenamento de dados.

Este método é semelhante a newrelic.instrument(), exceto que fornece um shim especializado em armazenamento de dados. Para obter mais informações, consulte o tutorial de instrumentação de armazenamento de dados Node.js da New Relic no Github.

newrelic.instrumentLoadedModule(moduleName, moduleInstance)

O método instrumentLoadedModule permite adicionar instrumentação padrão a módulos específicos em situações em que é impossível ter require('newrelic'); como a primeira linha do módulo principal do seu aplicativo.

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

Configura um retorno de chamada de instrumentação para um módulo cliente de serviço de mensagens.

Este método é semelhante a newrelic.instrument(), exceto que fornece um shim especializado em serviço de mensagens. Para obter mais informações, consulte o tutorial de instrumentação de serviço de mensagens Node.js da New Relic no Github.

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

Define um retorno de chamada de instrumentação para um módulo framework web.

Este método é exatamente como newrelic.instrument(), exceto que fornece um shim web-framework-specialized. Para obter mais informações, consulte o tutorial de instrumentação framework da web Node.js da New Relic no Github.

newrelic.startWebTransaction(url, handle)

Instrumento a transação web especificada. Usando esta chamada de API, você pode usar instrumentos de transação que o New Relic não detecta automaticamente.

• O url define o nome da transação e precisa ser estático. Não inclua dados variáveis, como ID do usuário.
• O handle define a função que você deseja instrumento.

O New Relic capturará qualquer métrica que seria capturada por instrumentação automática, bem como instrumentação manual por meio de startSegment().

Você must processa transações personalizadas manualmente chamando newrelic.getTransaction() no início de sua transação e, em seguida, ligando para transaction.end() quando terminar. O New Relic começa a cronometrar a transação quando newrelic.startWebTransaction() é chamado e termina a transação quando transaction.end() é chamado.

Você também pode retornar uma promessa para indicar o fim da transação. Observe que se esta promessa for rejeitada, ela não será automaticamente vinculada ao monitoramento de erros da New Relic. Isso precisa ser feito manualmente com noticeError().

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

Instrumento a transação em segundo plano especificada. Usando esta chamada de API, você pode expandir a instrumentação da New Relic para capturar dados de transações em segundo plano.

• O name define o nome da transação e precisa ser estático. Não inclua dados variáveis, como ID do usuário.

• O group é opcional e permite agrupar tarefas semelhantes por meio do

  transaction type

  na interface do usuário. Assim como name, o group precisa ser estático.

• O handle define uma função que inclui todo o trabalho em segundo plano que você deseja instrumentar.

O New Relic capturará qualquer métrica que seria capturada por instrumentação automática, bem como instrumentação manual por meio de startSegment().

Você must processa transações personalizadas manualmente chamando newrelic.getTransaction() no início de sua transação e, em seguida, ligando para transaction.end() quando terminar. O New Relic começa a cronometrar a transação quando newrelic.startBackgroundTransaction() é chamado e termina a transação quando transaction.end() é chamado.

Você também pode retornar uma promessa para indicar o fim da transação. Observe que se esta promessa for rejeitada, ela não será automaticamente vinculada ao monitoramento de erros da New Relic. Isso precisa ser feito manualmente com noticeError().

newrelic.getTransaction()

Retorna um identificador da transação atualmente em execução. Esse identificador pode então ser usado para interagir com uma determinada transação com segurança em qualquer contexto. É melhor usado com newrelic.startWebTransaction() e newrelic.startBackgroundTransaction().

Consulte a seção de manuseio de transação para obter mais detalhes.

newrelic.endTransaction()

Encerre a transação personalizada atual da web ou em segundo plano . Este método requer estar no contexto de transação correto quando chamado. Esta chamada de API não aceita argumentos.

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

Instrumento um método específico para melhorar a visibilidade de uma transação ou, opcionalmente, transformá-la em uma métrica.

• O name define um nome para o segmento. Este nome ficará visível no trace da transação e como uma nova métrica na interface do New Relic.
• A sinalização record define se o segmento deve ser registrado como uma métrica.
• O handler é a função que você deseja acompanhar como um segmento.
• O opcional callback é uma função passada ao manipulador para ser acionada após a conclusão do trabalho.

O agente começa a cronometrar o segmento quando startSegment é chamado. O segmento termina quando handler termina a execução ou callback é acionado, se for fornecido.

newrelic.recordMetric(name, value)

Use recordMetric para registrar uma métrica baseada em evento, geralmente associada a uma duração específica. O name deve ser uma string seguindo regras de nomenclatura de métrica padrão. O value geralmente será um número, mas também pode ser um objeto.

• Quando value for um valor numérico, deverá representar a magnitude de uma medida associada a um evento; por exemplo, a duração de uma chamada de método específica.
• Quando value é um objeto, ele deve conter chaves count, total, min, max e sumOfSquares , todas com valores numéricos. Este formulário é útil para agregar métricas por conta própria e reportá-las periodicamente; por exemplo, de um setInterval. Esses valores serão agregados a quaisquer valores coletados anteriormente para a mesma métrica. Os nomes dessas chaves correspondem aos nomes das chaves usadas pela API da plataforma.

newrelic.incrementMetric(name, [amount])

Use incrementMetric para atualizar uma métrica que funciona como um contador simples. A contagem da métrica selecionada será incrementada no valor especificado, com valor padrão de 1.

newrelic.recordCustomEvent(eventType, attributes)

Use recordCustomEvent para registrar uma métrica baseada em evento, geralmente associada a uma duração específica.

• O eventType deve ser uma sequência alfanumérica com menos de 255 caracteres.
• O attributes deve ser um objeto de pares de chave e valor. As chaves devem ter menos de 255 caracteres e os valores devem ser string, número ou booleano.

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

newrelic.recordCustomEvent('MessagingEvent', attributes);

newrelic.recordLogEvent({message, level})

Use recordLogEvent para registrar um evento de log, caso a instrumentação de registro automático seja insuficiente para sua framework de registro. Consulte a documentação gerada automaticamente para obter detalhes dos tipos de parâmetros aceitos.

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

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

transactionHandle.end([callback])

Use transactionHandle.end para encerrar a transação referenciada pela instância de identificador.

O callback é invocado quando a transação é totalmente encerrada. A transação concluída é passada para o retorno de chamada como primeiro argumento.

transactionHandle.ignore()

Use transactionHandle.ignore para ignorar a transação referenciada pela instância de identificador.

transactionHandle.insertDistributedTraceHeaders(headers)

Para obter contexto sobre como usar esta chamada e sua chamada de parceiro acceptDistributedTraceHeaders, leia primeiro Habilitar distributed tracing com API do agente.

transactionHandle.insertDistributedTraceHeaders é usado para implementar distributed tracing. Ele modifica o mapa headers transmitido adicionando cabeçalhos W3C Trace Context e cabeçalhos distributed trace New Relic. Os cabeçalhos New Relic podem ser desabilitados com distributed_tracing.exclude_newrelic_header: true na configuração. Este método substitui o método createDistributedTracePayload obsoleto, que cria apenas carga distributed trace da 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 obter contexto sobre como usar esta chamada e sua chamada de parceiro insertDistributedTraceHeaders, leia primeiro Habilitar distributed tracing com API do agente.

transactionHandle.acceptDistributedTraceHeaders É usado para instrumentalizar o serviço chamado para inclusão em um distributed trace. Ele vincula os intervalos em um trace aceitando uma carga gerada por ou gerada por algum insertDistributedTraceHeaders outro W3C Trace Context compatível com tracer. Este método aceita os cabeçalhos de uma solicitação recebida, procura cabeçalhos W3C Trace Context e, se não for encontrado, recorre aos cabeçalhos distributed trace da New Relic. Este método substitui o obsoleto (e agora removido a partir da versão 7.0.0) acceptDistributedTracePayload , que lida apenas com carga distributed trace do New Relic.

transportType deve ser uma das seguintes strings:

• AMQP
• HTTP
• HTTPS
• FerroMQ
• JMS
• Kafka
• Outro
• Fila
• Desconhecido

headers deve ser um objeto contendo todos os cabeçalhos da solicitação recebida. As chaves devem estar em 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 obter instruções sobre como usar esta chamada, juntamente com sua chamada de parceiro acceptDistributedTracePayload, consulte Habilitar distributed tracing com API do agente.

Esta chamada é usada para implementar distributed tracing. Ele gera uma carga útil que é lida pelo aplicativo receptor com acceptDistributedTracePayload.

O objeto DistributedTracePayload possui dois métodos disponíveis para geração da carga em diferentes formatos:

• DistributedTracePayload#text: retorna uma representação JSON da carga útil.

  Vincular uma transação em segundo plano aninhada

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

  Copiar

• DistributedTracePayload#httpSafe: retorna uma representação JSON codificada em base64 da carga útil.

  Colocar carga útil em uma solicitação de saída

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

  Copiar

transactionHandle.acceptDistributedTracePayload(payload)

Para obter contexto sobre como usar esta chamada e sua chamada de parceiro createDistributedTracePayload, leia primeiro Habilitar distributed tracing com API do agente.

transactionHandle.acceptDistributedTracePayload É usado para instrumentalizar o serviço chamado para inclusão em um distributed trace. Ele vincula os períodos em um trace aceitando a carga gerada por createDistributedTracePayload.

transactionHandle.isSampled()

Retorna se esse trace está sendo amostrado.

newrelic.addCustomAttribute(name, value)

Defina um valor de atributo personalizado a ser exibido junto com o rastreamento da transação na interface do New Relic. Deve ser chamado dentro do contexto de uma transação para que tenha local para definir o atributo personalizado. o atributo personalizado aparecerá na visualização detalhada do trace da transação do APM e nos erros da transação.

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

newrelic.addCustomAttributes(attributes)

Defina vários valores de atributo personalizado para serem exibidos junto com o rastreamento da transação na interface do New Relic. O atributo deve ser passado como um objeto único. Deve ser chamado dentro do contexto de uma transação para que tenha local para definir o atributo personalizado. o atributo personalizado aparecerá na visualização detalhada do trace da transação e nos erros da transação.

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

newrelic.addCustomAttributes(attributes);

newrelic.addCustomSpanAttribute(name, value)

Defina um valor de atributo de span personalizado para ser exibido junto com um span de rastreamento de transação na interface do New Relic. Isso deve ser chamado dentro do contexto de um segmento/span ativo para que tenha um local para definir o atributo de span personalizado. O atributo de período personalizado aparecerá na seção atributo da visualização de detalhes do período.

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

newrelic.addCustomSpanAttributes(attributes)

Defina vários valores de atributo de span personalizados para serem exibidos junto com os spans de rastreamento da transação na interface do New Relic. O atributo deve ser passado como um objeto único. Isso deve ser chamado dentro do contexto de um segmento/span ativo para que tenha um local para definir o atributo de span personalizado. O atributo de período personalizado aparecerá na seção atributo da visualização de detalhes do período.

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

newrelic.addCustomSpanAttributes(attributes);

newrelic.getBrowserTimingHeader()

Retorna o trecho HTML a ser inserido no cabeçalho das páginas HTML para habilitar monitoramento de browser. O HTML instruirá o browser a buscar um pequeno arquivo JavaScript e iniciar o cronômetro da página.

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

Use esta chamada se seu aplicativo estiver fazendo seu próprio tratamento de erros com domínio ou cláusulas try/catch, mas você deseja que todas as informações sobre quantos erros estão saindo do aplicativo sejam gerenciadas centralmente. Ao contrário de outras chamadas do Node.js, isso pode ser usado fora dos manipuladores de rota, mas terá contexto adicional se for chamado dentro do escopo da transação.

error deve ser um Error ou um de seus subtipos, mas a API manipulará strings e objetos que tenham uma propriedade .message ou .stack anexada.

customAttributes é um objeto opcional de quaisquer atributos personalizados a serem exibidos na interface do New Relic.

expected é um booleano opcional para classificar o erro como um erro esperado. Se um erro coletado com noticeError for expected, ele será coletado e reportado, mas não afetará Apdex ou taxa de erros métricos. Por padrão, expected é false.

Example:

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

newrelic.setErrorGroupCallback(callback)

Este método permite definir um retorno de chamada personalizado para gerar nomes de grupos de erros, que serão usados pela Errors Inbox para agrupar erros semelhantes por meio do atributo do agente error.group.name.

As funções fornecidas devem retornar uma string e receber um objeto como argumento. O objeto contém informações relacionadas ao erro ocorrido e possui o seguinte formato:

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

Chamar esta função várias vezes substituirá as versões definidas anteriormente desta função de retorno de chamada.

Para saber mais sobre esta função, consulte nosso aplicativo de exemplo.

newrelic.setIgnoreTransaction(ignored)

Diga ao módulo se deve ou não ignorar uma determinada solicitação. Isso permite que você filtre explicitamente rotas ou solicitações irrelevantes e de pesquisa longa que você sabe que consumirão muito tempo. Isso também permite coletar métricas para solicitações que de outra forma seriam ignoradas.

• Para ignorar a transação, defina o parâmetro como true: isso ignorará a transação.
• Para evitar que uma transação seja ignorada com esta função, passe o parâmetro false.
• Passar null ou undefined não alterará se a transação será ignorada.

newrelic.setUserID(string)

Este método oferece uma maneira de associar um identificador exclusivo a um evento de transação, rastrear a transação e erros na transação. Uma nova propriedade, enduser.id, será adicionada ao erro e reportada à Errors Inbox.

newrelic.shutdown(options, callback)

Use este método para desligar o agente normalmente, ambos os parâmetros são opcionais. Aqui está uma tabela de visão geral mostrando o parâmetro:

Aqui está uma tabela detalhada mostrando as opções de desligamento do objeto:

Example:

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

newrelic.getLinkingMetadata()

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

Ele conterá apenas itens com valores significativos. Por exemplo, se distributed tracing estiver desabilitado, trace.id não será incluído.

newrelic.getTraceMetadata()

Retorna e objeto contendo o ID trace e o ID de span atuais.

Uma lista de regras no formato {pattern : "pattern", name : "name"} para corresponder URLs de solicitação de entrada a pattern e nomear a transação New Relic correspondente name. Isso atua como uma substituição de regex, onde você pode definir o padrão como uma string ou como uma expressão regular JavaScript literal, e tanto o padrão quanto o nome são obrigatórios.

Ao passar uma regex como string, evite barras invertidas, pois o agente não as mantém quando fornecidas como string em um padrão. Defina suas regras de configuração das mais específicas às mais gerais, pois os padrões serão avaliados em ordem e são de natureza terminal. Para obter mais informações, consulte as diretrizes de nomenclatura.

Isso também pode ser definido com a variável de ambiente NEW_RELIC_NAMING_RULES, com diversas regras passadas como uma lista de literais de objetos JSON delimitados por vírgulas:

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

Atributo de regras opcionais

Atributos opcionais adicionais estão disponíveis:

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

Testando suas regras de nomenclatura

O agente Node.js vem com uma ferramenta de linha de comando para testar regras de nomenclatura. Para obter mais informações, execute o seguinte comando na janela do terminal em um diretório onde seu aplicativo está instalado:

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

Exemplos de regras de nomenclatura [#examples-rules]

Aqui estão alguns exemplos de regras de nomenclatura e os 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

Isso também pode ser definido por meio da variável de ambiente NEW_RELIC_IGNORING_RULES, com diversas regras passadas como uma lista de padrões delimitados por vírgulas. Atualmente não há como escapar das vírgulas nos padrões.

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

Se você estiver usando socket.io, terá um caso de uso para ignorar regras imediatamente. Para evitar que o long polling do socket.io domine sua métrica de tempo de resposta e afete a métrica Apdex de seu aplicativo, adicione uma regra como:

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

Versão programática de rules.name. Depois que as regras de nomenclatura forem adicionadas, elas não poderão ser removidas até que o processo Node.js seja reiniciado. Eles também podem ser adicionados por meio da configuração do agente Node.js. Ambos os parâmetros são obrigatórios.

Versão programática de rules.ignore. Depois que as regras de ignorar são adicionadas, elas não podem ser removidas até que o processo Node.js seja reiniciado. Eles também podem ser adicionados por meio da configuração do agente Node.js. Este parâmetro é obrigatório.