iDoc.dev

Français

English
简体中文
Español
Português
Deutsch
Italiano
日本語
한국어
Русский
العربية

Français

English
简体中文
Español
Português
Deutsch
Italiano
日本語
한국어
Русский
العربية

Thème

Canal de diagnostics ​

[Historique]

VersionChangements
v19.2.0, v18.13.0diagnostics_channel est maintenant Stable.
v15.1.0, v14.17.0Ajouté dans : v15.1.0, v14.17.0

[Stable: 2 - Stable]

Stable: 2 Stabilité: 2 - Stable

Code Source : lib/diagnostics_channel.js

Le module node:diagnostics_channel fournit une API pour créer des canaux nommés afin de signaler des données de message arbitraires à des fins de diagnostic.

Il est accessible en utilisant :

js
import diagnostics_channel from 'node:diagnostics_channel'
js
const diagnostics_channel = require('node:diagnostics_channel')

Il est prévu qu’un auteur de module souhaitant signaler des messages de diagnostic crée un ou plusieurs canaux de niveau supérieur pour signaler les messages. Les canaux peuvent également être acquis au moment de l’exécution, mais cela n’est pas encouragé en raison de la surcharge supplémentaire que cela implique. Les canaux peuvent être exportés par commodité, mais tant que le nom est connu, il peut être acquis n’importe où.

Si vous avez l’intention que votre module produise des données de diagnostic que d’autres peuvent utiliser, il est recommandé d’inclure une documentation sur les canaux nommés qui sont utilisés ainsi que sur la forme des données du message. Les noms de canal doivent généralement inclure le nom du module afin d’éviter les collisions avec les données provenant d’autres modules.

API publique ​

Vue d’ensemble ​

Voici un simple aperçu de l’API publique.

js
import diagnostics_channel from 'node:diagnostics_channel'

// Obtenir un objet de canal réutilisable
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Données reçues
}

// S’abonner au canal
diagnostics_channel.subscribe('my-channel', onMessage)

// Vérifier si le canal a un abonné actif
if (channel.hasSubscribers) {
  // Publier des données sur le canal
  channel.publish({
    some: 'data',
  })
}

// Se désabonner du canal
diagnostics_channel.unsubscribe('my-channel', onMessage)
js
const diagnostics_channel = require('node:diagnostics_channel')

// Obtenir un objet de canal réutilisable
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Données reçues
}

// S’abonner au canal
diagnostics_channel.subscribe('my-channel', onMessage)

// Vérifier si le canal a un abonné actif
if (channel.hasSubscribers) {
  // Publier des données sur le canal
  channel.publish({
    some: 'data',
  })
}

// Se désabonner du canal
diagnostics_channel.unsubscribe('my-channel', onMessage)

diagnostics_channel.hasSubscribers(name) ​

Ajouté dans : v15.1.0, v14.17.0

Vérifie s’il existe des abonnés actifs au canal nommé. Ceci est utile si le message que vous souhaitez envoyer peut être coûteux à préparer.

Cette API est facultative, mais utile lorsque vous essayez de publier des messages à partir d’un code très sensible aux performances.

js
import diagnostics_channel from 'node:diagnostics_channel'

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Il y a des abonnés, préparer et publier le message
}
js
const diagnostics_channel = require('node:diagnostics_channel')

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Il y a des abonnés, préparer et publier le message
}

diagnostics_channel.channel(name) ​

Ajouté dans : v15.1.0, v14.17.0

Il s’agit du principal point d’entrée pour quiconque souhaite publier sur un canal nommé. Il produit un objet de canal optimisé pour réduire autant que possible la surcharge au moment de la publication.

js
import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('my-channel')
js
const diagnostics_channel = require('node:diagnostics_channel')

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

diagnostics_channel.subscribe(name, onMessage) ​

Ajouté dans : v18.7.0, v16.17.0

Enregistre un gestionnaire de messages pour s’abonner à ce canal. Ce gestionnaire de messages sera exécuté de manière synchrone chaque fois qu’un message sera publié sur le canal. Toute erreur levée dans le gestionnaire de messages déclenchera un 'uncaughtException'.

js
import diagnostics_channel from 'node:diagnostics_channel'

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Données reçues
})
js
const diagnostics_channel = require('node:diagnostics_channel')

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Données reçues
})

diagnostics_channel.unsubscribe(name, onMessage) ​

