Eventos de rastreamento

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Código-fonte: lib/trace_events.js

O módulo node:trace_events fornece um mecanismo para centralizar informações de rastreamento geradas pelo V8, pelo núcleo do Node.js e pelo código do espaço do usuário.

O rastreamento pode ser habilitado com a sinalização de linha de comando --trace-event-categories ou usando o módulo node:trace_events. A sinalização --trace-event-categories aceita uma lista de nomes de categorias separados por vírgula.

As categorias disponíveis são:

• node: Um espaço reservado vazio.

• node.async_hooks: Habilita a captura de dados de rastreamento detalhados de async_hooks. Os eventos async_hooks têm um asyncId exclusivo e uma propriedade triggerId triggerAsyncId especial.

• node.bootstrap: Habilita a captura de marcos de inicialização do Node.js.

• node.console: Habilita a captura da saída de console.time() e console.count().

• node.threadpoolwork.sync: Habilita a captura de dados de rastreamento para operações síncronas do pool de threads, como blob, zlib, crypto e node_api.

• node.threadpoolwork.async: Habilita a captura de dados de rastreamento para operações assíncronas do pool de threads, como blob, zlib, crypto e node_api.

• node.dns.native: Habilita a captura de dados de rastreamento para consultas DNS.

• node.net.native: Habilita a captura de dados de rastreamento para rede.

• node.environment: Habilita a captura de marcos do ambiente Node.js.

• node.fs.sync: Habilita a captura de dados de rastreamento para métodos de sincronização do sistema de arquivos.

• node.fs_dir.sync: Habilita a captura de dados de rastreamento para métodos de diretório de sincronização do sistema de arquivos.

• node.fs.async: Habilita a captura de dados de rastreamento para métodos assíncronos do sistema de arquivos.

• node.fs_dir.async: Habilita a captura de dados de rastreamento para métodos de diretório assíncronos do sistema de arquivos.

• node.perf: Habilita a captura de medições da API de desempenho.

  • node.perf.usertiming: Habilita a captura apenas de medições e marcas de tempo do usuário da API de desempenho.
  • node.perf.timerify: Habilita a captura apenas de medições timerify da API de desempenho.

• node.promises.rejections: Habilita a captura de dados de rastreamento que acompanham o número de rejeições de Promise não tratadas e tratadas após rejeições.

• node.vm.script: Habilita a captura de dados de rastreamento para os métodos runInNewContext(), runInContext() e runInThisContext() do módulo node:vm.

• v8: Os eventos V8 são relacionados a GC, compilação e execução.

• node.http: Habilita a captura de dados de rastreamento para solicitação/resposta http.

• node.module_timer: Habilita a captura de dados de rastreamento para o carregamento do módulo CJS.

Por padrão, as categorias node, node.async_hooks e v8 estão habilitadas.

node --trace-event-categories v8,node,node.async_hooks server.js

Versões anteriores do Node.js exigiam o uso da sinalização --trace-events-enabled para habilitar eventos de rastreamento. Esse requisito foi removido. No entanto, a sinalização --trace-events-enabled pode ainda ser usada e habilitará as categorias de eventos de rastreamento node, node.async_hooks e v8 por padrão.

node --trace-events-enabled

# é equivalente a {#is-equivalent-to}

node --trace-event-categories v8,node,node.async_hooks

Alternativamente, os eventos de rastreamento podem ser habilitados usando o módulo node:trace_events:

const trace_events = require('node:trace_events')
const tracing = trace_events.createTracing({ categories: ['node.perf'] })
tracing.enable() // Habilita a captura de eventos de rastreamento para a categoria 'node.perf'

// faça o trabalho

tracing.disable() // Desabilita a captura de eventos de rastreamento para a categoria 'node.perf'

Executar o Node.js com rastreamento habilitado gerará arquivos de log que podem ser abertos na guia chrome://tracing do Chrome.

O arquivo de log é chamado por padrão node_trace.${rotation}.log, onde ${rotation} é um ID de rotação de log incremental. O padrão do caminho do arquivo pode ser especificado com --trace-event-file-pattern que aceita uma string de modelo que suporta ${rotation} e ${pid}:

node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js

Para garantir que o arquivo de log seja gerado corretamente após eventos de sinal como SIGINT, SIGTERM ou SIGBREAK, certifique-se de ter os manipuladores apropriados em seu código, como:

