iDoc.dev

Español

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

Español

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

Tema

Canal de Diagnóstico ​

[Historial]

VersiónCambios
v19.2.0, v18.13.0diagnostics_channel ahora es Estable.
v15.1.0, v14.17.0Añadido en: v15.1.0, v14.17.0

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código Fuente: lib/diagnostics_channel.js

El módulo node:diagnostics_channel proporciona una API para crear canales con nombre para informar datos de mensajes arbitrarios con fines de diagnóstico.

Se puede acceder a él utilizando:

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

Se pretende que un escritor de módulos que desee informar mensajes de diagnóstico cree uno o varios canales de nivel superior para informar mensajes. Los canales también se pueden adquirir en tiempo de ejecución, pero no se recomienda debido a la sobrecarga adicional de hacerlo. Los canales se pueden exportar por conveniencia, pero siempre que se conozca el nombre, se puede adquirir en cualquier lugar.

Si pretende que su módulo produzca datos de diagnóstico para que otros los consuman, se recomienda que incluya documentación de qué canales con nombre se utilizan junto con la forma de los datos del mensaje. Los nombres de los canales generalmente deben incluir el nombre del módulo para evitar colisiones con datos de otros módulos.

API pública ​

Visión general ​

A continuación se muestra una visión general simple de la API pública.

js
import diagnostics_channel from 'node:diagnostics_channel'

// Obtener un objeto de canal reutilizable
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Datos recibidos
}

// Suscribirse al canal
diagnostics_channel.subscribe('my-channel', onMessage)

// Comprobar si el canal tiene un suscriptor activo
if (channel.hasSubscribers) {
  // Publicar datos en el canal
  channel.publish({
    some: 'data',
  })
}

// Darse de baja del canal
diagnostics_channel.unsubscribe('my-channel', onMessage)
js
const diagnostics_channel = require('node:diagnostics_channel')

// Obtener un objeto de canal reutilizable
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Datos recibidos
}

// Suscribirse al canal
diagnostics_channel.subscribe('my-channel', onMessage)

// Comprobar si el canal tiene un suscriptor activo
if (channel.hasSubscribers) {
  // Publicar datos en el canal
  channel.publish({
    some: 'data',
  })
}

// Darse de baja del canal
diagnostics_channel.unsubscribe('my-channel', onMessage)

diagnostics_channel.hasSubscribers(name) ​

Añadido en: v15.1.0, v14.17.0

Comprueba si hay suscriptores activos en el canal nombrado. Esto es útil si el mensaje que desea enviar puede ser costoso de preparar.

Esta API es opcional pero útil cuando se intenta publicar mensajes desde código muy sensible al rendimiento.

js
import diagnostics_channel from 'node:diagnostics_channel'

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Hay suscriptores, preparar y publicar mensaje
}
js
const diagnostics_channel = require('node:diagnostics_channel')

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Hay suscriptores, preparar y publicar mensaje
}

diagnostics_channel.channel(name) ​

Añadido en: v15.1.0, v14.17.0

Este es el punto de entrada principal para cualquiera que quiera publicar en un canal con nombre. Produce un objeto de canal que está optimizado para reducir la sobrecarga en el momento de la publicación tanto como sea posible.

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

Añadido en: v18.7.0, v16.17.0

Registrar un controlador de mensajes para suscribirse a este canal. Este controlador de mensajes se ejecutará sincrónicamente cada vez que se publique un mensaje en el canal. Cualquier error lanzado en el controlador de mensajes activará una excepción 'uncaughtException'.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

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

diagnostics_channel.unsubscribe(name, onMessage) ​

Añadido en: v18.7.0, v16.17.0

  • name <string> | <symbol> El nombre del canal
  • onMessage <Function> El manejador suscrito previamente que se va a eliminar
  • Devuelve: <boolean> true si se encontró el manejador, false en caso contrario.

