Diagnosekanal

[Verlauf]

Version	Änderungen
v19.2.0, v18.13.0	`diagnostics_channel` ist jetzt stabil.
v15.1.0, v14.17.0	Hinzugefügt in: v15.1.0, v14.17.0

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/diagnostics_channel.js

Das Modul node:diagnostics_channel bietet eine API zum Erstellen benannter Kanäle, um beliebige Messagedaten zu Diagnosezwecken zu melden.

Es kann mit folgendem Zugriff werden:

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const diagnostics_channel = require('node:diagnostics_channel')

Es ist beabsichtigt, dass ein Modulschreiber, der Diagnosemessages melden möchte, einen oder mehrere Top-Level-Kanäle erstellt, um Messages über diese zu senden. Kanäle können auch zur Laufzeit abgerufen werden, dies wird jedoch aufgrund des zusätzlichen Aufwands nicht empfohlen. Kanäle können der Übersichtlichkeit halber exportiert werden, aber solange der Name bekannt ist, kann er überall abgerufen werden.

Wenn Ihr Modul Diagnosedaten für andere Benutzer erzeugen soll, wird empfohlen, eine Dokumentation der verwendeten benannten Kanäle sowie die Form der Messagedaten anzugeben. Kanalnamen sollten im Allgemeinen den Modulnamen enthalten, um Kollisionen mit Daten anderer Module zu vermeiden.

Öffentliche API

Übersicht

Im Folgenden finden Sie eine einfache Übersicht über die öffentliche API.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

// Erhalte ein wiederverwendbares Kanalobjekt
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Empfangene Daten
}

// Abonniere den Kanal
diagnostics_channel.subscribe('my-channel', onMessage)

// Überprüfe, ob der Kanal einen aktiven Abonnenten hat
if (channel.hasSubscribers) {
  // Veröffentliche Daten auf dem Kanal
  channel.publish({
    some: 'data',
  })
}

// Kündige das Abonnement des Kanals
diagnostics_channel.unsubscribe('my-channel', onMessage)

const diagnostics_channel = require('node:diagnostics_channel')

// Erhalte ein wiederverwendbares Kanalobjekt
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Empfangene Daten
}

// Abonniere den Kanal
diagnostics_channel.subscribe('my-channel', onMessage)

// Überprüfe, ob der Kanal einen aktiven Abonnenten hat
if (channel.hasSubscribers) {
  // Veröffentliche Daten auf dem Kanal
  channel.publish({
    some: 'data',
  })
}

// Kündige das Abonnement des Kanals
diagnostics_channel.unsubscribe('my-channel', onMessage)

`diagnostics_channel.hasSubscribers(name)`

Hinzugefügt in: v15.1.0, v14.17.0

name <string> | <symbol> Der Kanalname
Rückgabewert: <boolean> Ob aktive Abonnenten vorhanden sind

Überprüft, ob aktive Abonnenten für den benannten Kanal vorhanden sind. Dies ist hilfreich, wenn die zu sendende Nachricht teuer in der Vorbereitung sein könnte.

Diese API ist optional, aber hilfreich, wenn versucht wird, Nachrichten aus sehr leistungskritischen Code zu veröffentlichen.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Es gibt Abonnenten, Nachricht vorbereiten und veröffentlichen
}

const diagnostics_channel = require('node:diagnostics_channel')

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Es gibt Abonnenten, Nachricht vorbereiten und veröffentlichen
}

`diagnostics_channel.channel(name)`

Hinzugefügt in: v15.1.0, v14.17.0

name <string> | <symbol> Der Kanalname
Rückgabewert: <Channel> Das benannte Kanalojekt

Dies ist der primäre Einstiegspunkt für alle, die an einen benannten Kanal veröffentlichen möchten. Es erzeugt ein Kanalojekt, das optimiert ist, um den Overhead bei der Veröffentlichung so weit wie möglich zu reduzieren.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

`diagnostics_channel.subscribe(name, onMessage)`

Hinzugefügt in: v18.7.0, v16.17.0

name <string> | <symbol> Der Kanalname
onMessage <Function> Der Handler zum Empfangen von Kanalnachrichten
- message <any> Die Nachrichtendaten
- name <string> | <symbol> Der Name des Kanals

Registriert einen Nachrichtenhandler, um diesen Kanal zu abonnieren. Dieser Nachrichtenhandler wird synchron ausgeführt, wenn immer eine Nachricht an den Kanal veröffentlicht wird. Alle im Nachrichtenhandler ausgelösten Fehler lösen eine 'uncaughtException' aus.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Empfangene Daten
})

