iDoc.dev

Italiano

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

Italiano

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

Tema

Canale di diagnostica ​

[Cronologia]

VersioneModifiche
v19.2.0, v18.13.0diagnostics_channel è ora Stabile.
v15.1.0, v14.17.0Aggiunto in: v15.1.0, v14.17.0

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice Sorgente: lib/diagnostics_channel.js

Il modulo node:diagnostics_channel fornisce un'API per creare canali denominati per segnalare dati di messaggi arbitrari a scopo diagnostico.

È possibile accedervi tramite:

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

È inteso che uno sviluppatore di moduli che desidera segnalare messaggi di diagnostica creerà uno o più canali di livello superiore per segnalare i messaggi. I canali possono anche essere acquisiti in fase di runtime, ma non è incoraggiato a causa del sovraccarico aggiuntivo. I canali possono essere esportati per comodità, ma finché il nome è noto, può essere acquisito ovunque.

Se intendi che il tuo modulo produca dati di diagnostica che altri possano utilizzare, si consiglia di includere la documentazione di quali canali denominati vengono utilizzati insieme alla forma dei dati dei messaggi. I nomi dei canali dovrebbero generalmente includere il nome del modulo per evitare collisioni con i dati provenienti da altri moduli.

API pubblica ​

Panoramica ​

Di seguito è riportata una semplice panoramica dell'API pubblica.

js
import diagnostics_channel from 'node:diagnostics_channel';

// Ottieni un oggetto canale riutilizzabile
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Dati ricevuti
}

// Iscriviti al canale
diagnostics_channel.subscribe('my-channel', onMessage);

// Controlla se il canale ha un abbonato attivo
if (channel.hasSubscribers) {
  // Pubblica i dati sul canale
  channel.publish({
    some: 'data',
  });
}

// Annulla l'iscrizione al canale
diagnostics_channel.unsubscribe('my-channel', onMessage);
js
const diagnostics_channel = require('node:diagnostics_channel');

// Ottieni un oggetto canale riutilizzabile
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Dati ricevuti
}

// Iscriviti al canale
diagnostics_channel.subscribe('my-channel', onMessage);

// Controlla se il canale ha un abbonato attivo
if (channel.hasSubscribers) {
  // Pubblica i dati sul canale
  channel.publish({
    some: 'data',
  });
}

// Annulla l'iscrizione al canale
diagnostics_channel.unsubscribe('my-channel', onMessage);

diagnostics_channel.hasSubscribers(name) ​

Aggiunto in: v15.1.0, v14.17.0

Verifica se ci sono sottoscrittori attivi al canale specificato. Questo è utile se il messaggio che si desidera inviare potrebbe essere costoso da preparare.

Questa API è opzionale ma utile quando si cerca di pubblicare messaggi da codice molto sensibile alle prestazioni.

js
import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Ci sono sottoscrittori, prepara e pubblica il messaggio
}
js
const diagnostics_channel = require('node:diagnostics_channel');

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Ci sono sottoscrittori, prepara e pubblica il messaggio
}

diagnostics_channel.channel(name) ​

Aggiunto in: v15.1.0, v14.17.0

Questo è il punto di ingresso principale per chiunque voglia pubblicare su un canale con nome. Produce un oggetto canale che è ottimizzato per ridurre il più possibile l'overhead al momento della pubblicazione.

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

Aggiunto in: v18.7.0, v16.17.0

Registra un gestore di messaggi per sottoscriversi a questo canale. Questo gestore di messaggi verrà eseguito in modo sincrono ogni volta che un messaggio viene pubblicato sul canale. Qualsiasi errore generato nel gestore di messaggi attiverà un 'uncaughtException'.

js
import diagnostics_channel from 'node:diagnostics_channel';

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Dati ricevuti
});
js
const diagnostics_channel = require('node:diagnostics_channel');

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Dati ricevuti
});

diagnostics_channel.unsubscribe(name, onMessage) ​