Elimina un manejador de mensajes registrado previamente en este canal con diagnostics_channel.subscribe(name, onMessage).

js
import diagnostics_channel from 'node:diagnostics_channel'

function onMessage(message, name) {
  // Datos recibidos
}

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

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

function onMessage(message, name) {
  // Datos recibidos
}

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

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

diagnostics_channel.tracingChannel(nameOrChannels) ​

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Crea un contenedor TracingChannel para los Canales TracingChannel dados. Si se proporciona un nombre, se crearán los canales de rastreo correspondientes en la forma tracing:${name}:${eventType}, donde eventType corresponde a los tipos de Canales TracingChannel.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

// o...

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

// o...

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

Clase: Channel ​

Añadido en: v15.1.0, v14.17.0

La clase Channel representa un canal con nombre individual dentro del pipeline de datos. Se utiliza para rastrear suscriptores y para publicar mensajes cuando hay suscriptores presentes. Existe como un objeto separado para evitar búsquedas de canales en el momento de la publicación, lo que permite velocidades de publicación muy rápidas y permite un uso intensivo con un coste mínimo. Los canales se crean con diagnostics_channel.channel(name), no se admite la construcción de un canal directamente con new Channel(name).

channel.hasSubscribers ​

Añadido en: v15.1.0, v14.17.0

  • Devuelve: <boolean> Si hay suscriptores activos

Comprueba si hay suscriptores activos en este canal. Esto es útil si el mensaje que desea enviar puede ser costoso de preparar.

Esta API es opcional, pero útil cuando se intenta publicar mensajes desde código muy sensible al rendimiento.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

if (channel.hasSubscribers) {
  // Hay suscriptores, preparar y publicar mensaje
}
js
const diagnostics_channel = require('node:diagnostics_channel')

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

if (channel.hasSubscribers) {
  // Hay suscriptores, preparar y publicar mensaje
}

channel.publish(message) ​

Añadido en: v15.1.0, v14.17.0

  • message <any> El mensaje a enviar a los suscriptores del canal

Publica un mensaje a cualquier suscriptor del canal. Esto activará los manejadores de mensajes de forma sincrónica, por lo que se ejecutarán dentro del mismo contexto.

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

Añadido en: v15.1.0, v14.17.0

Obsoleto desde: v18.7.0, v16.17.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use diagnostics_channel.subscribe(name, onMessage)

Registra un manejador de mensajes para suscribirse a este canal. Este manejador de mensajes se ejecutará de forma sincrónica cada vez que se publique un mensaje en el canal. Cualquier error que se produzca en el manejador de mensajes activará una excepción 'uncaughtException'.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

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

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

channel.subscribe((message, name) => {
  // Datos recibidos
})

channel.unsubscribe(onMessage) ​

[Historial]

VersiónCambios
v18.7.0, v16.17.0Obsoleto desde: v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0Se agregó el valor devuelto. Se agregó a canales sin suscriptores.
v15.1.0, v14.17.0Añadido en: v15.1.0, v14.17.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use diagnostics_channel.unsubscribe(name, onMessage)

  • onMessage <Function> El controlador suscrito previamente a eliminar
  • Devuelve: <boolean> true si se encontró el controlador, false de lo contrario.

Eliminar un controlador de mensajes registrado previamente en este canal con channel.subscribe(onMessage).

js
import diagnostics_channel from 'node:diagnostics_channel'

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