const diagnostics_channel = require('node:diagnostics_channel')

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Empfangene Daten
})

`diagnostics_channel.unsubscribe(name, onMessage)`

Hinzugefügt in: v18.7.0, v16.17.0

name <string> | <symbol> Der Kanalname
onMessage <Function> Der zuvor abonnierte Handler, der entfernt werden soll
Rückgabewert: <boolean> true, wenn der Handler gefunden wurde, andernfalls false.

Entfernt einen zuvor mit diagnostics_channel.subscribe(name, onMessage) an diesen Kanal angemeldeten Message-Handler.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

function onMessage(message, name) {
  // Empfangene Daten
}

diagnostics_channel.subscribe('my-channel', onMessage)

diagnostics_channel.unsubscribe('my-channel', onMessage)

const diagnostics_channel = require('node:diagnostics_channel')

function onMessage(message, name) {
  // Empfangene Daten
}

diagnostics_channel.subscribe('my-channel', onMessage)

diagnostics_channel.unsubscribe('my-channel', onMessage)

`diagnostics_channel.tracingChannel(nameOrChannels)`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

nameOrChannels <string> | <TracingChannel> Kanalname oder Objekt, das alle TracingChannel-Kanäle enthält
Rückgabewert: <TracingChannel> Sammlung von Kanälen, die verfolgt werden sollen

Erstellt einen TracingChannel-Wrapper für die angegebenen TracingChannel-Kanäle. Wenn ein Name angegeben wird, werden die entsprechenden Tracing-Kanäle in der Form tracing:${name}:${eventType} erstellt, wobei eventType den Typen der TracingChannel-Kanäle entspricht.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channelsByName = diagnostics_channel.tracingChannel('my-channel')

// oder...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
})

const diagnostics_channel = require('node:diagnostics_channel')

const channelsByName = diagnostics_channel.tracingChannel('my-channel')

// oder...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
})

Klasse: `Channel`

Hinzugefügt in: v15.1.0, v14.17.0

Die Klasse Channel repräsentiert einen einzelnen benannten Kanal innerhalb der Datenpipeline. Sie wird verwendet, um Abonnenten zu verfolgen und Nachrichten zu veröffentlichen, wenn Abonnenten vorhanden sind. Sie existiert als separates Objekt, um Kanal-Lookups zum Zeitpunkt der Veröffentlichung zu vermeiden, was sehr schnelle Veröffentlichungsgeschwindigkeiten ermöglicht und eine intensive Nutzung bei minimalen Kosten erlaubt. Kanäle werden mit diagnostics_channel.channel(name) erstellt. Die direkte Erstellung eines Kanals mit new Channel(name) wird nicht unterstützt.

`channel.hasSubscribers`

Hinzugefügt in: v15.1.0, v14.17.0

Rückgabewert: <boolean> Gibt an, ob aktive Abonnenten vorhanden sind

Überprüft, ob aktive Abonnenten für diesen Kanal vorhanden sind. Dies ist hilfreich, wenn die zu sendende Nachricht teuer in der Vorbereitung sein könnte.

Diese API ist optional, aber hilfreich, wenn versucht wird, Nachrichten aus sehr leistungskritischen Codes zu veröffentlichen.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

if (channel.hasSubscribers) {
  // Es gibt Abonnenten, Nachricht vorbereiten und veröffentlichen
}

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

if (channel.hasSubscribers) {
  // Es gibt Abonnenten, Nachricht vorbereiten und veröffentlichen
}

`channel.publish(message)`

Hinzugefügt in: v15.1.0, v14.17.0

message <any> Die an die Kanalabonnenten zu sendende Nachricht

Veröffentlicht eine Nachricht an alle Abonnenten des Kanals. Dies löst Nachrichtenhandler synchron aus, sodass sie innerhalb desselben Kontexts ausgeführt werden.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

channel.publish({
  some: 'message',
})

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

channel.publish({
  some: 'message',
})

`channel.subscribe(onMessage)`

Hinzugefügt in: v15.1.0, v14.17.0

Veraltet seit: v18.7.0, v16.17.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie diagnostics_channel.subscribe(name, onMessage)

onMessage <Funktion> Der Handler zum Empfangen von Kanalnachrichten
- message <beliebig> Die Nachrichtendaten
- name <string> | <symbol> Der Name des Kanals

Registriert einen Nachrichtenhandler, um diesen Kanal zu abonnieren. Dieser Nachrichtenhandler wird synchron ausgeführt, sobald eine Nachricht an den Kanal gesendet wird. Alle im Nachrichtenhandler ausgelösten Fehler lösen eine 'uncaughtException' aus.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

