Eventi di traccia

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Codice sorgente: lib/trace_events.js

Il modulo node:trace_events fornisce un meccanismo per centralizzare le informazioni di tracciamento generate da V8, dal core di Node.js e dal codice utente.

Il tracciamento può essere abilitato con il flag della riga di comando --trace-event-categories o utilizzando il modulo node:trace_events. Il flag --trace-event-categories accetta un elenco di nomi di categorie separati da virgole.

Le categorie disponibili sono:

• node: Un segnaposto vuoto.

• node.async_hooks: Abilita la cattura di dati di traccia dettagliati di async_hooks. Gli eventi async_hooks hanno un asyncId univoco e una proprietà speciale triggerId triggerAsyncId.

• node.bootstrap: Abilita la cattura delle pietre miliari di bootstrap di Node.js.

• node.console: Abilita la cattura dell'output di console.time() e console.count().

• node.threadpoolwork.sync: Abilita la cattura dei dati di traccia per le operazioni sincrone del pool di thread, come blob, zlib, crypto e node_api.

• node.threadpoolwork.async: Abilita la cattura dei dati di traccia per le operazioni asincrone del pool di thread, come blob, zlib, crypto e node_api.

• node.dns.native: Abilita la cattura dei dati di traccia per le query DNS.

• node.net.native: Abilita la cattura dei dati di traccia per la rete.

• node.environment: Abilita la cattura delle pietre miliari dell'ambiente Node.js.

• node.fs.sync: Abilita la cattura dei dati di traccia per i metodi sincroni del file system.

• node.fs_dir.sync: Abilita la cattura dei dati di traccia per i metodi sincroni delle directory del file system.

• node.fs.async: Abilita la cattura dei dati di traccia per i metodi asincroni del file system.

• node.fs_dir.async: Abilita la cattura dei dati di traccia per i metodi asincroni delle directory del file system.

• node.perf: Abilita la cattura delle misurazioni dell'API Performance.

  • node.perf.usertiming: Abilita la cattura solo delle misurazioni e dei marcatori User Timing dell'API Performance.
  • node.perf.timerify: Abilita la cattura solo delle misurazioni timerify dell'API Performance.

• node.promises.rejections: Abilita la cattura dei dati di traccia che tengono traccia del numero di rigetti di Promise non gestiti e di quelli gestiti dopo i rigetti.

• node.vm.script: Abilita la cattura dei dati di traccia per i metodi runInNewContext(), runInContext() e runInThisContext() del modulo node:vm.

• v8: Gli eventi V8 sono relativi a GC, compilazione ed esecuzione.

• node.http: Abilita la cattura dei dati di traccia per la richiesta/risposta http.

• node.module_timer: Abilita la cattura dei dati di traccia per il caricamento del modulo CJS.

Per impostazione predefinita, sono abilitate le categorie node, node.async_hooks e v8.

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

Le versioni precedenti di Node.js richiedevano l'utilizzo del flag --trace-events-enabled per abilitare gli eventi di traccia. Questo requisito è stato rimosso. Tuttavia, il flag --trace-events-enabled può ancora essere utilizzato e abiliterà le categorie di eventi di traccia node, node.async_hooks e v8 per impostazione predefinita.

node --trace-events-enabled

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

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

In alternativa, gli eventi di traccia possono essere abilitati utilizzando il modulo node:trace_events:

const trace_events = require('node:trace_events')
const tracing = trace_events.createTracing({ categories: ['node.perf'] })
tracing.enable() // Abilita la cattura degli eventi di traccia per la categoria 'node.perf'

// esegui il lavoro

tracing.disable() // Disabilita la cattura degli eventi di traccia per la categoria 'node.perf'

L'esecuzione di Node.js con il tracciamento abilitato produrrà file di log che possono essere aperti nella scheda chrome://tracing di Chrome.

Il file di log si chiama per impostazione predefinita node_trace.${rotation}.log, dove ${rotation} è un ID di rotazione del log incrementale. Lo schema del percorso del file può essere specificato con --trace-event-file-pattern che accetta una stringa di modello che supporta ${rotation} e ${pid}:

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

Per garantire che il file di log venga generato correttamente dopo eventi di segnale come SIGINT, SIGTERM o SIGBREAK, assicurarsi di avere i gestori appropriati nel codice, ad esempio:

process.on('SIGINT', function onSigint() {
  console.info('Ricevuto SIGINT.')
  process.exit(130) // O codice di uscita applicabile a seconda del sistema operativo e del segnale
})

Il sistema di tracciamento utilizza la stessa origine temporale di quella utilizzata da process.hrtime(). Tuttavia, i timestamp degli eventi di traccia sono espressi in microsecondi, a differenza di process.hrtime() che restituisce nanosecondi.

Le funzionalità di questo modulo non sono disponibili nei thread Worker.

Il modulo node:trace_events

Aggiunto in: v10.0.0

Oggetto Tracing

Aggiunto in: v10.0.0

L'oggetto Tracing viene utilizzato per abilitare o disabilitare il tracing per insiemi di categorie. Le istanze vengono create utilizzando il metodo trace_events.createTracing().

Al momento della creazione, l'oggetto Tracing è disabilitato. Chiamare il metodo tracing.enable() aggiunge le categorie all'insieme delle categorie di eventi di traccia abilitate. Chiamare tracing.disable() rimuoverà le categorie dall'insieme delle categorie di eventi di traccia abilitate.

tracing.categories

Aggiunto in: v10.0.0

• <string>

Un elenco separato da virgole delle categorie di eventi di traccia coperte da questo oggetto Tracing.

tracing.disable()

Aggiunto in: v10.0.0

Disabilita questo oggetto Tracing.

Solo le categorie di eventi di traccia non coperte da altri oggetti Tracing abilitati e non specificate dal flag --trace-event-categories verranno disabilitate.

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

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

t2.disable() // Disabiliterà solo l'emissione della categoria 'node.perf'

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

tracing.enable()

Aggiunto in: v10.0.0

Abilita questo oggetto Tracing per l'insieme di categorie coperte dall'oggetto Tracing.

tracing.enabled

Aggiunto in: v10.0.0

• <boolean> true solo se l'oggetto Tracing è stato abilitato.

trace_events.createTracing(options)

Aggiunto in: v10.0.0

• options <Object>

  • categories <string[]> Una matrice di nomi di categorie di traccia. I valori inclusi nella matrice vengono convertiti in stringa quando possibile. Verrà generato un errore se il valore non può essere convertito.

• Restituisce: <Tracing>.

Crea e restituisce un oggetto Tracing per l'insieme di categories dato.

const trace_events = require('node:trace_events')
const categories = ['node.perf', 'node.async_hooks']
const tracing = trace_events.createTracing({ categories })
tracing.enable()
// fai qualcosa
tracing.disable()

trace_events.getEnabledCategories()

Aggiunto in: v10.0.0

• Restituisce: <string>

Restituisce un elenco separato da virgole di tutte le categorie di eventi di traccia attualmente abilitate. L'insieme corrente di categorie di eventi di traccia abilitate è determinato dall' unione di tutti gli oggetti Tracing attualmente abilitati e di qualsiasi categoria abilitata utilizzando il flag --trace-event-categories.

Dato il file test.js di seguito, il comando node --trace-event-categories node.perf test.js stamperà 'node.async_hooks,node.perf' sulla 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())

Esempi

Raccogliere dati sugli eventi di traccia tramite l'ispettore

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