Canale di diagnostica

[Cronologia]

Versione	Modifiche
v19.2.0, v18.13.0	diagnostics_channel è ora Stabile.
v15.1.0, v14.17.0	Aggiunto 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 di diagnostica.

È possibile accedervi utilizzando:

ESM

import diagnostics_channel from 'node:diagnostics_channel'

CJS

const diagnostics_channel = require('node:diagnostics_channel')

Si intende che un autore di moduli che desidera segnalare messaggi di diagnostica creerà uno o più canali di livello superiore per segnalare i messaggi attraverso di essi. I canali possono anche essere acquisiti in fase di runtime, ma non è incoraggiato a causa del sovraccarico aggiuntivo che comporta. I canali possono essere esportati per comodità, ma purché il nome sia noto, possono essere acquisiti ovunque.

Se intendi che il tuo modulo produca dati diagnostici da consumare per altri, 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 di altri moduli.

API pubblica

Panoramica

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

ESM

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 sottoscrittore attivo
if (channel.hasSubscribers) {
  // Pubblica i dati sul canale
  channel.publish({
    some: 'data',
  })
}

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

CJS

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

• name <stringa> | <simbolo> Il nome del canale
• Restituisce: <boolean> Se ci sono abbonati attivi

Verifica se ci sono abbonati attivi al canale specificato. Ciò è 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.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

diagnostics_channel.channel(name)

Aggiunto in: v15.1.0, v14.17.0

• name <stringa> | <simbolo> Il nome del canale
• Restituisce: <Canale> L'oggetto canale specificato

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

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

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

• name <stringa> | <simbolo> Il nome del canale
• onMessage <Funzione> L'handler per ricevere i messaggi del canale
  • message <any> I dati del messaggio
  • name <stringa> | <simbolo> Il nome del canale

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. Qualsiasi errore generato nel gestore di messaggi attiverà un 'uncaughtException'.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

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 <string> | <symbol> Il nome del canale
• 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 diagnostics_channel.subscribe(name, onMessage).

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

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

• nameOrChannels <string> | <TracingChannel> Nome del canale o oggetto contenente tutti i Canali TracingChannel
• Restituisce: <TracingChannel> Collezione di canali da tracciare con

Crea un involucro 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.

ESM

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

CJS

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 permettendo un uso intenso sostenendo costi minimi. I canali vengono creati con diagnostics_channel.channel(name), non è supportata la costruzione di un canale direttamente con new Channel(name).

channel.hasSubscribers

Aggiunto in: v15.1.0, v14.17.0

• Restituisce: <boolean> Se ci sono abbonati attivi

Verifica se ci sono abbonati attivi a questo canale. Ciò è 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.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

if (channel.hasSubscribers) {
  // Ci sono abbonati, prepara e pubblica il messaggio
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

if (channel.hasSubscribers) {
  // Ci sono abbonati, prepara e pubblica il messaggio
}

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. Ciò attiverà i gestori dei messaggi in modo sincrono, in modo che vengano eseguiti nello stesso contesto.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

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)

• onMessage <Funzione> L'handler per ricevere i messaggi del canale
  • message <qualsiasi> I dati del messaggio
  • name <stringa> | <simbolo> Il nome del canale

Registra un gestore di messaggi per sottoscrivere 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'.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

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

channel.unsubscribe(onMessage)

[Cronologia]

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

[Stabile: 0 - Deprecato]

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

• onMessage <Funzione> Il precedente handler sottoscritto da rimuovere
• Restituisce: <booleano> true se l'handler è stato trovato, false altrimenti.

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

ESM

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)

CJS

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 collegare i dati di contesto
• transform <Function> 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 collegato al canale. Se lo store è già stato collegato, 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.

ESM

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

CJS

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

• store <AsyncLocalStorage> Lo store da scollegare dal canale.
• Restituisce: <boolean> true se lo store è stato trovato, false altrimenti.

Rimuove un gestore di messaggi precedentemente registrato a questo canale con channel.bindStore(store).

ESM

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)