Ajouté dans : v18.7.0, v16.17.0

  • name <string> | <symbol> Le nom du canal
  • onMessage <Function> Le gestionnaire précédemment abonné à supprimer
  • Retourne : <boolean> true si le gestionnaire a été trouvé, false sinon.

Supprime un gestionnaire de messages précédemment enregistré auprès de ce canal avec diagnostics_channel.subscribe(name, onMessage).

js
import diagnostics_channel from 'node:diagnostics_channel'

function onMessage(message, name) {
  // Données reçues
}

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

diagnostics_channel.unsubscribe('my-channel', onMessage)
js
const diagnostics_channel = require('node:diagnostics_channel')

function onMessage(message, name) {
  // Données reçues
}

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

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

diagnostics_channel.tracingChannel(nameOrChannels) ​

Ajouté dans : v19.9.0, v18.19.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Crée un wrapper TracingChannel pour les Canaux TracingChannel donnés. Si un nom est donné, les canaux de suivi correspondants seront créés sous la forme tracing:${name}:${eventType} où eventType correspond aux types de Canaux TracingChannel.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

// ou...

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'),
})
js
const diagnostics_channel = require('node:diagnostics_channel')

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

// ou...

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'),
})

Classe : Channel ​

Ajouté dans : v15.1.0, v14.17.0

La classe Channel représente un canal nommé individuel au sein du pipeline de données. Elle est utilisée pour suivre les abonnés et publier des messages lorsqu’il y a des abonnés présents. Elle existe en tant qu’objet séparé pour éviter les recherches de canaux au moment de la publication, ce qui permet des vitesses de publication très rapides et une utilisation intensive tout en engendrant un coût très minime. Les canaux sont créés avec diagnostics_channel.channel(name), la construction d’un canal directement avec new Channel(name) n’est pas prise en charge.

channel.hasSubscribers ​

Ajouté dans : v15.1.0, v14.17.0

  • Retourne : <boolean> Si des abonnés sont actifs

Vérifie s’il existe des abonnés actifs à ce canal. Ceci est utile si le message que vous souhaitez envoyer peut être coûteux à préparer.

Cette API est facultative, mais utile lorsque vous essayez de publier des messages à partir de code très sensible aux performances.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

if (channel.hasSubscribers) {
  // Il y a des abonnés, préparer et publier le message
}
js
const diagnostics_channel = require('node:diagnostics_channel')

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

if (channel.hasSubscribers) {
  // Il y a des abonnés, préparer et publier le message
}

channel.publish(message) ​

Ajouté dans : v15.1.0, v14.17.0

  • message <any> Le message à envoyer aux abonnés du canal

Publie un message à tous les abonnés du canal. Cela déclenchera les gestionnaires de messages de manière synchrone, de sorte qu’ils s’exécuteront dans le même contexte.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channel.publish({
  some: 'message',
})
js
const diagnostics_channel = require('node:diagnostics_channel')

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

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

channel.subscribe(onMessage) ​

Ajouté dans : v15.1.0, v14.17.0

Déprécié depuis : v18.7.0, v16.17.0

[Stable : 0 - Déprécié]

Stable : 0 Stabilité : 0 - Déprécié : Utilisez diagnostics_channel.subscribe(name, onMessage)

Enregistre un gestionnaire de messages pour s’abonner à ce canal. Ce gestionnaire de messages sera exécuté de manière synchrone chaque fois qu’un message est publié sur le canal. Toute erreur levée dans le gestionnaire de messages déclenchera un événement 'uncaughtException'.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channel.subscribe((message, name) => {
  // Données reçues
})
js
const diagnostics_channel = require('node:diagnostics_channel')

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

channel.subscribe((message, name) => {
  // Données reçues
})

channel.unsubscribe(onMessage) ​

[Historique]

VersionModifications
v18.7.0, v16.17.0Déprécié depuis : v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0Valeur de retour ajoutée. Ajouté aux canaux sans abonnés.
v15.1.0, v14.17.0Ajouté dans : v15.1.0, v14.17.0

[Stable : 0 - Déprécié]

Stable : 0 Stabilité : 0 - Déprécié : Utilisez diagnostics_channel.unsubscribe(name, onMessage)

  • onMessage <Function> Le gestionnaire précédemment abonné à supprimer
  • Retourne : <boolean> true si le gestionnaire a été trouvé, false sinon.

