Canal de diagnostics

[Historique]

Version	Modifications
v19.2.0, v18.13.0	`diagnostics_channel` est maintenant Stable.
v15.1.0, v14.17.0	Ajouté 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 :

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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 représente. Les canaux peuvent être exportés pour plus de 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 pourront utiliser, il est recommandé d'inclure la documentation des canaux nommés utilisés ainsi que la forme des données du message. Les noms de canaux doivent généralement inclure le nom du module pour éviter les collisions avec les données d'autres modules.

API publique

Aperçu

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

ESMCJS

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 les données sur le canal
  channel.publish({
    some: 'data',
  });
}

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

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 les 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

name <string> | <symbol> Le nom du canal
Retourne : <boolean> S'il y a des abonnés actifs

Vérifie s'il y a 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.

ESMCJS

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
}

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

name <string> | <symbol> Le nom du canal
Retourne : <Channel> L'objet de canal nommé

Il s'agit du point d'entrée principal pour tous ceux qui souhaitent publier sur un canal nommé. Il produit un objet de canal qui est optimisé pour réduire autant que possible la surcharge au moment de la publication.

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

Ajouté dans : v18.7.0, v16.17.0

name <string> | <symbol> Le nom du canal
onMessage <Function> Le gestionnaire pour recevoir les messages du canal
- message <any> Les données du message
- name <string> | <symbol> Le nom du canal

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. Toutes les erreurs lancées dans le gestionnaire de messages déclencheront une 'uncaughtException'.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

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é sur ce canal avec diagnostics_channel.subscribe(name, onMessage).

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

function onMessage(message, name) {
  // Received data
}

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

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

const diagnostics_channel = require('node:diagnostics_channel');

function onMessage(message, name) {
  // Received data
}

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 - Experimental]

Stable: 1 Stabilité : 1 - Expérimental

nameOrChannels <string> | <TracingChannel> Nom du canal ou objet contenant tous les Canaux TracingChannel
Retourne : <TracingChannel> Collection de canaux à tracer avec

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

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

// or...

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

// or...

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ée 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 pour publier des messages lorsque des abonnés sont présents. Elle existe en tant qu’objet distinct pour éviter les recherches de canal au moment de la publication, ce qui permet des vitesses de publication très rapides et une utilisation intensive tout en entraînant des coûts minimes. 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ée dans : v15.1.0, v14.17.0

Retourne : <boolean> S’il y a des abonnés actifs

Vérifiez s’il y a 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.

ESMCJS

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
}

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ée dans : v15.1.0, v14.17.0

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

Publier un message à tous les abonnés au canal. Cela déclenchera les gestionnaires de messages de manière synchrone afin qu’ils s’exécutent dans le même contexte.

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

Ajouté dans : v15.1.0, v14.17.0

Obsolète depuis : v18.7.0, v16.17.0

[Stable: 0 - Obsolète]

Stable: 0 Stabilité : 0 - Obsolète : Utilisez diagnostics_channel.subscribe(name, onMessage)

onMessage <Function> Le gestionnaire pour recevoir les messages du canal
- message <any> Les données du message
- name <string> | <symbol> Le nom du canal

Enregistrez un gestionnaire de messages pour vous 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'.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

channel.subscribe((message, name) => {
  // Received data
});

const diagnostics_channel = require('node:diagnostics_channel');

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

channel.subscribe((message, name) => {
  // Received data
});

`channel.unsubscribe(onMessage)`

[Historique]

Version	Modifications
v18.7.0, v16.17.0	Obsolète depuis : v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0	Ajout d'une valeur de retour. Ajouté aux canaux sans abonnés.
v15.1.0, v14.17.0	Ajouté dans : v15.1.0, v14.17.0

[Stable: 0 - Obsolète]

Stable: 0 Stabilité : 0 - Obsolète : Utilisez diagnostics_channel.unsubscribe(name, onMessage)

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

Supprimez un gestionnaire de messages précédemment enregistré sur ce canal avec channel.subscribe(onMessage).

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

const diagnostics_channel = require('node:diagnostics_channel');

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

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

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

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 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 fournies sont appliquées à tout store lié au canal. Si le store a déjà été lié, la fonction transform précédente est remplacée par la nouvelle. La fonction transform peut être omise pour définir directement les données de contexte fournies comme contexte.

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

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Expérimental