channel.subscribe((message, name) => {
  // Empfangene Daten
})

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

channel.subscribe((message, name) => {
  // Empfangene Daten
})

`channel.unsubscribe(onMessage)`

[Verlauf]

Version	Änderungen
v18.7.0, v16.17.0	Veraltet seit: v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0	Rückgabewert hinzugefügt. Zu Kanälen ohne Abonnenten hinzugefügt.
v15.1.0, v14.17.0	Hinzugefügt in: v15.1.0, v14.17.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie diagnostics_channel.unsubscribe(name, onMessage)

onMessage <Funktion> Der zuvor abonnierte Handler, der entfernt werden soll
Rückgabewert: <boolean> true, wenn der Handler gefunden wurde, andernfalls false.

Entfernt einen zuvor mit channel.subscribe(onMessage) an diesen Kanal registrierten Nachrichtenhandler.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Empfangene Daten
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Empfangene Daten
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

`channel.bindStore(store[, transform])`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

store <AsyncLocalStorage> Der Store, an den die Kontextdaten gebunden werden sollen
transform <Function> Transformiert Kontextdaten, bevor der Store-Kontext gesetzt wird

Wenn channel.runStores(context, ...) aufgerufen wird, werden die angegebenen Kontextdaten auf jeden an den Kanal gebundenen Store angewendet. Wenn der Store bereits gebunden wurde, wird die vorherige transform-Funktion durch die neue ersetzt. Die transform-Funktion kann weggelassen werden, um die angegebenen Kontextdaten direkt als Kontext zu setzen.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, data => {
  return { data }
})

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, data => {
  return { data }
})

`channel.unbindStore(store)`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

store <AsyncLocalStorage> Der Store, der vom Kanal getrennt werden soll.
Rückgabewert: <boolean> true, wenn der Store gefunden wurde, andernfalls false.

Entfernt einen Message Handler, der zuvor mit channel.bindStore(store) an diesem Kanal registriert wurde.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store)
channel.unbindStore(store)

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store)
channel.unbindStore(store)

`channel.runStores(context, fn[, thisArg[, ...args]])`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

context <any> Nachricht an Abonnenten zu senden und an Stores zu binden
fn <Function> Handler, der innerhalb des eingegebenen Speicherkontexts ausgeführt wird
thisArg <any> Der Empfänger, der für den Funktionsaufruf verwendet werden soll.
...args <any> Optionale Argumente, die an die Funktion übergeben werden sollen.

Wendet die gegebenen Daten auf alle an den Kanal gebundenen AsyncLocalStorage-Instanzen für die Dauer der gegebenen Funktion an und veröffentlicht dann an den Kanal, innerhalb dessen Umfang die Daten auf die Stores angewendet werden.

Wenn eine Transformationsfunktion an channel.bindStore(store) übergeben wurde, wird sie angewendet, um die Nachrichten Daten zu transformieren, bevor sie zum Kontextwert für den Store wird. Der vorherige Speicherkontext ist innerhalb der Transformationsfunktion zugänglich, wenn Kontextverknüpfungen erforderlich sind.

Der auf den Store angewendete Kontext sollte in jedem asynchronen Code zugänglich sein, der aus der Ausführung fortgesetzt wird, die während der gegebenen Funktion begonnen hat. Es gibt jedoch einige Situationen, in denen Kontextverlust auftreten kann.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, message => {
  const parent = store.getStore()
  return new Span(message, parent)
})
channel.runStores({ some: 'message' }, () => {
  store.getStore() // Span({ some: 'message' })
})

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const store = new AsyncLocalStorage()

const channel = diagnostics_channel.channel('my-channel')

channel.bindStore(store, message => {
  const parent = store.getStore()
  return new Span(message, parent)
})
channel.runStores({ some: 'message' }, () => {
  store.getStore() // Span({ some: 'message' })
})

Klasse: `TracingChannel`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Die Klasse TracingChannel ist eine Sammlung von TracingChannel-Kanälen, die zusammen eine einzelne verfolgbare Aktion ausdrücken. Sie wird verwendet, um den Prozess der Erzeugung von Ereignissen zur Verfolgung des Anwendungsflusses zu formalisieren und zu vereinfachen. diagnostics_channel.tracingChannel() wird verwendet, um einen TracingChannel zu konstruieren. Wie bei Channel wird empfohlen, einen einzelnen TracingChannel auf der obersten Ebene der Datei zu erstellen und wiederzuverwenden, anstatt sie dynamisch zu erstellen.