Supprime un gestionnaire de messages précédemment enregistré auprès de ce canal avec channel.subscribe(onMessage).

js
import diagnostics_channel from 'node:diagnostics_channel'

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

function onMessage(message, name) {
  // Données reçues
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)
js
const diagnostics_channel = require('node:diagnostics_channel')

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

function onMessage(message, name) {
  // Données reçues
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

channel.bindStore(store[, transform]) ​

Ajouté dans : v19.9.0, v18.19.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

  • store <AsyncLocalStorage> Le store auquel lier les données de contexte
  • transform <Function> Transforme les données de contexte avant de définir le contexte du store

Lorsque channel.runStores(context, ...) est appelé, les données de contexte données seront appliquées à tout store lié au canal. Si le store a déjà été lié, la fonction transform précédente sera remplacée par la nouvelle. La fonction transform peut être omise pour définir directement les données de contexte données comme contexte.

js
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 }
})
js
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) ​

Ajouté dans : v19.9.0, v18.19.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Supprime un gestionnaire de messages précédemment enregistré sur ce canal avec channel.bindStore(store).

js
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)
js
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]]) ​

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Expérimental]

Stable: 1 Stabilité: 1 - Expérimental

  • context <any> Message à envoyer aux abonnés et à lier aux magasins
  • fn <Function> Gestionnaire à exécuter dans le contexte de stockage saisi
  • thisArg <any> Le récepteur à utiliser pour l'appel de la fonction.
  • ...args <any> Arguments optionnels à passer à la fonction.

Applique les données fournies à toutes les instances AsyncLocalStorage liées au canal pendant la durée de la fonction donnée, puis publie sur le canal dans la portée de ces données appliquées aux magasins.

Si une fonction de transformation a été donnée à channel.bindStore(store), elle sera appliquée pour transformer les données du message avant qu'elles ne deviennent la valeur de contexte pour le magasin. Le contexte de stockage précédent est accessible depuis la fonction de transformation dans les cas où une liaison de contexte est requise.

Le contexte appliqué au magasin doit être accessible dans tout code asynchrone qui continue à partir de l'exécution qui a commencé pendant la fonction donnée, cependant il existe certaines situations dans lesquelles une perte de contexte peut se produire.

js
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' })
})
js
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' })
})

Classe : TracingChannel ​

Ajoutée dans : v19.9.0, v18.19.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

La classe TracingChannel est un ensemble de canaux TracingChannel qui, ensemble, expriment une seule action traçable. Elle est utilisée pour formaliser et simplifier le processus de production d’événements pour le traçage du flux d’application. diagnostics_channel.tracingChannel() est utilisé pour construire un TracingChannel. Comme pour Channel, il est recommandé de créer et de réutiliser un seul TracingChannel au niveau supérieur du fichier plutôt que de les créer dynamiquement.

tracingChannel.subscribe(subscribers) ​

Ajoutée dans : v19.9.0, v18.19.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Aide pour abonner un ensemble de fonctions aux canaux correspondants. C’est la même chose que d’appeler channel.subscribe(onMessage) sur chaque canal individuellement.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channels.subscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
})
js
const diagnostics_channel = require('node:diagnostics_channel')

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

channels.subscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
})

tracingChannel.unsubscribe(subscribers) ​

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Expérimental]

Stable: 1 Stabilité: 1 - Expérimental

Aide pour désabonner une collection de fonctions des canaux correspondants. Cela revient au même que d'appeler channel.unsubscribe(onMessage) sur chaque canal individuellement.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channels.unsubscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
})
js
const diagnostics_channel = require('node:diagnostics_channel')

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

channels.unsubscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
})

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

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Expérimental]

Stable: 1 Stabilité: 1 - Expérimental

  • fn <Function> Fonction autour de laquelle envelopper une trace
  • context <Object> Objet partagé pour corréler les événements
  • thisArg <any> Le récepteur à utiliser pour l'appel de la fonction
  • ...args <any> Arguments optionnels à passer à la fonction
  • Retourne : <any> La valeur de retour de la fonction donnée

Trace un appel de fonction synchrone. Cela produira toujours un événement start et un événement end autour de l'exécution et peut produire un événement error si la fonction donnée lève une erreur. Cela exécutera la fonction donnée en utilisant channel.runStores(context, ...) sur le canal start ce qui garantit que tous les événements doivent avoir tous les magasins liés définis pour correspondre à ce contexte de trace.