Aggiunto in: v18.7.0, v16.17.0

  • name <stringa> | <simbolo> Il nome del canale
  • onMessage <Funzione> Il gestore precedentemente sottoscritto da rimuovere
  • Restituisce: <booleano> true se il gestore è stato trovato, false altrimenti.

Rimuove un gestore di messaggi precedentemente registrato su questo canale con diagnostics_channel.subscribe(name, onMessage).

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

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Crea un wrapper TracingChannel per i dati Canali TracingChannel. Se viene fornito un nome, i canali di tracciamento corrispondenti verranno creati nella forma tracing:${name}:${eventType} dove eventType corrisponde ai tipi di Canali TracingChannel.

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

Aggiunto in: v15.1.0, v14.17.0

La classe Channel rappresenta un singolo canale denominato all'interno della pipeline di dati. Viene utilizzata per tenere traccia degli iscritti e per pubblicare messaggi quando sono presenti iscritti. Esiste come oggetto separato per evitare ricerche di canali al momento della pubblicazione, consentendo velocità di pubblicazione molto elevate e consentendo un uso intenso con un costo minimo. I canali vengono creati con diagnostics_channel.channel(name), la costruzione di un canale direttamente con new Channel(name) non è supportata.

channel.hasSubscribers ​

Aggiunto in: v15.1.0, v14.17.0

  • Restituisce: <boolean> Se ci sono iscritti attivi

Verifica se ci sono iscritti attivi a questo canale. Questo è utile se il messaggio che si desidera inviare potrebbe essere costoso da preparare.

Questa API è facoltativa ma utile quando si cerca di pubblicare messaggi da codice molto sensibile alle prestazioni.

js
import diagnostics_channel from 'node:diagnostics_channel';

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

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}
js
const diagnostics_channel = require('node:diagnostics_channel');

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

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}

channel.publish(message) ​

Aggiunto in: v15.1.0, v14.17.0

  • message <any> Il messaggio da inviare agli iscritti al canale

Pubblica un messaggio a tutti gli iscritti al canale. Questo attiverà i gestori di messaggi in modo sincrono in modo che vengano eseguiti nello stesso contesto.

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

Aggiunto in: v15.1.0, v14.17.0

Deprecato a partire da: v18.7.0, v16.17.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Usa diagnostics_channel.subscribe(name, onMessage)

Registra un gestore di messaggi per iscriversi a questo canale. Questo gestore di messaggi verrà eseguito in modo sincrono ogni volta che un messaggio viene pubblicato sul canale. Eventuali errori generati nel gestore di messaggi attiveranno un 'uncaughtException'.

js
import diagnostics_channel from 'node:diagnostics_channel';

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

channel.subscribe((message, name) => {
  // Dati ricevuti
});
js
const diagnostics_channel = require('node:diagnostics_channel');

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

channel.subscribe((message, name) => {
  // Dati ricevuti
});

channel.unsubscribe(onMessage) ​

[Cronologia]

VersioneModifiche
v18.7.0, v16.17.0Deprecato a partire da: v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0Aggiunto il valore di ritorno. Aggiunto ai canali senza iscritti.
v15.1.0, v14.17.0Aggiunto in: v15.1.0, v14.17.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Usa diagnostics_channel.unsubscribe(name, onMessage)

  • onMessage <Function> Il gestore precedentemente sottoscritto da rimuovere
  • Restituisce: <boolean> true se il gestore è stato trovato, false altrimenti.

Rimuove un gestore di messaggi precedentemente registrato a questo canale con channel.subscribe(onMessage).

js
import diagnostics_channel from 'node:diagnostics_channel';

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