`tracingChannel.subscribe(subscribers)`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

subscribers <Objekt> Menge der TracingChannel-Kanal Abonnenten
- start <Funktion> Der start-Ereignis Abonnent
- end <Funktion> Der end-Ereignis Abonnent
- asyncStart <Funktion> Der asyncStart-Ereignis Abonnent
- asyncEnd <Funktion> Der asyncEnd-Ereignis Abonnent
- error <Funktion> Der error-Ereignis Abonnent

Hilfsprogramm zum Abonnieren einer Sammlung von Funktionen für die entsprechenden Kanäle. Dies ist dasselbe wie der Aufruf von channel.subscribe(onMessage) für jeden Kanal einzeln.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.subscribe({
  start(message) {
    // Start-Nachricht verarbeiten
  },
  end(message) {
    // End-Nachricht verarbeiten
  },
  asyncStart(message) {
    // asyncStart-Nachricht verarbeiten
  },
  asyncEnd(message) {
    // asyncEnd-Nachricht verarbeiten
  },
  error(message) {
    // Fehlermeldung verarbeiten
  },
})

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.subscribe({
  start(message) {
    // Start-Nachricht verarbeiten
  },
  end(message) {
    // End-Nachricht verarbeiten
  },
  asyncStart(message) {
    // asyncStart-Nachricht verarbeiten
  },
  asyncEnd(message) {
    // asyncEnd-Nachricht verarbeiten
  },
  error(message) {
    // Fehlermeldung verarbeiten
  },
})

`tracingChannel.unsubscribe(subscribers)`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

subscribers <Objekt> Menge der TracingChannel-Kanäle Abonnenten
- start <Funktion> Der start-Ereignis Abonnent
- end <Funktion> Der end-Ereignis Abonnent
- asyncStart <Funktion> Der asyncStart-Ereignis Abonnent
- asyncEnd <Funktion> Der asyncEnd-Ereignis Abonnent
- error <Funktion> Der error-Ereignis Abonnent
Gibt zurück: <boolean> true, wenn alle Handler erfolgreich abgemeldet wurden, andernfalls false.

Hilfsprogramm zum Abmelden einer Sammlung von Funktionen von den entsprechenden Kanälen. Dies entspricht dem Aufruf von channel.unsubscribe(onMessage) für jeden Kanal einzeln.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.unsubscribe({
  start(message) {
    // Start-Nachricht verarbeiten
  },
  end(message) {
    // End-Nachricht verarbeiten
  },
  asyncStart(message) {
    // asyncStart-Nachricht verarbeiten
  },
  asyncEnd(message) {
    // asyncEnd-Nachricht verarbeiten
  },
  error(message) {
    // Fehlermeldung verarbeiten
  },
})

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.unsubscribe({
  start(message) {
    // Start-Nachricht verarbeiten
  },
  end(message) {
    // End-Nachricht verarbeiten
  },
  asyncStart(message) {
    // asyncStart-Nachricht verarbeiten
  },
  asyncEnd(message) {
    // asyncEnd-Nachricht verarbeiten
  },
  error(message) {
    // Fehlermeldung verarbeiten
  },
})

`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

fn <Funktion> Funktion, um einen Trace einzubetten
context <Objekt> Geteiltes Objekt zur Korrelation von Ereignissen
thisArg <beliebig> Der Empfänger, der für den Funktionsaufruf verwendet werden soll
...args <beliebig> Optionale Argumente, die an die Funktion übergeben werden sollen
Rückgabewert: <beliebig> Der Rückgabewert der gegebenen Funktion

Traciert einen synchronen Funktionsaufruf. Dies erzeugt immer ein start-Ereignis und ein end-Ereignis um die Ausführung herum und kann ein error-Ereignis erzeugen, wenn die gegebene Funktion einen Fehler auslöst. Dies führt die gegebene Funktion mit channel.runStores(context, ...) auf dem start-Kanal aus, wodurch sichergestellt wird, dass alle Ereignisse über alle gebundenen Stores verfügen, die diesem Trace-Kontext entsprechen.

Um sicherzustellen, dass nur korrekte Trace-Graphen gebildet werden, werden Ereignisse nur veröffentlicht, wenn Abonnenten vor dem Start des Traces vorhanden sind. Abonnements, die nach Beginn des Traces hinzugefügt werden, erhalten keine zukünftigen Ereignisse aus diesem Trace, sondern nur zukünftige Traces werden angezeigt.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceSync(
  () => {
    // Etwas tun
  },
  {
    some: 'thing',
  }
)

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceSync(
  () => {
    // Etwas tun
  },
  {
    some: 'thing',
  }
)

`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