Pour garantir que seuls les graphes de trace corrects sont formés, les événements ne seront publiés que si des abonnés sont présents avant de démarrer la trace. Les abonnements qui sont ajoutés après le début de la trace ne recevront pas les événements futurs de cette trace, seules les futures traces seront vues.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceSync(
  () => {
    // Do something
  },
  {
    some: 'thing',
  }
)
js
const diagnostics_channel = require('node:diagnostics_channel')

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

channels.traceSync(
  () => {
    // Do something
  },
  {
    some: 'thing',
  }
)

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

Ajouté dans : v19.9.0, v18.19.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

  • fn <Function> Fonction renvoyant une Promise pour envelopper une trace
  • context <Object> Objet partagé pour corréler les évènements de trace
  • thisArg <any> Le récepteur à utiliser pour l’appel de la fonction
  • ...args <any> Arguments optionnels à passer à la fonction
  • Retourne : <Promise> Chaînée à partir de la Promise renvoyée par la fonction donnée

Trace un appel de fonction renvoyant une Promise. Cela produira toujours un évènement start et un évènement end autour de la partie synchrone de l’exécution de la fonction, et produira un évènement asyncStart et un évènement asyncEnd lorsqu’une continuation de la Promise est atteinte. Cela peut également produire un évènement error si la fonction donnée lève une erreur ou si la Promise renvoyée est rejetée. Cela exécutera la fonction donnée en utilisant channel.runStores(context, ...) sur le canal start ce qui garantit que tous les évènements devraient avoir tous les stockages liés définis pour correspondre à ce contexte de trace.

Pour garantir que seuls des graphes de trace corrects soient formés, les évènements ne seront publiés que si des abonnés sont présents avant le démarrage de la trace. Les abonnements qui sont ajoutés après le début de la trace ne recevront pas les évènements futurs de cette trace, seules les futures traces seront vues.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channels.tracePromise(
  async () => {
    // Do something
  },
  {
    some: 'thing',
  }
)
js
const diagnostics_channel = require('node:diagnostics_channel')

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

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

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

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Expérimental]

Stable: 1 Stabilité: 1 - Expérimental

  • fn <Function> fonction de rappel utilisant une fonction pour envelopper une trace
  • position <number> Position de l'argument indexé à zéro du rappel attendu (par défaut, le dernier argument si undefined est passé)
  • context <Object> Objet partagé pour corréler les événements de trace (par défaut, {} si undefined est passé)
  • thisArg <any> Le récepteur à utiliser pour l'appel de fonction
  • ...args <any> arguments à passer à la fonction (doit inclure le rappel)
  • Retourne : <any> La valeur de retour de la fonction donnée

Tracer un appel de fonction recevant un rappel. Le rappel est censé suivre la convention d'erreur en tant que premier argument habituellement utilisée. Cela produira toujours un événement start et un événement end autour de la portion synchrone de l'exécution de la fonction, et produira un événement asyncStart et un événement asyncEnd autour de l'exécution du rappel. Il peut également produire un événement error si la fonction donnée lève une erreur ou si le premier argument passé au rappel est défini. Cela exécutera la fonction donnée en utilisant channel.runStores(context, ...) sur le canal start qui garantit que tous les événements doivent avoir tous les magasins liés définis pour correspondre à ce contexte de trace.

Pour garantir que seuls des graphes de traces corrects sont formés, les événements ne seront publiés que si des abonnés sont présents avant le début de la trace. Les abonnements qui sont ajoutés après le début de la trace ne recevront pas les événements futurs de cette trace, seules les futures traces seront vues.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceCallback(
  (arg1, callback) => {
    // Do something
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)
js
const diagnostics_channel = require('node:diagnostics_channel')

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

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

Le rappel sera également exécuté avec channel.runStores(context, ...) ce qui permet la récupération de la perte de contexte dans certains cas.

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

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

// Le canal de départ définit les données initiales du magasin sur quelque chose
// et stocke cette valeur de données de magasin sur l'objet de contexte de trace
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Ensuite, asyncStart peut restaurer à partir de ces données qu'il a stockées précédemment
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})
js
const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

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