function onMessage(message, name) {
  // Dati ricevuti
}

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) {
  // Dati ricevuti
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

channel.bindStore(store[, transform]) ​

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

  • store <AsyncLocalStorage> Lo store a cui associare i dati di contesto
  • transform <Funzione> Trasforma i dati di contesto prima di impostare il contesto dello store

Quando viene chiamato channel.runStores(context, ...), i dati di contesto forniti verranno applicati a qualsiasi store associato al canale. Se lo store è già stato associato, la precedente funzione transform verrà sostituita con quella nuova. La funzione transform può essere omessa per impostare direttamente i dati di contesto forniti come contesto.

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

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Rimuove un gestore di messaggi precedentemente registrato a questo canale con 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]]) ​

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

  • context <any> Messaggio da inviare ai sottoscrittori e da associare agli store
  • fn <Function> Gestore da eseguire all'interno del contesto di archiviazione inserito
  • thisArg <any> Il ricevitore da utilizzare per la chiamata di funzione.
  • ...args <any> Argomenti opzionali da passare alla funzione.

Applica i dati forniti a qualsiasi istanza di AsyncLocalStorage associata al canale per la durata della funzione specificata, quindi pubblica sul canale nell'ambito di tali dati applicati agli store.

Se è stata fornita una funzione di trasformazione a channel.bindStore(store) verrà applicata per trasformare i dati del messaggio prima che diventino il valore di contesto per lo store. Il contesto di archiviazione precedente è accessibile dall'interno della funzione di trasformazione nei casi in cui è richiesto il collegamento del contesto.

Il contesto applicato allo store dovrebbe essere accessibile in qualsiasi codice asincrono che continua dall'esecuzione iniziata durante la funzione specificata, tuttavia ci sono alcune situazioni in cui può verificarsi perdita di contesto.

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 ​

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

La classe TracingChannel è una raccolta di Canali TracingChannel che insieme esprimono una singola azione tracciabile. Viene utilizzata per formalizzare e semplificare il processo di produzione di eventi per la tracciatura del flusso dell'applicazione. diagnostics_channel.tracingChannel() viene utilizzato per costruire un TracingChannel. Come con Channel si consiglia di creare e riutilizzare un singolo TracingChannel al livello superiore del file piuttosto che crearli dinamicamente.

tracingChannel.subscribe(subscribers) ​

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Helper per abbonare una raccolta di funzioni ai canali corrispondenti. Questo equivale a chiamare channel.subscribe(onMessage) su ciascun canale individualmente.

js
import diagnostics_channel from 'node:diagnostics_channel';

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

channels.subscribe({
  start(message) {
    // Gestisci il messaggio di inizio
  },
  end(message) {
    // Gestisci il messaggio di fine
  },
  asyncStart(message) {
    // Gestisci il messaggio asyncStart
  },
  asyncEnd(message) {
    // Gestisci il messaggio asyncEnd
  },
  error(message) {
    // Gestisci il messaggio di errore
  },
});
js
const diagnostics_channel = require('node:diagnostics_channel');

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

channels.subscribe({
  start(message) {
    // Gestisci il messaggio di inizio
  },
  end(message) {
    // Gestisci il messaggio di fine
  },
  asyncStart(message) {
    // Gestisci il messaggio asyncStart
  },
  asyncEnd(message) {
    // Gestisci il messaggio asyncEnd
  },
  error(message) {
    // Gestisci il messaggio di errore
  },
});

tracingChannel.unsubscribe(subscribers) ​

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Helper per disiscrivere una raccolta di funzioni dai canali corrispondenti. Questo è lo stesso di chiamare channel.unsubscribe(onMessage) su ogni canale individualmente.

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

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

  • fn <Function> Funzione per avvolgere una traccia
  • context <Object> Oggetto condiviso per correlare gli eventi
  • thisArg <any> Il ricevitore da utilizzare per la chiamata di funzione
  • ...args <any> Argomenti opzionali da passare alla funzione
  • Restituisce: <any> Il valore di ritorno della funzione data

Traccia una chiamata di funzione sincrona. Questo produrrà sempre un evento start event e un evento end event attorno all'esecuzione e potrebbe produrre un evento error event se la funzione data genera un errore. Questo eseguirà la funzione data utilizzando channel.runStores(context, ...) sul canale start il quale assicura che tutti gli eventi debbano avere tutti gli store associati impostati per corrispondere a questo contesto di traccia.