fn <Function> Promise-zurückgebende Funktion, um einen Trace herumzulegen
context <Object> Geteiltes Objekt zur Korrelation von Trace-Ereignissen
thisArg <any> Der Empfänger, der für den Funktionsaufruf verwendet werden soll
...args <any> Optionale Argumente, die an die Funktion übergeben werden sollen
Rückgabewert: <Promise> Verkettet aus dem Promise, das von der gegebenen Funktion zurückgegeben wird

Verfolgen Sie einen Aufruf einer Promise-zurückgebenden Funktion. Dies erzeugt immer ein start-Ereignis und ein end-Ereignis um den synchronen Teil der Funktionsausführung herum und erzeugt ein asyncStart-Ereignis und ein asyncEnd-Ereignis, wenn eine Promise-Fortsetzung erreicht wird. Es kann auch ein error-Ereignis erzeugen, wenn die gegebene Funktion einen Fehler auslöst oder das zurückgegebene Promise zurückgewiesen wird. Dies führt die gegebene Funktion mit channel.runStores(context, ...) auf dem start-Kanal aus, wodurch sichergestellt wird, dass alle Ereignisse über alle gebundenen Stores verfügen, die so eingestellt sind, dass sie diesem Trace-Kontext entsprechen.

Um sicherzustellen, dass nur korrekte Trace-Graphen gebildet werden, werden Ereignisse nur veröffentlicht, wenn Abonnenten vor dem Start des Trace vorhanden sind. Abonnements, die nach Beginn des Trace hinzugefügt werden, erhalten keine zukünftigen Ereignisse aus diesem Trace, sondern nur zukünftige Traces werden angezeigt.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.tracePromise(
  async () => {
    // Etwas tun
  },
  {
    some: 'thing',
  }
)

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.tracePromise(
  async () => {
    // Etwas tun
  },
  {
    some: 'thing',
  }
)

`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`

Hinzugefügt in: v19.9.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

fn <Function> Rückruffunktion zum Einbetten eines Traces
position <number> Nullbasierte Argumentposition der erwarteten Rückruffunktion (standardmäßig das letzte Argument, wenn undefined übergeben wird)
context <Object> Geteiltes Objekt zur Korrelation von Trace-Ereignissen (standardmäßig {}, wenn undefined übergeben wird)
thisArg <any> Der Empfänger, der für den Funktionsaufruf verwendet werden soll
...args <any> Argumente, die an die Funktion übergeben werden sollen (müssen den Rückruf enthalten)
Rückgabewert: <any> Der Rückgabewert der gegebenen Funktion