// Le canal de départ définit les données initiales du magasin sur quelque chose
// et stocke cette valeur de données de magasin sur l'objet de contexte de trace
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Ensuite, asyncStart peut restaurer à partir de ces données qu'il a stockées précédemment
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

tracingChannel.hasSubscribers ​

Ajouté dans : v22.0.0, v20.13.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

  • Retourne : <boolean> true si l’un des canaux individuels a un abonné, false sinon.

Il s’agit d’une méthode d’assistance disponible sur une instance de TracingChannel pour vérifier si l’un des canaux TracingChannel a des abonnés. La valeur true est retournée si l’un d’eux possède au moins un abonné, et la valeur false est retournée dans le cas contraire.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

if (channels.hasSubscribers) {
  // Faire quelque chose
}
js
const diagnostics_channel = require('node:diagnostics_channel')

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

if (channels.hasSubscribers) {
  // Faire quelque chose
}

Canaux TracingChannel ​

Un TracingChannel est un ensemble de plusieurs diagnostics_channels représentant des points spécifiques dans le cycle de vie de l’exécution d’une action traçable unique. Le comportement est divisé en cinq diagnostics_channels composés de start, end, asyncStart, asyncEnd et error. Une action traçable unique partagera le même objet d’événement entre tous les événements, ce qui peut être utile pour gérer la corrélation via une WeakMap.

Ces objets d’événement seront étendus avec les valeurs result ou error lorsque la tâche « se termine ». Dans le cas d’une tâche synchrone, la valeur result sera la valeur de retour et error sera tout ce qui est levé par la fonction. Avec les fonctions asynchrones basées sur un rappel, la valeur result sera le deuxième argument du rappel tandis que la valeur error sera soit une erreur levée visible dans l’événement end, soit le premier argument du rappel dans l’un des événements asyncStart ou asyncEnd.

Pour garantir que seuls les graphiques de trace corrects soient formés, les événements ne doivent être publiés que si des abonnés sont présents avant de commencer la trace. Les abonnements qui sont ajoutés après le début de la trace ne devraient pas recevoir d’événements futurs de cette trace ; seules les traces futures seront visibles.

Les canaux de traçage doivent suivre un modèle de nommage de :

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

start(event) ​

  • Nom : tracing:${name}:start

L’événement start représente le point auquel une fonction est appelée. À ce point, les données de l’événement peuvent contenir les arguments de la fonction ou tout autre élément disponible au tout début de l’exécution de la fonction.

end(event) ​

  • Nom : tracing:${name}:end

L’événement end représente le point auquel un appel de fonction renvoie une valeur. Dans le cas d’une fonction asynchrone, il s’agit du moment où la promesse est renvoyée et non du moment où la fonction elle-même effectue une instruction de retour en interne. À ce point, si la fonction tracée était synchrone, le champ result sera défini sur la valeur de retour de la fonction. En outre, le champ error peut être présent pour représenter toute erreur levée.

Il est recommandé d’écouter spécifiquement l’événement error pour suivre les erreurs, car il est possible qu’une action traçable produise plusieurs erreurs. Par exemple, une tâche asynchrone qui échoue peut être démarrée en interne avant que la partie synchrone de la tâche ne lève une erreur.

asyncStart(event) ​

  • Nom : tracing:${name}:asyncStart

L’événement asyncStart représente le rappel ou la continuation d’une fonction traçable en cours d’atteinte. À ce point, des éléments tels que les arguments de rappel peuvent être disponibles, ou tout autre élément exprimant le « résultat » de l’action.

Pour les fonctions basées sur les rappels, le premier argument du rappel sera attribué au champ error, s’il n’est pas undefined ou null, et le deuxième argument sera attribué au champ result.

Pour les promesses, l’argument du chemin resolve sera attribué à result ou l’argument du chemin reject sera attribué à error.

Il est recommandé d’écouter spécifiquement l’événement error pour suivre les erreurs, car il est possible qu’une action traçable produise plusieurs erreurs. Par exemple, une tâche asynchrone qui échoue peut être démarrée en interne avant que la partie synchrone de la tâche ne lève une erreur.

asyncEnd(event) ​

  • Nom : tracing:${name}:asyncEnd

L’événement asyncEnd représente le rappel d’une fonction asynchrone en cours de renvoi. Il est peu probable que les données d’événement changent après l’événement asyncStart. Cependant, il peut être utile de voir le point où le rappel se termine.