Per garantire che vengano formati solo grafici di traccia corretti, gli eventi verranno pubblicati solo se sono presenti sottoscrittori prima di avviare la traccia. Le sottoscrizioni che vengono aggiunte dopo l'inizio della traccia non riceveranno eventi futuri da quella traccia, verranno visualizzate solo le tracce future.

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

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

  • fn <Function> Funzione che restituisce una Promise da racchiudere in una traccia
  • context <Object> Oggetto condiviso per correlare gli eventi di traccia
  • thisArg <any> Il ricevitore da utilizzare per la chiamata alla funzione
  • ...args <any> Argomenti opzionali da passare alla funzione
  • Restituisce: <Promise> Concatenata dalla promise restituita dalla funzione data

Traccia una chiamata di funzione che restituisce una promise. Questo produrrà sempre un evento start event e end event attorno alla porzione sincrona dell'esecuzione della funzione, e produrrà un evento asyncStart event e asyncEnd event quando viene raggiunta una continuazione della promise. Può anche produrre un evento error event se la funzione data genera un errore o la promise restituita viene rifiutata. Questo eseguirà la funzione data usando channel.runStores(context, ...) sul canale start il che garantisce che tutti gli eventi debbano avere tutti gli store vincolati impostati in modo da corrispondere a questo contesto di traccia.

Per garantire che vengano formati solo grafi di traccia corretti, gli eventi verranno pubblicati solo se gli iscritti sono presenti prima di iniziare la traccia. Le iscrizioni che vengono aggiunte dopo l'inizio della traccia non riceveranno eventi futuri da quella traccia, verranno visualizzate solo le tracce future.

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

Aggiunto in: v19.9.0, v18.19.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

  • fn <Function> callback che utilizza una funzione per avvolgere una traccia
  • position <number> Posizione dell'argomento con indice zero del callback previsto (impostato di default all'ultimo argomento se viene passato undefined)
  • context <Object> Oggetto condiviso per correlare gli eventi di traccia (impostato di default a {} se viene passato undefined)
  • thisArg <any> Il ricevitore da utilizzare per la chiamata di funzione
  • ...args <any> argomenti da passare alla funzione (deve includere il callback)
  • Restituisce: <any> Il valore di ritorno della funzione specificata

Traccia una chiamata di funzione che riceve un callback. Si prevede che il callback segua la convenzione dell'errore come primo argomento tipicamente utilizzata. Questo produrrà sempre un evento start event e end event attorno alla porzione sincrona dell'esecuzione della funzione e produrrà un evento asyncStart event e asyncEnd event attorno all'esecuzione del callback. Potrebbe anche produrre un evento error event se la funzione specificata genera un'eccezione o se viene impostato il primo argomento passato al callback. Questo eseguirà la funzione specificata utilizzando channel.runStores(context, ...) sul canale start che garantisce che tutti gli eventi debbano avere tutti gli store vincolati impostati in modo da corrispondere a questo contesto di traccia.

Per garantire che vengano formati solo grafici di traccia corretti, gli eventi verranno pubblicati solo se gli iscritti sono presenti prima di iniziare la traccia. Le iscrizioni che vengono aggiunte dopo l'inizio della traccia non riceveranno eventi futuri da quella traccia, verranno visualizzate solo le tracce future.

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

Il callback verrà anche eseguito con channel.runStores(context, ...) che abilita il ripristino della perdita di contesto in alcuni casi.

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

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

// 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 ​

Aggiunto in: v22.0.0, v20.13.0

[Stable: 1 - Sperimentale]

Stable: 1 Stabilità: 1 - Sperimentale

  • Restituisce: <boolean> true se uno qualsiasi dei singoli canali ha un sottoscrittore, false in caso contrario.

Questo è un metodo helper disponibile su un'istanza di TracingChannel per verificare se uno qualsiasi dei Canali TracingChannel ha sottoscrittori. Viene restituito true se uno qualsiasi di essi ha almeno un sottoscrittore, false altrimenti.

js
import diagnostics_channel from 'node:diagnostics_channel';

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

