Trace-Ereignisse

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Quellcode: lib/trace_events.js

Das Modul node:trace_events bietet einen Mechanismus zur Zentralisierung von Tracing-Informationen, die von V8, Node.js-Core und Benutzercode generiert werden.

Das Tracing kann mit dem Befehlszeilen-Flag --trace-event-categories oder mit dem Modul node:trace_events aktiviert werden. Das Flag --trace-event-categories akzeptiert eine Liste von durch Kommas getrennten Kategorienamen.

Die verfügbaren Kategorien sind:

• node: Ein leerer Platzhalter.
• node.async_hooks: Aktiviert die Erfassung detaillierter async_hooks-Tracedaten. Die async_hooks-Ereignisse haben eine eindeutige asyncId und eine spezielle triggerId-Eigenschaft triggerAsyncId.
• node.bootstrap: Aktiviert die Erfassung von Node.js-Bootstrap-Meilensteinen.
• node.console: Aktiviert die Erfassung der Ausgaben von console.time() und console.count().
• node.threadpoolwork.sync: Aktiviert die Erfassung von Tracedaten für synchrone Threadpool-Operationen, wie z. B. blob, zlib, crypto und node_api.
• node.threadpoolwork.async: Aktiviert die Erfassung von Tracedaten für asynchrone Threadpool-Operationen, wie z. B. blob, zlib, crypto und node_api.
• node.dns.native: Aktiviert die Erfassung von Tracedaten für DNS-Abfragen.
• node.net.native: Aktiviert die Erfassung von Tracedaten für das Netzwerk.
• node.environment: Aktiviert die Erfassung von Node.js-Umgebungsmeilensteinen.
• node.fs.sync: Aktiviert die Erfassung von Tracedaten für synchrone Dateisystemmethoden.
• node.fs_dir.sync: Aktiviert die Erfassung von Tracedaten für synchrone Dateisystemverzeichnis-Methoden.
• node.fs.async: Aktiviert die Erfassung von Tracedaten für asynchrone Dateisystemmethoden.
• node.fs_dir.async: Aktiviert die Erfassung von Tracedaten für asynchrone Dateisystemverzeichnis-Methoden.
• node.perf: Aktiviert die Erfassung von Performance API-Messungen.
  • node.perf.usertiming: Aktiviert die Erfassung von ausschließlich Performance-API-Benutzer-Timing-Messungen und -Markierungen.
  • node.perf.timerify: Aktiviert die Erfassung von ausschließlich Performance-API-Timerify-Messungen.
• node.promises.rejections: Aktiviert die Erfassung von Tracedaten zur Verfolgung der Anzahl von nicht behandelten Promise-Ablehnungen und nachbearbeiteten Ablehnungen.
• node.vm.script: Aktiviert die Erfassung von Tracedaten für die node:vm-Modulmethoden runInNewContext(), runInContext() und runInThisContext().
• v8: Die V8-Ereignisse beziehen sich auf GC, Kompilierung und Ausführung.
• node.http: Aktiviert die Erfassung von Tracedaten für HTTP-Anfragen/-Antworten.
• node.module_timer: Aktiviert die Erfassung von Tracedaten für das Laden von CJS-Modulen.

Standardmäßig sind die Kategorien node, node.async_hooks und v8 aktiviert.

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

Frühere Versionen von Node.js erforderten die Verwendung des Flags --trace-events-enabled, um Trace-Ereignisse zu aktivieren. Diese Anforderung wurde entfernt. Das Flag --trace-events-enabled kann jedoch weiterhin verwendet werden und aktiviert standardmäßig die Trace-Ereigniskategorien node, node.async_hooks und v8.

node --trace-events-enabled

# ist gleichbedeutend mit {#is-equivalent-to}

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

Alternativ können Trace-Ereignisse mit dem Modul node:trace_events aktiviert werden:

const trace_events = require('node:trace_events')
const tracing = trace_events.createTracing({ categories: ['node.perf'] })
tracing.enable() // Aktiviert die Erfassung von Trace-Ereignissen für die Kategorie 'node.perf'

// Arbeit ausführen

tracing.disable() // Deaktiviert die Erfassung von Trace-Ereignissen für die Kategorie 'node.perf'

Das Ausführen von Node.js mit aktiviertem Tracing erzeugt Protokolldateien, die im Tab chrome://tracing von Chrome geöffnet werden können.