function onMessage(message, name) {
  // Datos recibidos
}

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) {
  // Datos recibidos
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

channel.bindStore(store[, transform]) ​

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • store <AsyncLocalStorage> El almacén al que enlazar los datos del contexto
  • transform <Function> Transforma los datos del contexto antes de establecer el contexto del almacén

Cuando se llama a channel.runStores(context, ...), los datos de contexto dados se aplicarán a cualquier almacén enlazado al canal. Si el almacén ya se ha enlazado, la función transform anterior será reemplazada por la nueva. La función transform puede omitirse para establecer los datos de contexto dados como el contexto directamente.

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

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • store <AsyncLocalStorage> El almacén que se va a desvincular del canal.
  • Devuelve: <boolean> true si se encontró el almacén, false en caso contrario.

Elimina un controlador de mensajes registrado previamente en este canal 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]]) ​

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • context <any> Mensaje para enviar a los suscriptores y enlazar a los almacenes
  • fn <Function> Manejador para ejecutar dentro del contexto de almacenamiento ingresado
  • thisArg <any> El receptor que se utilizará para la llamada a la función.
  • ...args <any> Argumentos opcionales para pasar a la función.

Aplica los datos dados a cualquier instancia de AsyncLocalStorage enlazada al canal durante la duración de la función dada, luego publica en el canal dentro del alcance de que los datos se aplican a los almacenes.

Si se proporciona una función de transformación a channel.bindStore(store), se aplicará para transformar los datos del mensaje antes de que se convierta en el valor de contexto para el almacén. El contexto de almacenamiento anterior es accesible desde dentro de la función de transformación en los casos en que se requiere la vinculación de contexto.

El contexto aplicado al almacén debe ser accesible en cualquier código asincrónico que continúe desde la ejecución que comenzó durante la función dada, sin embargo, hay algunas situaciones en las que se puede producir pérdida de contexto.

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

Clase: TracingChannel ​

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

La clase TracingChannel es una colección de Canales TracingChannel que juntas expresan una única acción rastreable. Se utiliza para formalizar y simplificar el proceso de producción de eventos para rastrear el flujo de la aplicación. diagnostics_channel.tracingChannel() se utiliza para construir un TracingChannel. Al igual que con Channel, se recomienda crear y reutilizar un único TracingChannel en el nivel superior del archivo en lugar de crearlos dinámicamente.

tracingChannel.subscribe(subscribers) ​

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Ayudante para suscribir una colección de funciones a los canales correspondientes. Esto es lo mismo que llamar a channel.subscribe(onMessage) en cada canal individualmente.

js
import diagnostics_channel from 'node:diagnostics_channel'

const canales = diagnostics_channel.tracingChannel('mi-canal')

canales.subscribe({
  start(mensaje) {
    // Manejar mensaje de inicio
  },
  end(mensaje) {
    // Manejar mensaje de fin
  },
  asyncStart(mensaje) {
    // Manejar mensaje asyncStart
  },
  asyncEnd(mensaje) {
    // Manejar mensaje asyncEnd
  },
  error(mensaje) {
    // Manejar mensaje de error
  },
})
js
const diagnostics_channel = require('node:diagnostics_channel')

const canales = diagnostics_channel.tracingChannel('mi-canal')

canales.subscribe({
  start(mensaje) {
    // Manejar mensaje de inicio
  },
  end(mensaje) {
    // Manejar mensaje de fin
  },
  asyncStart(mensaje) {
    // Manejar mensaje asyncStart
  },
  asyncEnd(mensaje) {
    // Manejar mensaje asyncEnd
  },
  error(mensaje) {
    // Manejar mensaje de error
  },
})

tracingChannel.unsubscribe(subscribers) ​

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Ayudante para cancelar la suscripción de una colección de funciones de los canales correspondientes. Esto es lo mismo que llamar a channel.unsubscribe(onMessage) en cada canal individualmente.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

channels.unsubscribe({
  start(message) {
    // Manejar mensaje de inicio
  },
  end(message) {
    // Manejar mensaje de fin
  },
  asyncStart(message) {
    // Manejar mensaje asyncStart
  },
  asyncEnd(message) {
    // Manejar mensaje asyncEnd
  },
  error(message) {
    // Manejar mensaje de error
  },
})
js
const diagnostics_channel = require('node:diagnostics_channel')

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