Trace einen Funktionsaufruf, der eine Rückruffunktion empfängt. Es wird erwartet, dass die Rückruffunktion der Fehler-als-erstes-Argument-Konvention folgt, die üblicherweise verwendet wird. Dies erzeugt immer ein start-Ereignis und ein end-Ereignis um den synchronen Teil der Funktionsausführung und erzeugt ein asyncStart-Ereignis und ein asyncEnd-Ereignis um die Rückruf-Ausführung. Es kann auch ein error-Ereignis erzeugen, wenn die gegebene Funktion eine Ausnahme auslöst oder das erste an die Rückruffunktion übergebene Argument gesetzt ist. Dies führt die gegebene Funktion mit channel.runStores(context, ...) auf dem start-Kanal aus, was sicherstellt, dass alle Ereignisse über alle gebundenen Stores verfügen, die so eingestellt sind, dass sie diesem Trace-Kontext entsprechen.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceCallback(
  (arg1, callback) => {
    // Etwas tun
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

channels.traceCallback(
  (arg1, callback) => {
    // Etwas tun
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

Die Rückruffunktion wird auch mit channel.runStores(context, ...) ausgeführt, was in einigen Fällen die Wiederherstellung von Kontextverlusten ermöglicht.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'
import { AsyncLocalStorage } from 'node:async_hooks'

const channels = diagnostics_channel.tracingChannel('my-channel')
const myStore = new AsyncLocalStorage()

// Der Startkanal setzt die anfänglichen Store-Daten auf etwas
// und speichert diesen Store-Datenwert im Trace-Kontextobjekt
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Dann kann asyncStart aus diesen zuvor gespeicherten Daten wiederherstellen
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const channels = diagnostics_channel.tracingChannel('my-channel')
const myStore = new AsyncLocalStorage()

// Der Startkanal setzt die anfänglichen Store-Daten auf etwas
// und speichert diesen Store-Datenwert im Trace-Kontextobjekt
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Dann kann asyncStart aus diesen zuvor gespeicherten Daten wiederherstellen
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

`tracingChannel.hasSubscribers`

Hinzugefügt in: v22.0.0, v20.13.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Rückgabewert: <boolean> true, wenn einer der einzelnen Kanäle einen Subscriber hat, false andernfalls.

Dies ist eine Hilfsmethode, die in einer TracingChannel-Instanz verfügbar ist, um zu überprüfen, ob einer der TracingChannel-Kanäle Subscriber hat. true wird zurückgegeben, wenn mindestens einer von ihnen mindestens einen Subscriber hat, andernfalls false.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

const channels = diagnostics_channel.tracingChannel('my-channel')

if (channels.hasSubscribers) {
  // Etwas tun
}

const diagnostics_channel = require('node:diagnostics_channel')

const channels = diagnostics_channel.tracingChannel('my-channel')

if (channels.hasSubscribers) {
  // Etwas tun
}

TracingChannel-Kanäle

Ein TracingChannel ist eine Sammlung mehrerer diagnostics_channels, die spezifische Punkte im Ausführungslebenszyklus einer einzelnen verfolgbaren Aktion darstellen. Das Verhalten ist in fünf diagnostics_channels aufgeteilt, bestehend aus start, end, asyncStart, asyncEnd und error. Eine einzelne verfolgbare Aktion teilt das gleiche Ereignisobjekt zwischen allen Ereignissen, was hilfreich für die Verwaltung der Korrelation über eine WeakMap sein kann.

Diese Ereignisobjekte werden mit result- oder error-Werten erweitert, wenn die Aufgabe "abgeschlossen" ist. Bei einer synchronen Aufgabe ist result der Rückgabewert und error alles, was von der Funktion ausgelöst wird. Bei asynchronen Funktionen auf Callback-Basis ist result das zweite Argument des Callbacks, während error entweder ein ausgelöster Fehler ist, der im end-Ereignis sichtbar ist, oder das erste Callback-Argument in einem der asyncStart- oder asyncEnd-Ereignisse.

Um sicherzustellen, dass nur korrekte Trace-Graphen gebildet werden, sollten Ereignisse nur veröffentlicht werden, wenn Subscriber vorhanden sind, bevor der Trace gestartet wird. Abonnements, die nach Beginn des Traces hinzugefügt werden, sollten keine zukünftigen Ereignisse von diesem Trace erhalten, nur zukünftige Traces werden angezeigt.

Tracing-Kanäle sollten einem Benennungsmuster folgen:

tracing:module.class.method:start oder tracing:module.function:start
tracing:module.class.method:end oder tracing:module.function:end
tracing:module.class.method:asyncStart oder tracing:module.function:asyncStart
tracing:module.class.method:asyncEnd oder tracing:module.function:asyncEnd
tracing:module.class.method:error oder tracing:module.function:error

`start(event)`

Name: tracing:${name}:start

Das start-Ereignis repräsentiert den Zeitpunkt, an dem eine Funktion aufgerufen wird. Zu diesem Zeitpunkt können die Ereignisdaten Funktionsargumente oder alles andere enthalten, was zu Beginn der Ausführung der Funktion verfügbar ist.

`end(event)`

Name: tracing:${name}:end

Das end-Ereignis repräsentiert den Zeitpunkt, an dem ein Funktionsaufruf einen Wert zurückgibt. Bei einer asynchronen Funktion ist dies der Zeitpunkt, an dem das zurückgegebene Promise abgeschlossen wird, nicht der Zeitpunkt, an dem die Funktion selbst intern eine Return-Anweisung ausführt. Zu diesem Zeitpunkt wird, falls die verfolgte Funktion synchron war, das Feld result auf den Rückgabewert der Funktion gesetzt. Alternativ kann das Feld error vorhanden sein, um alle ausgelösten Fehler darzustellen.

Es wird empfohlen, speziell auf das error-Ereignis zu hören, um Fehler zu verfolgen, da es möglich ist, dass eine verfolgbare Aktion mehrere Fehler erzeugt. Beispielsweise kann eine asynchrone Aufgabe, die fehlschlägt, intern gestartet werden, bevor der synchrone Teil der Aufgabe einen Fehler auslöst.

`asyncStart(event)`

Name: tracing:${name}:asyncStart

Das asyncStart-Ereignis repräsentiert das Erreichen des Callbacks oder der Fortsetzung einer verfolgbaren Funktion. Zu diesem Zeitpunkt können Dinge wie Callback-Argumente verfügbar sein oder alles andere, das das "Ergebnis" der Aktion ausdrückt.

Bei callback-basierten Funktionen wird das erste Argument des Callbacks dem Feld error zugewiesen, falls es nicht undefined oder null ist, und das zweite Argument wird dem Feld result zugewiesen.

Bei Promises wird das Argument zum resolve-Pfad result zugewiesen oder das Argument zum reject-Pfad wird error zugewiesen.

`asyncEnd(event)`

Name: tracing:${name}:asyncEnd

Das asyncEnd-Ereignis repräsentiert die Rückgabe des Callbacks einer asynchronen Funktion. Es ist unwahrscheinlich, dass sich die Ereignisdaten nach dem asyncStart-Ereignis ändern, es kann jedoch nützlich sein, den Punkt zu sehen, an dem der Callback abgeschlossen wird.

`error(event)`

Name: tracing:${name}:error

Das error-Ereignis repräsentiert jeden Fehler, der von der verfolgbaren Funktion synchron oder asynchron erzeugt wird. Wenn ein Fehler im synchronen Teil der verfolgten Funktion ausgelöst wird, wird der Fehler dem error-Feld des Ereignisses zugewiesen und das error-Ereignis wird ausgelöst. Wenn ein Fehler asynchron über einen Callback oder eine Promise-Ablehnung empfangen wird, wird er ebenfalls dem error-Feld des Ereignisses zugewiesen und löst das error-Ereignis aus.

Es ist möglich, dass ein einziger Aufruf einer verfolgbaren Funktion mehrere Male Fehler erzeugt. Dies sollte bei der Verarbeitung dieses Ereignisses berücksichtigt werden. Wenn beispielsweise eine andere asynchrone Aufgabe intern ausgelöst wird, die fehlschlägt, und dann der synchrone Teil der Funktion einen Fehler auslöst, werden zwei error-Ereignisse emittiert, eines für den synchronen Fehler und eines für den asynchronen Fehler.

Integrierte Kanäle

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Während die diagnostics_channel-API jetzt als stabil gilt, sind die derzeit verfügbaren integrierten Kanäle dies nicht. Jeder Kanal muss unabhängig deklariert werden.

HTTP

http.client.request.created

request <http.ClientRequest>

Wird emittiert, wenn ein Client ein Request-Objekt erstellt. Im Gegensatz zu http.client.request.start wird dieses Ereignis emittiert, bevor die Anfrage gesendet wurde.

http.client.request.start

request <http.ClientRequest>

Wird emittiert, wenn ein Client eine Anfrage startet.

http.client.request.error

request <http.ClientRequest>
error <Error>

Wird emittiert, wenn während einer Client-Anfrage ein Fehler auftritt.

http.client.response.finish

request <http.ClientRequest>
response <http.IncomingMessage>

Wird emittiert, wenn ein Client eine Antwort empfängt.

http.server.request.start

Wird emittiert, wenn der Server eine Anfrage empfängt.

http.server.response.created

request <http.IncomingMessage>
response <http.ServerResponse>

Wird emittiert, wenn der Server eine Antwort erstellt. Das Ereignis wird emittiert, bevor die Antwort gesendet wird.

http.server.response.finish

Wird emittiert, wenn der Server eine Antwort sendet.

Module

module.require.start

event <Objekt> mit folgenden Eigenschaften:
- id - An require() übergebenes Argument. Modulname.
- parentFilename - Name des Moduls, das versucht hat, require(id) aufzurufen.

Ausgegeben, wenn require() ausgeführt wird. Siehe start-Ereignis.

module.require.end

event <Objekt> mit folgenden Eigenschaften:
- id - An require() übergebenes Argument. Modulname.
- parentFilename - Name des Moduls, das versucht hat, require(id) aufzurufen.

Ausgegeben, wenn ein require()-Aufruf zurückkehrt. Siehe end-Ereignis.

module.require.error

event <Objekt> mit folgenden Eigenschaften:
- id - An require() übergebenes Argument. Modulname.
- parentFilename - Name des Moduls, das versucht hat, require(id) aufzurufen.
error <Error>

Ausgegeben, wenn require() einen Fehler auslöst. Siehe error-Ereignis.

module.import.asyncStart

event <Objekt> mit folgenden Eigenschaften:
- id - An import() übergebenes Argument. Modulname.
- parentURL - URL-Objekt des Moduls, das versucht hat, import(id) aufzurufen.

Ausgegeben, wenn import() aufgerufen wird. Siehe asyncStart-Ereignis.

module.import.asyncEnd

event <Objekt> mit folgenden Eigenschaften:
- id - An import() übergebenes Argument. Modulname.
- parentURL - URL-Objekt des Moduls, das versucht hat, import(id) aufzurufen.

Ausgegeben, wenn import() abgeschlossen ist. Siehe asyncEnd-Ereignis.

module.import.error

event <Objekt> mit folgenden Eigenschaften:
- id - An import() übergebenes Argument. Modulname.
- parentURL - URL-Objekt des Moduls, das versucht hat, import(id) aufzurufen.
error <Error>

Ausgegeben, wenn import() einen Fehler auslöst. Siehe error-Ereignis.

NET

net.client.socket

socket <net.Socket>

Wird ausgelöst, wenn eine neue TCP- oder Pipe-Client-Socket erstellt wird.

net.server.socket

socket <net.Socket>

Wird ausgelöst, wenn eine neue TCP- oder Pipe-Verbindung empfangen wird.

tracing:net.server.listen:asyncStart

server <net.Server>
options <Object>

Wird ausgelöst, wenn net.Server.listen() aufgerufen wird, bevor der Port oder die Pipe tatsächlich eingerichtet ist.

tracing:net.server.listen:asyncEnd

server <net.Server>

Wird ausgelöst, wenn net.Server.listen() abgeschlossen ist und der Server somit bereit ist, Verbindungen anzunehmen.

tracing:net.server.listen:error

server <net.Server>
error <Error>

Wird ausgelöst, wenn net.Server.listen() einen Fehler zurückgibt.

UDP

udp.socket

socket <dgram.Socket>

Wird ausgelöst, wenn eine neue UDP-Socket erstellt wird.

Prozess

Hinzugefügt in: v16.18.0

child_process

process <ChildProcess>

Wird ausgelöst, wenn ein neuer Prozess erstellt wird.

Worker-Thread

Hinzugefügt in: v16.18.0

worker_threads

worker Worker

Wird ausgelöst, wenn ein neuer Thread erstellt wird.

Diagnosekanal ​

Öffentliche API ​

Übersicht ​

diagnostics_channel.hasSubscribers(name) ​

diagnostics_channel.channel(name) ​

diagnostics_channel.subscribe(name, onMessage) ​

diagnostics_channel.unsubscribe(name, onMessage) ​

diagnostics_channel.tracingChannel(nameOrChannels) ​

Klasse: Channel ​

channel.hasSubscribers ​

channel.publish(message) ​

channel.subscribe(onMessage) ​

channel.unsubscribe(onMessage) ​

channel.bindStore(store[, transform]) ​

channel.unbindStore(store) ​

channel.runStores(context, fn[, thisArg[, ...args]]) ​

Klasse: TracingChannel ​

tracingChannel.subscribe(subscribers) ​

tracingChannel.unsubscribe(subscribers) ​

tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]]) ​

tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]]) ​

tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]]) ​

tracingChannel.hasSubscribers ​

TracingChannel-Kanäle ​

start(event) ​

end(event) ​

asyncStart(event) ​

asyncEnd(event) ​

error(event) ​

Integrierte Kanäle ​

HTTP ​

Module ​

NET ​

UDP ​

Prozess ​

Worker-Thread ​

Diagnosekanal

Öffentliche API

Übersicht

`diagnostics_channel.hasSubscribers(name)`

`diagnostics_channel.channel(name)`

`diagnostics_channel.subscribe(name, onMessage)`

`diagnostics_channel.unsubscribe(name, onMessage)`

`diagnostics_channel.tracingChannel(nameOrChannels)`

Klasse: `Channel`

`channel.hasSubscribers`

`channel.publish(message)`

`channel.subscribe(onMessage)`

`channel.unsubscribe(onMessage)`

`channel.bindStore(store[, transform])`

`channel.unbindStore(store)`

`channel.runStores(context, fn[, thisArg[, ...args]])`

Klasse: `TracingChannel`

`tracingChannel.subscribe(subscribers)`

`tracingChannel.unsubscribe(subscribers)`

`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`

`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`

`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`

`tracingChannel.hasSubscribers`

TracingChannel-Kanäle

`start(event)`

`end(event)`

`asyncStart(event)`

`asyncEnd(event)`

`error(event)`

Integrierte Kanäle

HTTP

Module

NET

UDP

Prozess

Worker-Thread