CJS

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 agli iscritti 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 data, quindi pubblica sul canale all'interno dell'ambito in cui tali dati vengono applicati agli store.

Se una funzione di trasformazione è stata fornita 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 è richiesta la collegamento del contesto.

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

ESM

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

CJS

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

• subscribers <Object> Set di Canali TracingChannel iscritti
  • start <Function> L'iscritto all'evento start
  • end <Function> L'iscritto all'evento end
  • asyncStart <Function> L'iscritto all'evento asyncStart
  • asyncEnd <Function> L'iscritto all'evento asyncEnd
  • error <Function> L'iscritto all'evento error

Helper per iscrivere una raccolta di funzioni ai canali corrispondenti. Questo è lo stesso che chiamare channel.subscribe(onMessage) su ciascun canale individualmente.

ESM

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

CJS

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

• subscribers <Oggetto> Insieme di iscritti ai Canali TracingChannel

  • start <Funzione> L'iscritto all'evento start
  • end <Funzione> L'iscritto all'evento end
  • asyncStart <Funzione> L'iscritto all'evento asyncStart
  • asyncEnd <Funzione> L'iscritto all'evento asyncEnd
  • error <Funzione> L'iscritto all'evento error

• Restituisce: <booleano> true se tutti gli handler sono stati annullati con successo, e false altrimenti.