channels.unsubscribe({
  start(message) {
    // Manejar mensaje de inicio
  },
  end(message) {
    // Manejar mensaje de fin
  },
  asyncStart(message) {
    // Manejar mensaje asyncStart
  },
  asyncEnd(message) {
    // Manejar mensaje asyncEnd
  },
  error(message) {
    // Manejar mensaje de error
  },
})

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

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • fn <Function> Función para envolver un seguimiento
  • context <Object> Objeto compartido para correlacionar eventos a través de
  • thisArg <any> El receptor que se usará para la llamada a la función
  • ...args <any> Argumentos opcionales para pasar a la función
  • Devuelve: <any> El valor de retorno de la función dada

Traza una llamada a función sincrónica. Esto siempre producirá un evento start y un evento end alrededor de la ejecución y puede producir un evento error si la función dada lanza un error. Esto ejecutará la función dada usando channel.runStores(context, ...) en el canal start, lo que asegura que todos los eventos deberían tener cualquier almacén enlazado configurado para que coincida con este contexto de traza.

Para asegurar que solo se formen gráficos de traza correctos, los eventos solo se publicarán si hay suscriptores presentes antes de iniciar la traza. Las suscripciones que se agregan después de que comience la traza no recibirán eventos futuros de esa traza, solo se verán las trazas futuras.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

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

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

channels.traceSync(
  () => {
    // Hacer algo
  },
  {
    some: 'thing',
  }
)

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

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • fn <Function> Función que devuelve una promesa para envolver un seguimiento
  • context <Object> Objeto compartido para correlacionar eventos de seguimiento a través de
  • thisArg <any> El receptor que se utilizará para la llamada a la función
  • ...args <any> Argumentos opcionales para pasar a la función
  • Devuelve: <Promise> Encadenado desde la promesa devuelta por la función dada

Traza una llamada a una función que devuelve una promesa. Esto siempre producirá un evento start y un evento end alrededor de la parte sincrónica de la ejecución de la función, y producirá un evento asyncStart y un evento asyncEnd cuando se alcance una continuación de la promesa. También puede producir un evento error si la función dada lanza un error o la promesa devuelta se rechaza. Esto ejecutará la función dada usando channel.runStores(context, ...) en el canal start, lo que garantiza que todos los eventos deben tener cualquier almacén enlazado configurado para que coincida con este contexto de seguimiento.

Para asegurar que solo se forman gráficos de seguimiento correctos, los eventos solo se publicarán si hay suscriptores presentes antes de iniciar el seguimiento. Las suscripciones que se agregan después de que comienza el seguimiento no recibirán eventos futuros de ese seguimiento, solo se verán los seguimientos futuros.

js
import diagnostics_channel from 'node:diagnostics_channel'

const canales = diagnostics_channel.tracingChannel('mi-canal')

canales.tracePromise(
  async () => {
    // Hacer algo
  },
  {
    algo: 'cosa',
  }
)
js
const diagnostics_channel = require('node:diagnostics_channel')

const canales = diagnostics_channel.tracingChannel('mi-canal')

canales.tracePromise(
  async () => {
    // Hacer algo
  },
  {
    algo: 'cosa',
  }
)

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

Añadido en: v19.9.0, v18.19.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • fn <Function> función de devolución de llamada que se utiliza para envolver un seguimiento
  • position <number> Posición del argumento con índice cero de la devolución de llamada esperada (por defecto, el último argumento si se pasa undefined)
  • context <Object> Objeto compartido para correlacionar eventos de seguimiento (por defecto {} si se pasa undefined)
  • thisArg <any> El receptor que se utilizará para la llamada a la función
  • ...args <any> argumentos que se pasarán a la función (debe incluir la devolución de llamada)
  • Devuelve: <any> El valor de retorno de la función dada