if (channels.hasSubscribers) {
  // Fai qualcosa
}
js
const diagnostics_channel = require('node:diagnostics_channel');

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

if (channels.hasSubscribers) {
  // Fai qualcosa
}

Canali TracingChannel ​

Un TracingChannel è una raccolta di diversi diagnostics_channels che rappresentano punti specifici nel ciclo di vita dell'esecuzione di una singola azione tracciabile. Il comportamento è suddiviso in cinque diagnostics_channels costituiti da start, end, asyncStart, asyncEnd ed error. Una singola azione tracciabile condividerà lo stesso oggetto evento tra tutti gli eventi, questo può essere utile per la gestione della correlazione tramite una weakmap.

Questi oggetti evento saranno estesi con valori result o error quando l'attività è "completa". Nel caso di un'attività sincrona, il result sarà il valore di ritorno e l'error sarà qualsiasi cosa generata dalla funzione. Con le funzioni asincrone basate su callback, il result sarà il secondo argomento del callback mentre l'error sarà un errore generato visibile nell'evento end o il primo argomento del callback in uno degli eventi asyncStart o asyncEnd.

Per garantire che vengano formati solo grafici di traccia corretti, gli eventi devono essere pubblicati solo se i sottoscrittori sono presenti prima di avviare la traccia. Le sottoscrizioni aggiunte dopo l'inizio della traccia non devono ricevere eventi futuri da tale traccia, verranno visualizzate solo le tracce future.

I canali di tracciamento devono seguire uno schema di denominazione di:

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

start(event) ​

  • Nome: tracing:${name}:start

L'evento start rappresenta il punto in cui una funzione viene chiamata. A questo punto, i dati dell'evento possono contenere gli argomenti della funzione o qualsiasi altra cosa disponibile all'inizio dell'esecuzione della funzione.

end(event) ​

  • Nome: tracing:${name}:end

L'evento end rappresenta il punto in cui una chiamata di funzione restituisce un valore. Nel caso di una funzione asincrona, questo è quando la promise viene restituita, non quando la funzione stessa esegue internamente un'istruzione di ritorno. A questo punto, se la funzione tracciata era sincrona, il campo result sarà impostato sul valore di ritorno della funzione. In alternativa, il campo error può essere presente per rappresentare eventuali errori generati.

Si consiglia di ascoltare specificamente l'evento error per tenere traccia degli errori, poiché è possibile che un'azione tracciabile produca più errori. Ad esempio, un'attività asincrona che non riesce può essere avviata internamente prima della parte sincrona dell'attività e quindi generare un errore.

asyncStart(event) ​

  • Nome: tracing:${name}:asyncStart

L'evento asyncStart rappresenta il callback o la continuazione di una funzione tracciabile che viene raggiunta. A questo punto, potrebbero essere disponibili elementi come gli argomenti del callback o qualsiasi altra cosa che esprima il "risultato" dell'azione.

Per le funzioni basate su callback, il primo argomento del callback verrà assegnato al campo error, se non undefined o null, e il secondo argomento verrà assegnato al campo result.

Per le promise, l'argomento al percorso resolve verrà assegnato a result o l'argomento al percorso reject verrà assegnato a error.

Si consiglia di ascoltare specificamente l'evento error per tenere traccia degli errori, poiché è possibile che un'azione tracciabile produca più errori. Ad esempio, un'attività asincrona che non riesce può essere avviata internamente prima della parte sincrona dell'attività e quindi generare un errore.

asyncEnd(event) ​

  • Nome: tracing:${name}:asyncEnd

L'evento asyncEnd rappresenta il callback di una funzione asincrona che restituisce. È improbabile che i dati dell'evento cambino dopo l'evento asyncStart, tuttavia può essere utile vedere il punto in cui il callback viene completato.

error(event) ​

  • Nome: tracing:${name}:error