Helper per annullare l'iscrizione di una raccolta di funzioni dai canali corrispondenti. Equivale a chiamare channel.unsubscribe(onMessage) su ciascun canale individualmente.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.unsubscribe({
  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
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.unsubscribe({
  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.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 racchiudere 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 e un evento end intorno all'esecuzione e potrebbe produrre un evento error se la funzione data genera un errore. Questo eseguirà la funzione data usando channel.runStores(context, ...) sul canale start, il che garantisce che tutti gli eventi abbiano tutti gli store associati 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 sono presenti sottoscrittori prima di iniziare la traccia. Le sottoscrizioni aggiunte dopo l'inizio della traccia non riceveranno eventi futuri da tale traccia, ma verranno visualizzate solo le tracce future.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceSync(
  () => {
    // Fai qualcosa
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.traceSync(
  () => {
    // Fai qualcosa
  },
  {
    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 <Funzione> Funzione che restituisce una Promise da avvolgere con un trace
• context <Oggetto> Oggetto condiviso per correlare gli eventi di trace
• thisArg <any> Il ricevitore da utilizzare per la chiamata di 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 e un evento end attorno alla porzione sincrona dell'esecuzione della funzione e produrrà un evento asyncStart e un evento asyncEnd quando si raggiunge una continuazione della promise. Potrebbe anche produrre un evento error 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 abbiano tutti gli store vincolati 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 dell'inizio della traccia. Le sottoscrizioni che vengono aggiunte dopo l'inizio della traccia non riceveranno eventi futuri da tale traccia, verranno visualizzate solo le tracce future.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.tracePromise(
  async () => {
    // Fai qualcosa
  },
  {
    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 indicizzata a zero della callback prevista (il valore predefinito è l'ultimo argomento se viene passato undefined)
• context <Object> Oggetto condiviso per correlare gli eventi di traccia (il valore predefinito è {} se viene passato undefined)
• thisArg <any> Il ricevitore da utilizzare per la chiamata di funzione
• ...args <any> argomenti da passare alla funzione (deve includere la callback)
• Restituisce: <any> Il valore di ritorno della funzione data

Traccia una chiamata di funzione che riceve una callback. Si prevede che la callback segua la convenzione dell'errore come primo argomento tipicamente utilizzata. Questo produrrà sempre un evento start e un evento end attorno alla porzione sincrona dell'esecuzione della funzione e produrrà un evento asyncStart e un evento asyncEnd attorno all'esecuzione della callback. Potrebbe anche produrre un evento error se la funzione data genera un errore o se viene impostato il primo argomento passato alla callback. Questo eseguirà la funzione data utilizzando channel.runStores(context, ...) sul canale start che garantisce che tutti gli eventi debbano avere qualsiasi store associato impostato 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 dell'avvio della traccia. Le iscrizioni aggiunte dopo l'inizio della traccia non riceveranno eventi futuri da quella traccia, ma verranno visualizzate solo le tracce future.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

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

Anche la callback verrà eseguita con channel.runStores(context, ...) che consente il ripristino della perdita di contesto in alcuni casi.

ESM

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

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

// Il canale di inizio imposta i dati iniziali dello store su qualcosa
// e memorizza quel valore dei dati dello store sull'oggetto del contesto di traccia
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Quindi asyncStart può ripristinare da quei dati memorizzati in precedenza
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

CJS

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

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

// Il canale di inizio imposta i dati iniziali dello store su qualcosa
// e memorizza quel valore dei dati dello store sull'oggetto del contesto di traccia
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Quindi asyncStart può ripristinare da quei dati memorizzati in precedenza
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

tracingChannel.hasSubscribers

Aggiunto in: v22.0.0, v20.13.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

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

Questo è un metodo di supporto 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.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

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; ciò può essere utile per la gestione della correlazione tramite una weakmap.

Questi oggetti evento verranno estesi con valori result o error quando l'attività "termina". Nel caso di un'attività sincrona, il result sarà il valore restituito 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 qualsiasi 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 dell'inizio della traccia. Le sottoscrizioni che vengono 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. In 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 avviene quando la promise viene restituita, non quando la funzione stessa esegue un'istruzione return internamente. In 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 fallisce può essere avviata internamente prima che la parte sincrona dell'attività generi un errore.

asyncStart(event)

• Nome: tracing:${name}:asyncStart

L'evento asyncStart rappresenta il raggiungimento del callback o della continuazione di una funzione tracciabile. 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 del percorso resolve verrà assegnato a result o l'argomento del 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 fallisce può essere avviata internamente prima che la parte sincrona dell'attività generi un errore.

asyncEnd(event)

• Nome: tracing:${name}:asyncEnd

L'evento asyncEnd rappresenta il ritorno del callback di una funzione asincrona. Non è probabile 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 viene generato un errore nella parte 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 questo dovrebbe essere considerato quando si utilizza questo evento. Ad esempio, se un'altra attività asincrona viene attivata internamente e fallisce e poi 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 in modo indipendente.

HTTP

http.client.request.created

• request <http.ClientRequest>

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

• request <http.ClientRequest>

Emesso quando il client avvia una richiesta.

http.client.request.error

• request <http.ClientRequest>
• error <Error>

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

http.client.response.finish

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

Emesso quando il client riceve una risposta.

http.server.request.start

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

Emesso quando il server riceve una richiesta.

http.server.response.created

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

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

http.server.response.finish

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

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 eseguire require(id).

Emesso quando viene eseguito require(). Vedere 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 eseguire require(id).

Emesso quando una chiamata a require() restituisce un valore. Vedere 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 eseguire require(id).

• error <Error>

Emesso quando un require() genera un errore. Vedere 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 eseguire import(id).

Emesso quando viene invocato import(). Vedere 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 eseguire import(id).

Emesso quando import() è stato completato. Vedere 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 eseguire import(id).

• error <Error>

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

NET

net.client.socket

• socket <net.Socket>

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

net.server.socket

• socket <net.Socket>

Emesso quando viene ricevuta una nuova connessione TCP o pipe.

tracing:net.server.listen:asyncStart

• server <net.Server>
• options <Object>

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

tracing:net.server.listen:asyncEnd

• server <net.Server>

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

tracing:net.server.listen:error

• server <net.Server>
• error <Error>

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

UDP

udp.socket

• socket <dgram.Socket>

Emesso quando viene creato un nuovo socket UDP.

Processo

Aggiunto in: v16.18.0

child_process

• process <ChildProcess>

Emesso quando viene creato un nuovo processo.

Thread di lavoro

Aggiunto in: v16.18.0

worker_threads

• worker Worker

Emesso quando viene creato un nuovo thread.