Traza una llamada a función que recibe una devolución de llamada. Se espera que la devolución de llamada siga el convenio de error como primer argumento que se usa normalmente. Esto siempre producirá un evento start y un evento end alrededor de la parte síncrona de la ejecución de la función, y producirá un evento asyncStart y un evento asyncEnd alrededor de la ejecución de la devolución de llamada. También puede producir un evento error si la función dada lanza una excepción o se establece el primer argumento pasado a la devolución de llamada. Esto ejecutará la función dada usando channel.runStores(context, ...) en el canal start, lo que garantiza que todos los eventos deben tener cualquier almacén enlazado establecido para que coincida con este contexto de seguimiento.

Para asegurar que solo se formen gráficos de seguimiento correctos, los eventos solo se publicarán si hay suscriptores presentes antes de iniciar el seguimiento. Las suscripciones que se agregan después de que comience el seguimiento no recibirán eventos futuros de ese seguimiento, solo se verán los seguimientos futuros.

js
import diagnostics_channel from 'node:diagnostics_channel'

const canales = diagnostics_channel.tracingChannel('mi-canal')

canales.traceCallback(
  (arg1, callback) => {
    // Hacer algo
    callback(null, 'resultado')
  },
  1,
  {
    algo: 'cosa',
  },
  thisArg,
  arg1,
  callback
)
js
const diagnostics_channel = require('node:diagnostics_channel')

const canales = diagnostics_channel.tracingChannel('mi-canal')

canales.traceCallback(
  (arg1, callback) => {
    // Hacer algo
    callback(null, 'resultado')
  },
  1,
  {
    algo: 'cosa',
  },
  thisArg,
  arg1,
  callback
)

La devolución de llamada también se ejecutará con channel.runStores(context, ...), lo que permite la recuperación de la pérdida de contexto en algunos casos.

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

const canales = diagnostics_channel.tracingChannel('mi-canal')
const miAlmacén = new AsyncLocalStorage()

// El canal de inicio establece los datos del almacén inicial en algo
// y almacena ese valor de datos del almacén en el objeto de contexto de seguimiento
canales.start.bindStore(miAlmacén, datos => {
  const intervalo = new Intervalo(datos)
  datos.intervalo = intervalo
  return intervalo
})

// Luego, asyncStart puede restaurar desde esos datos que almacenó previamente
canales.asyncStart.bindStore(miAlmacén, datos => {
  return datos.intervalo
})
js
const diagnostics_channel = require('node:diagnostics_channel')
const { AsyncLocalStorage } = require('node:async_hooks')

const canales = diagnostics_channel.tracingChannel('mi-canal')
const miAlmacén = new AsyncLocalStorage()

// El canal de inicio establece los datos del almacén inicial en algo
// y almacena ese valor de datos del almacén en el objeto de contexto de seguimiento
canales.start.bindStore(miAlmacén, datos => {
  const intervalo = new Intervalo(datos)
  datos.intervalo = intervalo
  return intervalo
})

// Luego, asyncStart puede restaurar desde esos datos que almacenó previamente
canales.asyncStart.bindStore(miAlmacén, datos => {
  return datos.intervalo
})

tracingChannel.hasSubscribers ​

Añadido en: v22.0.0, v20.13.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • Devuelve: <boolean> true si alguno de los canales individuales tiene un suscriptor, false si no.

Este es un método auxiliar disponible en una instancia de TracingChannel para comprobar si alguno de los Canales de TracingChannel tiene suscriptores. Se devuelve true si alguno de ellos tiene al menos un suscriptor, y false en caso contrario.

js
import diagnostics_channel from 'node:diagnostics_channel'

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

if (channels.hasSubscribers) {
  // Hacer algo
}
js
const diagnostics_channel = require('node:diagnostics_channel')

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

if (channels.hasSubscribers) {
  // Hacer algo
}

Canales TracingChannel ​