Die Protokolldatei heißt standardmäßig node_trace.${rotation}.log, wobei ${rotation} eine inkrementelle Protokollrotations-ID ist. Das Dateipfadmuster kann mit --trace-event-file-pattern angegeben werden, das eine Template-Zeichenkette akzeptiert, die ${rotation} und ${pid} unterstützt:

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

Um sicherzustellen, dass die Protokolldatei nach Signalereignissen wie SIGINT, SIGTERM oder SIGBREAK ordnungsgemäß generiert wird, stellen Sie sicher, dass Sie die entsprechenden Handler in Ihrem Code haben, wie z. B.:

process.on('SIGINT', function onSigint() {
  console.info('SIGINT empfangen.')
  process.exit(130) // Oder ein anwendbarer Exit-Code, abhängig von Betriebssystem und Signal
})

Das Tracing-System verwendet dieselbe Zeitquelle wie die von process.hrtime(). Die Zeitstempel für Trace-Ereignisse werden jedoch im Gegensatz zu process.hrtime(), das Nanosekunden zurückgibt, in Mikrosekunden ausgedrückt.

Die Funktionen dieses Moduls sind in Worker-Threads nicht verfügbar.

Das Modul node:trace_events

Hinzugefügt in: v10.0.0

Tracing-Objekt

Hinzugefügt in: v10.0.0

Das Tracing-Objekt wird verwendet, um das Tracing für Sätze von Kategorien zu aktivieren oder zu deaktivieren. Instanzen werden mit der Methode trace_events.createTracing() erstellt.

Wenn es erstellt wird, ist das Tracing-Objekt deaktiviert. Das Aufrufen der Methode tracing.enable() fügt die Kategorien dem Satz der aktivierten Trace-Ereigniskategorien hinzu. Das Aufrufen von tracing.disable() entfernt die Kategorien aus dem Satz der aktivierten Trace-Ereigniskategorien.

tracing.categories

Hinzugefügt in: v10.0.0

• <string>

Eine durch Kommas getrennte Liste der Trace-Ereigniskategorien, die von diesem Tracing-Objekt abgedeckt werden.

tracing.disable()

Hinzugefügt in: v10.0.0

Deaktiviert dieses Tracing-Objekt.

Es werden nur Trace-Ereigniskategorien deaktiviert, die nicht von anderen aktivierten Tracing-Objekten abgedeckt werden und nicht durch das Flag --trace-event-categories angegeben werden.

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

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

t2.disable() // Deaktiviert nur die Ausgabe der Kategorie 'node.perf'

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

tracing.enable()

Hinzugefügt in: v10.0.0

Aktiviert dieses Tracing-Objekt für den Satz von Kategorien, die vom Tracing-Objekt abgedeckt werden.

tracing.enabled

Hinzugefügt in: v10.0.0

• <boolean> true, nur wenn das Tracing-Objekt aktiviert wurde.

trace_events.createTracing(options)

Hinzugefügt in: v10.0.0

• options <Object>

  • categories <string[]> Ein Array von Trace-Kategorienamen. Werte, die im Array enthalten sind, werden, wenn möglich, in einen String umgewandelt. Es wird ein Fehler ausgelöst, wenn der Wert nicht umgewandelt werden kann.

• Gibt zurück: <Tracing>.

Erstellt und gibt ein Tracing-Objekt für den angegebenen Satz von categories zurück.

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

trace_events.getEnabledCategories()

Hinzugefügt in: v10.0.0

• Gibt zurück: <string>

Gibt eine durch Kommas getrennte Liste aller aktuell aktivierten Trace-Ereigniskategorien zurück. Die aktuelle Menge der aktivierten Trace-Ereigniskategorien wird durch die Vereinigung aller aktuell aktivierten Tracing-Objekte und aller Kategorien bestimmt, die mit dem Flag --trace-event-categories aktiviert wurden.

Angenommen, die Datei test.js unten, der Befehl node --trace-event-categories node.perf test.js gibt 'node.async_hooks,node.perf' auf der Konsole aus.

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

Beispiele

Sammeln von Trace-Ereignisdaten mit dem Inspector

'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', () => {
    // fertig
  })
  const traceConfig = { includedCategories: ['v8'] }
  await post('NodeTracing.start', { traceConfig })
  // etwas tun
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect()
      console.log(data)
    })
  }, 1000)
}

collect()