store <AsyncLocalStorage> Le store à dissocier du canal.
Returns: <boolean> true si le store a été trouvé, false sinon.

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

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]])`

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Experimental]

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 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, mais il existe des situations dans lesquelles une perte de contexte peut se produire.

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

Classe : `TracingChannel`

Ajouté dans : v19.9.0, v18.19.0

[Stable: 1 - Expérimental]

Stable: 1 Stabilité: 1 - Expérimental

La classe TracingChannel est une collection de Canaux TracingChannel qui expriment ensemble 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 avec 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é dans : v19.9.0, v18.19.0

[Stable: 1 - Expérimental]

Stable: 1 Stabilité: 1 - Expérimental

subscribers <Objet> Ensemble d'abonnés Canaux TracingChannel
- start <Fonction> L'abonné à l'événement start
- end <Fonction> L'abonné à l'événement end
- asyncStart <Fonction> L'abonné à l'événement asyncStart
- asyncEnd <Fonction> L'abonné à l'événement asyncEnd
- error <Fonction> L'abonné à l'événement error

Aide à abonner une collection de fonctions aux canaux correspondants. Cela revient à appeler channel.subscribe(onMessage) sur chaque canal individuellement.

ESMCJS

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

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 - Experimental]

Stable: 1 Stable: 1 - Expérimental

subscribers <Object> Ensemble d'abonnés aux Canaux TracingChannel
- start <Function> L'abonné à l'événement start
- end <Function> L'abonné à l'événement end
- asyncStart <Function> L'abonné à l'événement asyncStart
- asyncEnd <Function> L'abonné à l'événement asyncEnd
- error <Function> L'abonné à l'événement error
Retourne : <boolean> true si tous les gestionnaires ont été désabonnés avec succès, et false sinon.

Assistant pour désabonner une collection de fonctions des canaux correspondants. Ceci est identique à l'appel de channel.unsubscribe(onMessage) sur chaque canal individuellement.

ESMCJS

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

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 - Experimental]

Stable: 1 Stable: 1 - Expérimental

fn <Function> Fonction autour de laquelle créer un trace
context <Object> Objet partagé pour corréler les événements
thisArg <any> Le receveur à utiliser pour l'appel de 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 start événement et un end événement autour de l'exécution et peut produire un error événement 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 des magasins liés définis pour correspondre à ce contexte de trace.

Pour garantir que seuls des graphes de trace corrects sont 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 traces futures seront vues.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

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

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 - Experimental]

Stable: 1 Stability: 1 - Expérimental

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

Trace un appel de fonction renvoyant une promesse. Cela produira toujours un événement start event et un événement end event autour de la partie synchrone de l’exécution de la fonction, et produira un événement asyncStart event et un événement asyncEnd event lorsqu’une continuation de promesse est atteinte. Cela peut également produire un événement error event si la fonction donnée lève une erreur ou si la promesse 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 des magasins liés définis pour correspondre à ce contexte de trace.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

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

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 - Experimental]

Stable: 1 Stable: 1 - Expérimental

fn <Function> Callback utilisant une fonction pour envelopper un trace
position <number> Position de l'argument (indexé à zéro) du callback 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 callback)
Retourne : <any> La valeur de retour de la fonction donnée

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

Pour garantir que seuls des graphes de trace 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 traces futures seront visibles.

ESMCJS

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

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 callback sera également exécuté avec channel.runStores(context, ...) ce qui permet la récupération de la perte de contexte dans certains cas.

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

// The start channel sets the initial store data to something
// and stores that store data value on the trace context object
channels.start.bindStore(myStore, (data) => {
  const span = new Span(data);
  data.span = span;
  return span;
});

// Then asyncStart can restore from that data it stored previously
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();

// The start channel sets the initial store data to something
// and stores that store data value on the trace context object
channels.start.bindStore(myStore, (data) => {
  const span = new Span(data);
  data.span = span;
  return span;
});

// Then asyncStart can restore from that data it stored previously
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. true est renvoyé si l’un d’eux a au moins un abonné, false est renvoyé sinon.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

if (channels.hasSubscribers) {
  // Do something
}

const diagnostics_channel = require('node:diagnostics_channel');

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

if (channels.hasSubscribers) {
  // Do something
}

Canaux TracingChannel

Un TracingChannel est une collection de plusieurs diagnostics_channels représentant des points spécifiques dans le cycle de vie de l’exécution d’une seule action traçable. Le comportement est divisé en cinq diagnostics_channels comprenant start, end, asyncStart, asyncEnd et error. Une seule action traçable 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 des valeurs result ou error lorsque la tâche est « terminée ». Dans le cas d’une tâche synchrone, le result sera la valeur de retour et l’error sera tout ce qui est lancé depuis la fonction. Avec les fonctions asynchrones basées sur un callback, le result sera le deuxième argument du callback tandis que l’error sera soit une erreur levée visible dans l’événement end, soit le premier argument du callback 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 démarrer la trace. Les abonnements qui sont ajoutés après le début de la trace ne doivent pas recevoir les événements futurs de cette trace, seules les traces futures seront vues.

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 moment où une fonction est appelée. À ce stade, 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 moment où un appel de fonction renvoie une valeur. Dans le cas d’une fonction asynchrone, c’est le moment où la promesse est renvoyée, et non le moment où la fonction elle-même effectue une instruction de retour en interne. À ce stade, si la fonction tracée était synchrone, le champ result sera défini sur la valeur de retour de la fonction. Le champ error peut également être présent pour représenter toute erreur généré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 génère une erreur.

`asyncStart(event)`

Nom : tracing:${name}:asyncStart

L’événement asyncStart représente le rappel ou la continuation d’une fonction traçable qui est atteinte. À ce stade, 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 des 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.

`asyncEnd(event)`

Nom : tracing:${name}:asyncEnd

L’événement asyncEnd représente le rappel d’une fonction asynchrone qui renvoie. Il est peu probable que les données de l’événement changent après l’événement asyncStart, mais il peut être utile de voir le moment 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 affecté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 affecté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 fois. 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 et é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 Stability : 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

request <http.ClientRequest>

Émis lorsque le 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

request <http.ClientRequest>

Émis lorsque le client démarre une requête.

http.client.request.error

request <http.ClientRequest>
error <Error>

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

http.client.response.finish

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

Émis lorsque le client reçoit une réponse.

http.server.request.start

Émis lorsque le serveur reçoit une requête.

http.server.response.created

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

Émis lorsque le 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 lorsque le 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é d'exécuter require(id).

Émis quand 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é d'exécuter require(id).

Émis quand un appel à require() retourne. 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é d'exécuter require(id).
error <Error>

Émis quand 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é d'exécuter import(id).

Émis quand 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é d'exécuter import(id).

Émis quand 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é d'exécuter import(id).
error <Error>

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

NET

net.client.socket

socket <net.Socket>

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

net.server.socket

socket <net.Socket>

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

tracing:net.server.listen:asyncStart

server <net.Server>
options <Object>

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

tracing:net.server.listen:asyncEnd

server <net.Server>

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

tracing:net.server.listen:error

server <net.Server>
error <Error>

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

UDP

udp.socket

socket <dgram.Socket>

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

Processus

Ajouté dans : v16.18.0

child_process

process <ChildProcess>

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

Thread de travail

Ajouté dans : v16.18.0

worker_threads

worker Worker

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

Canal de diagnostics ​

API publique ​

Aperçu ​

diagnostics_channel.hasSubscribers(name) ​

diagnostics_channel.channel(name) ​

diagnostics_channel.subscribe(name, onMessage) ​

diagnostics_channel.unsubscribe(name, onMessage) ​

diagnostics_channel.tracingChannel(nameOrChannels) ​

Classe : 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]]) ​

Classe : 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 ​

Canaux TracingChannel ​

start(event) ​

end(event) ​

asyncStart(event) ​

asyncEnd(event) ​

error(event) ​

Canaux intégrés ​

HTTP ​

Modules ​

NET ​

UDP ​

Processus ​

Thread de travail ​

Canal de diagnostics

API publique

Aperçu

`diagnostics_channel.hasSubscribers(name)`

`diagnostics_channel.channel(name)`

`diagnostics_channel.subscribe(name, onMessage)`

`diagnostics_channel.unsubscribe(name, onMessage)`

`diagnostics_channel.tracingChannel(nameOrChannels)`

Classe : `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]])`

Classe : `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`

Canaux TracingChannel

`start(event)`

`end(event)`

`asyncStart(event)`

`asyncEnd(event)`

`error(event)`

Canaux intégrés

HTTP

Modules

NET

UDP

Processus

Thread de travail