Un TracingChannel es una colección de varios diagnostics_channels que representan puntos específicos en el ciclo de vida de ejecución de una sola acción rastreable. El comportamiento se divide en cinco diagnostics_channels que consisten en start, end, asyncStart, asyncEnd, y error. Una sola acción rastreable compartirá el mismo objeto de evento entre todos los eventos; esto puede ser útil para gestionar la correlación a través de un weakmap.

Estos objetos de evento se extenderán con valores result o error cuando la tarea "complete". En el caso de una tarea síncrona, el result será el valor de retorno y el error será cualquier cosa lanzada desde la función. Con funciones asíncronas basadas en callbacks, el result será el segundo argumento del callback, mientras que el error será o bien un error lanzado visible en el evento end o el primer argumento del callback en cualquiera de los eventos asyncStart o asyncEnd.

Para asegurar que solo se formen gráficos de rastreo correctos, los eventos solo deben publicarse si hay suscriptores presentes antes de comenzar el rastreo. Las suscripciones que se agreguen después de que comience el rastreo no deben recibir eventos futuros de ese rastreo; solo se verán los rastreos futuros.

Los canales de rastreo deben seguir un patrón de nomenclatura de:

  • tracing:módulo.clase.método:start o tracing:módulo.función:start
  • tracing:módulo.clase.método:end o tracing:módulo.función:end
  • tracing:módulo.clase.método:asyncStart o tracing:módulo.función:asyncStart
  • tracing:módulo.clase.método:asyncEnd o tracing:módulo.función:asyncEnd
  • tracing:módulo.clase.método:error o tracing:módulo.función:error

start(event) ​

  • Nombre: tracing:${name}:start

El evento start representa el punto en el que se llama a una función. En este punto, los datos del evento pueden contener argumentos de la función o cualquier otra cosa disponible al comienzo de la ejecución de la función.

end(event) ​

  • Nombre: tracing:${name}:end

El evento end representa el punto en el que una llamada a función devuelve un valor. En el caso de una función asincrónica, esto ocurre cuando se devuelve la promesa, no cuando la función en sí misma realiza una instrucción de retorno internamente. En este punto, si la función rastreada fue sincrónica, el campo result se establecerá en el valor de retorno de la función. Alternativamente, el campo error puede estar presente para representar cualquier error lanzado.

Se recomienda escuchar específicamente el evento error para rastrear errores, ya que es posible que una acción rastreable produzca múltiples errores. Por ejemplo, una tarea asincrónica que falla puede iniciarse internamente antes de que la parte sincrónica de la tarea lance un error.

asyncStart(evento) ​

  • Nombre: tracing:${name}:asyncStart

El evento asyncStart representa la devolución de llamada o la continuación de una función rastreable que se ha alcanzado. En este punto, pueden estar disponibles cosas como los argumentos de devolución de llamada, o cualquier otra cosa que exprese el "resultado" de la acción.

Para las funciones basadas en devoluciones de llamada, el primer argumento de la devolución de llamada se asignará al campo error, si no es undefined o null, y el segundo argumento se asignará al campo result.

Para las promesas, el argumento en la ruta resolve se asignará a result o el argumento en la ruta reject se asignará a error.

Se recomienda escuchar específicamente el evento error para rastrear errores, ya que es posible que una acción rastreable produzca múltiples errores. Por ejemplo, una tarea asincrónica que falla puede iniciarse internamente antes de que la parte sincrónica de la tarea lance un error.

asyncEnd(evento) ​

  • Nombre: tracing:${name}:asyncEnd

El evento asyncEnd representa la devolución de llamada de una función asincrónica que retorna. No es probable que los datos del evento cambien después del evento asyncStart, sin embargo, puede ser útil ver el punto donde se completa la devolución de llamada.

error(event) ​

  • Nombre: tracing:${name}:error

El evento error representa cualquier error producido por la función rastreable de forma síncrona o asíncrona. Si se produce un error en la parte síncrona de la función rastreada, el error se asignará al campo error del evento y se activará el evento error. Si se recibe un error de forma asíncrona a través de una devolución de llamada o un rechazo de promesa, también se asignará al campo error del evento y se activará el evento error.