L'evento error rappresenta qualsiasi errore prodotto dalla funzione tracciabile, sia in modo sincrono che asincrono. Se un errore viene generato nella porzione sincrona della funzione tracciata, l'errore verrà assegnato al campo error dell'evento e verrà attivato l'evento error. Se un errore viene ricevuto in modo asincrono tramite un callback o un rifiuto di una promise, verrà anch'esso assegnato al campo error dell'evento e attiverà l'evento error.

È possibile che una singola chiamata di funzione tracciabile produca errori più volte, quindi è necessario tenerne conto quando si utilizza questo evento. Ad esempio, se internamente viene attivata un'altra attività asincrona che fallisce e quindi la parte sincrona della funzione genera un errore, verranno emessi due eventi error, uno per l'errore sincrono e uno per l'errore asincrono.

Canali integrati ​

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Sebbene l'API diagnostics_channel sia ora considerata stabile, i canali integrati attualmente disponibili non lo sono. Ogni canale deve essere dichiarato stabile indipendentemente.

HTTP ​

http.client.request.created

Emesso quando il client crea un oggetto richiesta. A differenza di http.client.request.start, questo evento viene emesso prima che la richiesta sia stata inviata.

http.client.request.start

Emesso quando il client avvia una richiesta.

http.client.request.error

Emesso quando si verifica un errore durante una richiesta del client.

http.client.response.finish

Emesso quando il client riceve una risposta.

http.server.request.start

Emesso quando il server riceve una richiesta.

http.server.response.created

Emesso quando il server crea una risposta. L'evento viene emesso prima che la risposta venga inviata.

http.server.response.finish

Emesso quando il server invia una risposta.

Moduli ​

module.require.start

  • event <Object> contenente le seguenti proprietà
    • id - Argomento passato a require(). Nome del modulo.
    • parentFilename - Nome del modulo che ha tentato di require(id).

Emesso quando viene eseguito require(). Vedi l'evento start.

module.require.end

  • event <Object> contenente le seguenti proprietà
    • id - Argomento passato a require(). Nome del modulo.
    • parentFilename - Nome del modulo che ha tentato di require(id).

Emesso quando una chiamata a require() restituisce un valore. Vedi l'evento end.

module.require.error

  • event <Object> contenente le seguenti proprietà

    • id - Argomento passato a require(). Nome del modulo.
    • parentFilename - Nome del modulo che ha tentato di require(id).

  • error <Error>

Emesso quando require() genera un errore. Vedi l'evento error.

module.import.asyncStart

  • event <Object> contenente le seguenti proprietà
    • id - Argomento passato a import(). Nome del modulo.
    • parentURL - Oggetto URL del modulo che ha tentato di import(id).

Emesso quando viene invocato import(). Vedi l'evento asyncStart.

module.import.asyncEnd

  • event <Object> contenente le seguenti proprietà
    • id - Argomento passato a import(). Nome del modulo.
    • parentURL - Oggetto URL del modulo che ha tentato di import(id).

Emesso quando import() è stato completato. Vedi l'evento asyncEnd.

module.import.error

  • event <Object> contenente le seguenti proprietà

    • id - Argomento passato a import(). Nome del modulo.
    • parentURL - Oggetto URL del modulo che ha tentato di import(id).

  • error <Error>

Emesso quando import() genera un errore. Vedi l'evento error.

NET ​

net.client.socket

Emesso quando viene creato un nuovo socket client TCP o pipe.

net.server.socket

Emesso quando viene ricevuta una nuova connessione TCP o pipe.

tracing:net.server.listen:asyncStart

Emesso quando viene invocato net.Server.listen(), prima che la porta o la pipe siano effettivamente impostate.

tracing:net.server.listen:asyncEnd

Emesso quando net.Server.listen() è stato completato e quindi il server è pronto ad accettare connessioni.

tracing:net.server.listen:error

Emesso quando net.Server.listen() restituisce un errore.

UDP ​

udp.socket

Emesso quando viene creato un nuovo socket UDP.

Process ​

Aggiunto in: v16.18.0

child_process

Emesso quando viene creato un nuovo processo.

Worker Thread ​

Aggiunto in: v16.18.0

worker_threads

Emesso quando viene creato un nuovo thread.