error(event) ​

  • Nom : tracing:${name}:error

L’événement error représente toute erreur produite par la fonction traçable, que ce soit de manière synchrone ou asynchrone. Si une erreur est levée dans la partie synchrone de la fonction tracée, l’erreur sera attribuée au champ error de l’événement et l’événement error sera déclenché. Si une erreur est reçue de manière asynchrone via un rappel ou un rejet de promesse, elle sera également attribuée au champ error de l’événement et déclenchera l’événement error.

Il est possible qu’un seul appel de fonction traçable produise des erreurs à plusieurs reprises ; il faut donc en tenir compte lors de la consommation de cet événement. Par exemple, si une autre tâche asynchrone est déclenchée en interne, qui échoue, puis que la partie synchrone de la fonction lève une erreur, deux événements error seront émis, un pour l’erreur synchrone et un pour l’erreur asynchrone.

Canaux intégrés ​

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Bien que l’API diagnostics_channel soit désormais considérée comme stable, les canaux intégrés actuellement disponibles ne le sont pas. Chaque canal doit être déclaré stable indépendamment.

HTTP ​

http.client.request.created

Émis lorsqu’un client crée un objet de requête. Contrairement à http.client.request.start, cet événement est émis avant que la requête n’ait été envoyée.

http.client.request.start

Émis lorsqu’un client démarre une requête.

http.client.request.error

Émis lorsqu’une erreur se produit lors d’une requête client.

http.client.response.finish

Émis lorsqu’un client reçoit une réponse.

http.server.request.start

Émis lorsqu’un serveur reçoit une requête.

http.server.response.created

Émis lorsqu’un serveur crée une réponse. L’événement est émis avant que la réponse ne soit envoyée.

http.server.response.finish

Émis lorsqu’un serveur envoie une réponse.

Modules ​

module.require.start

  • event <Object> contenant les propriétés suivantes :
    • id - Argument passé à require(). Nom du module.
    • parentFilename - Nom du module qui a tenté de faire require(id).

Émis lorsque require() est exécuté. Voir l'événement start.

module.require.end

  • event <Object> contenant les propriétés suivantes :
    • id - Argument passé à require(). Nom du module.
    • parentFilename - Nom du module qui a tenté de faire require(id).

Émis lorsqu'un appel à require() renvoie une valeur. Voir l'événement end.

module.require.error

  • event <Object> contenant les propriétés suivantes :

    • id - Argument passé à require(). Nom du module.
    • parentFilename - Nom du module qui a tenté de faire require(id).

  • error <Error>

Émis lorsqu'un require() lève une erreur. Voir l'événement error.

module.import.asyncStart

  • event <Object> contenant les propriétés suivantes :
    • id - Argument passé à import(). Nom du module.
    • parentURL - Objet URL du module qui a tenté de faire import(id).

Émis lorsque import() est invoqué. Voir l'événement asyncStart.

module.import.asyncEnd

  • event <Object> contenant les propriétés suivantes :
    • id - Argument passé à import(). Nom du module.
    • parentURL - Objet URL du module qui a tenté de faire import(id).

Émis lorsque import() est terminé. Voir l'événement asyncEnd.

module.import.error

  • event <Object> contenant les propriétés suivantes :

    • id - Argument passé à import(). Nom du module.
    • parentURL - Objet URL du module qui a tenté de faire import(id).

  • error <Error>

Émis lorsqu'un import() lève une erreur. Voir l'événement error.

NET ​

net.client.socket

Émis lorsqu'un nouveau socket client TCP ou pipe est créé.

net.server.socket

Émis lorsqu'une nouvelle connexion TCP ou pipe est reçue.

tracing:net.server.listen:asyncStart

Émis lorsque net.Server.listen() est invoqué, avant que le port ou le pipe ne soit réellement configuré.

tracing:net.server.listen:asyncEnd

Émis lorsque net.Server.listen() est terminé et que le serveur est donc prêt à accepter les connexions.

tracing:net.server.listen:error

Émis lorsque net.Server.listen() renvoie une erreur.

UDP ​

udp.socket

Émis lorsqu'un nouveau socket UDP est créé.

Processus ​

Ajouté dans : v16.18.0

child_process

Émis lorsqu'un nouveau processus est créé.

Thread Worker ​

Ajouté dans : v16.18.0

worker_threads

Émis lorsqu'un nouveau thread est créé.