Es posible que una sola llamada a una función rastreable produzca errores varias veces, por lo que esto debe tenerse en cuenta al consumir este evento. Por ejemplo, si se activa internamente otra tarea asíncrona que falla y luego la parte síncrona de la función lanza un error, se emitirán dos eventos error, uno para el error síncrono y otro para el error asíncrono.

Canales Integrados ​

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Si bien la API diagnostics_channel ahora se considera estable, los canales integrados actualmente disponibles no lo son. Cada canal debe declararse estable de forma independiente.

HTTP ​

http.client.request.created

Emitido cuando el cliente crea un objeto de solicitud. A diferencia de http.client.request.start, este evento se emite antes de que se haya enviado la solicitud.

http.client.request.start

Emitido cuando el cliente inicia una solicitud.

http.client.request.error

Emitido cuando ocurre un error durante una solicitud del cliente.

http.client.response.finish

Emitido cuando el cliente recibe una respuesta.

http.server.request.start

Emitido cuando el servidor recibe una solicitud.

http.server.response.created

Emitido cuando el servidor crea una respuesta. El evento se emite antes de que se envíe la respuesta.

http.server.response.finish

Emitido cuando el servidor envía una respuesta.

Módulos ​

module.require.start

  • event <Object> que contiene las siguientes propiedades:
    • id - Argumento pasado a require(). Nombre del módulo.
    • parentFilename - Nombre del módulo que intentó requerir (id).

Emitido cuando se ejecuta require(). Ver evento start.

module.require.end

  • event <Object> que contiene las siguientes propiedades:
    • id - Argumento pasado a require(). Nombre del módulo.
    • parentFilename - Nombre del módulo que intentó requerir (id).

Emitido cuando una llamada require() retorna. Ver evento end.

module.require.error

  • event <Object> que contiene las siguientes propiedades:

    • id - Argumento pasado a require(). Nombre del módulo.
    • parentFilename - Nombre del módulo que intentó requerir (id).

  • error <Error>

Emitido cuando require() lanza un error. Ver evento error.

module.import.asyncStart

  • event <Object> que contiene las siguientes propiedades:
    • id - Argumento pasado a import(). Nombre del módulo.
    • parentURL - Objeto URL del módulo que intentó importar (id).

Emitido cuando se invoca import(). Ver evento asyncStart.

module.import.asyncEnd

  • event <Object> que contiene las siguientes propiedades:
    • id - Argumento pasado a import(). Nombre del módulo.
    • parentURL - Objeto URL del módulo que intentó importar (id).

Emitido cuando import() ha completado. Ver evento asyncEnd.

module.import.error

  • event <Object> que contiene las siguientes propiedades:

    • id - Argumento pasado a import(). Nombre del módulo.
    • parentURL - Objeto URL del módulo que intentó importar (id).

  • error <Error>

Emitido cuando import() lanza un error. Ver evento error.

NET ​

net.client.socket

Emitido cuando se crea un nuevo socket de cliente TCP o de tubería.

net.server.socket

Emitido cuando se recibe una nueva conexión TCP o de tubería.

tracing:net.server.listen:asyncStart

Emitido cuando se invoca net.Server.listen(), antes de que el puerto o la tubería estén realmente configurados.

tracing:net.server.listen:asyncEnd

Emitido cuando net.Server.listen() ha finalizado y, por lo tanto, el servidor está listo para aceptar conexiones.

tracing:net.server.listen:error

Emitido cuando net.Server.listen() devuelve un error.

UDP ​

udp.socket

Emite cuando se crea un nuevo socket UDP.

Proceso ​

Añadido en: v16.18.0

child_process

Emite cuando se crea un nuevo proceso.

Hilo de trabajo ​

Añadido en: v16.18.0

worker_threads

Emite cuando se crea un nuevo hilo.