process.on('SIGINT', function onSigint() {
  console.info('Recebido SIGINT.')
  process.exit(130) // Ou código de saída aplicável dependendo do SO e do sinal
})

O sistema de rastreamento usa a mesma fonte de tempo que a usada por process.hrtime(). No entanto, os timestamps de eventos de rastreamento são expressos em microssegundos, ao contrário de process.hrtime(), que retorna nanossegundos.

Os recursos deste módulo não estão disponíveis em threads Worker.

O módulo node:trace_events

Adicionado em: v10.0.0

Objeto Tracing

Adicionado em: v10.0.0

O objeto Tracing é usado para habilitar ou desabilitar o rastreamento para conjuntos de categorias. Instâncias são criadas usando o método trace_events.createTracing().

Quando criado, o objeto Tracing está desabilitado. Chamar o método tracing.enable() adiciona as categorias ao conjunto de categorias de eventos de rastreamento habilitadas. Chamar tracing.disable() removerá as categorias do conjunto de categorias de eventos de rastreamento habilitadas.

tracing.categories

Adicionado em: v10.0.0

• <string>

Uma lista separada por vírgulas das categorias de eventos de rastreamento cobertas por este objeto Tracing.

tracing.disable()

Adicionado em: v10.0.0

Desabilita este objeto Tracing.

Apenas as categorias de eventos de rastreamento não cobertas por outros objetos Tracing habilitados e não especificadas pela flag --trace-event-categories serão desabilitadas.

const trace_events = require('node:trace_events')
const t1 = trace_events.createTracing({ categories: ['node', 'v8'] })
const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] })
t1.enable()
t2.enable()

// Imprime 'node,node.perf,v8'
console.log(trace_events.getEnabledCategories())

t2.disable() // Somente desabilitará a emissão da categoria 'node.perf'

// Imprime 'node,v8'
console.log(trace_events.getEnabledCategories())

tracing.enable()

Adicionado em: v10.0.0

Habilita este objeto Tracing para o conjunto de categorias cobertas pelo objeto Tracing.

tracing.enabled

Adicionado em: v10.0.0

• <boolean> true apenas se o objeto Tracing foi habilitado.

trace_events.createTracing(options)

Adicionado em: v10.0.0

• options <Object>

  • categories <string[]> Uma matriz de nomes de categorias de rastreamento. Os valores incluídos na matriz são convertidos para string quando possível. Um erro será lançado se o valor não puder ser convertido.

• Retorna: <Tracing>.

Cria e retorna um objeto Tracing para o conjunto dado de categories.

const trace_events = require('node:trace_events')
const categories = ['node.perf', 'node.async_hooks']
const tracing = trace_events.createTracing({ categories })
tracing.enable()
// faça algo
tracing.disable()

trace_events.getEnabledCategories()

Adicionado em: v10.0.0

• Retorna: <string>

Retorna uma lista separada por vírgulas de todas as categorias de eventos de rastreamento atualmente habilitadas. O conjunto atual de categorias de eventos de rastreamento habilitadas é determinado pela união de todos os objetos Tracing atualmente habilitados e quaisquer categorias habilitadas usando a flag --trace-event-categories.

Dado o arquivo test.js abaixo, o comando node --trace-event-categories node.perf test.js imprimirá 'node.async_hooks,node.perf' no console.

const trace_events = require('node:trace_events')
const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] })
const t2 = trace_events.createTracing({ categories: ['node.perf'] })
const t3 = trace_events.createTracing({ categories: ['v8'] })

t1.enable()
t2.enable()

console.log(trace_events.getEnabledCategories())

Exemplos

Coletar dados de eventos de rastreamento pelo inspetor

'use strict'

const { Session } = require('node:inspector')
const session = new Session()
session.connect()

function post(message, data) {
  return new Promise((resolve, reject) => {
    session.post(message, data, (err, result) => {
      if (err) reject(new Error(JSON.stringify(err)))
      else resolve(result)
    })
  })
}

async function collect() {
  const data = []
  session.on('NodeTracing.dataCollected', chunk => data.push(chunk))
  session.on('NodeTracing.tracingComplete', () => {
    // done
  })
  const traceConfig = { includedCategories: ['v8'] }
  await post('NodeTracing.start', { traceConfig })
  // do something
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect()
      console.log(data)
    })
  }, 1000)
}

collect()