Canal de Diagnóstico

[Histórico]

Versão	Mudanças
v19.2.0, v18.13.0	diagnostics_channel agora é Estável.
v15.1.0, v14.17.0	Adicionado em: v15.1.0, v14.17.0

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código-Fonte: lib/diagnostics_channel.js

O módulo node:diagnostics_channel fornece uma API para criar canais nomeados para relatar dados de mensagens arbitrárias para fins de diagnóstico.

Ele pode ser acessado usando:

ESM

import diagnostics_channel from 'node:diagnostics_channel'

CJS

const diagnostics_channel = require('node:diagnostics_channel')

A intenção é que um escritor de módulo que deseja relatar mensagens de diagnóstico crie um ou vários canais de nível superior para relatar mensagens através deles. Canais também podem ser adquiridos em tempo de execução, mas isso não é recomendado devido à sobrecarga adicional de fazê-lo. Canais podem ser exportados por conveniência, mas desde que o nome seja conhecido, ele pode ser adquirido em qualquer lugar.

Se você pretende que seu módulo produza dados de diagnóstico para outros consumirem, é recomendável que você inclua documentação de quais canais nomeados são usados ​​juntamente com o formato dos dados da mensagem. Os nomes dos canais geralmente devem incluir o nome do módulo para evitar colisões com dados de outros módulos.

API Pública

Visão Geral

A seguir, há uma visão geral simples da API pública.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

// Obtenha um objeto de canal reutilizável
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Dados recebidos
}

// Inscreva-se no canal
diagnostics_channel.subscribe('my-channel', onMessage)

// Verifique se o canal tem um assinante ativo
if (channel.hasSubscribers) {
  // Publique dados no canal
  channel.publish({
    some: 'data',
  })
}

// Cancele a inscrição do canal
diagnostics_channel.unsubscribe('my-channel', onMessage)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

// Obtenha um objeto de canal reutilizável
const channel = diagnostics_channel.channel('my-channel')

function onMessage(message, name) {
  // Dados recebidos
}

// Inscreva-se no canal
diagnostics_channel.subscribe('my-channel', onMessage)

// Verifique se o canal tem um assinante ativo
if (channel.hasSubscribers) {
  // Publique dados no canal
  channel.publish({
    some: 'data',
  })
}

// Cancele a inscrição do canal
diagnostics_channel.unsubscribe('my-channel', onMessage)

diagnostics_channel.hasSubscribers(name)

Adicionado em: v15.1.0, v14.17.0

• name <string> | <symbol> O nome do canal
• Retorna: <boolean> Se houver assinantes ativos

Verifica se há assinantes ativos no canal nomeado. Isso é útil se a mensagem que você deseja enviar pode ser cara para preparar.

Esta API é opcional, mas útil ao tentar publicar mensagens de código muito sensível ao desempenho.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Existem assinantes, prepare e publique a mensagem
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Existem assinantes, prepare e publique a mensagem
}

diagnostics_channel.channel(name)

Adicionado em: v15.1.0, v14.17.0

• name <string> | <symbol> O nome do canal
• Retorna: <Channel> O objeto de canal nomeado

Este é o ponto de entrada principal para quem deseja publicar em um canal nomeado. Ele produz um objeto de canal que é otimizado para reduzir a sobrecarga no momento da publicação, tanto quanto possível.

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)

Adicionado em: v18.7.0, v16.17.0

• name <string> | <symbol> O nome do canal
• onMessage <Function> O manipulador para receber mensagens do canal
  • message <any> Os dados da mensagem
  • name <string> | <symbol> O nome do canal

Registre um manipulador de mensagens para assinar este canal. Este manipulador de mensagens será executado de forma síncrona sempre que uma mensagem for publicada no canal. Quaisquer erros lançados no manipulador de mensagens acionarão um 'uncaughtException'.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

diagnostics_channel.unsubscribe(name, onMessage)

Adicionado em: v18.7.0, v16.17.0

• name <string> | <symbol> O nome do canal
• onMessage <Function> O manipulador previamente inscrito a ser removido
• Retorna: <boolean> true se o manipulador foi encontrado, false caso contrário.

Remove um manipulador de mensagens previamente registrado neste canal com diagnostics_channel.subscribe(name, onMessage).

ESM

import diagnostics_channel from 'node:diagnostics_channel'

function onMessage(message, name) {
  // Dados recebidos
}

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

function onMessage(message, name) {
  // Dados recebidos
}

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

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

diagnostics_channel.tracingChannel(nameOrChannels)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• nameOrChannels <string> | <TracingChannel> Nome do canal ou objeto contendo todos os Canais TracingChannel
• Retorna: <TracingChannel> Coleção de canais para rastrear

Cria um invólucro TracingChannel para os Canais TracingChannel fornecidos. Se um nome for fornecido, os canais de rastreamento correspondentes serão criados na forma de tracing:${name}:${eventType}, onde eventType corresponde aos tipos de Canais TracingChannel.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

// ou...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

// ou...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
})

Classe: Channel

Adicionado em: v15.1.0, v14.17.0

A classe Channel representa um canal nomeado individual dentro do pipeline de dados. Ela é usada para rastrear assinantes e publicar mensagens quando há assinantes presentes. Ela existe como um objeto separado para evitar buscas de canais no momento da publicação, permitindo velocidades de publicação muito rápidas e permitindo o uso intenso com um custo mínimo. Os canais são criados com diagnostics_channel.channel(name), construir um canal diretamente com new Channel(name) não é suportado.

channel.hasSubscribers

Adicionado em: v15.1.0, v14.17.0

• Retorna: <boolean> Se houver assinantes ativos

Verifica se há assinantes ativos para este canal. Isso é útil se a mensagem que você deseja enviar pode ser cara de preparar.

Esta API é opcional, mas útil ao tentar publicar mensagens de código sensível ao desempenho.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('meu-canal')

if (channel.hasSubscribers) {
  // Há assinantes, prepare e publique a mensagem
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('meu-canal')

if (channel.hasSubscribers) {
  // Há assinantes, prepare e publique a mensagem
}

channel.publish(message)

Adicionado em: v15.1.0, v14.17.0

• message <any> A mensagem para enviar aos assinantes do canal

Publica uma mensagem para qualquer assinante do canal. Isso irá acionar manipuladores de mensagens de forma síncrona para que eles sejam executados dentro do mesmo contexto.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

const channel = diagnostics_channel.channel('meu-canal')

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

const channel = diagnostics_channel.channel('meu-canal')

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

channel.subscribe(onMessage)

Adicionado em: v15.1.0, v14.17.0

Obsoleto desde: v18.7.0, v16.17.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use diagnostics_channel.subscribe(name, onMessage)

• onMessage <Function> O manipulador para receber mensagens do canal
  • message <any> Os dados da mensagem
  • name <string> | <symbol> O nome do canal

Registre um manipulador de mensagens para se inscrever neste canal. Este manipulador de mensagens será executado de forma síncrona sempre que uma mensagem for publicada no canal. Quaisquer erros lançados no manipulador de mensagens acionarão um 'uncaughtException'.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channel.subscribe((message, name) => {
  // Dados recebidos
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channel.subscribe((message, name) => {
  // Dados recebidos
})

channel.unsubscribe(onMessage)

[Histórico]

Versão	Alterações
v18.7.0, v16.17.0	Obsoleto desde: v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0	Adicionado valor de retorno. Adicionado a canais sem assinantes.
v15.1.0, v14.17.0	Adicionado em: v15.1.0, v14.17.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use diagnostics_channel.unsubscribe(name, onMessage)

• onMessage <Function> O manipulador inscrito anteriormente a ser removido
• Retorna: <boolean> true se o manipulador foi encontrado, false caso contrário.

Remove um manipulador de mensagens previamente registrado neste canal com channel.subscribe(onMessage).

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

function onMessage(message, name) {
  // Dados recebidos
}

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) {
  // Dados recebidos
}

channel.subscribe(onMessage)

channel.unsubscribe(onMessage)

channel.bindStore(store[, transform])

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• store <AsyncLocalStorage> O armazenamento ao qual vincular os dados de contexto
• transform <Function> Transforma os dados de contexto antes de definir o contexto do armazenamento

Quando channel.runStores(context, ...) é chamado, os dados de contexto fornecidos serão aplicados a qualquer armazenamento vinculado ao canal. Se o armazenamento já tiver sido vinculado, a função transform anterior será substituída pela nova. A função transform pode ser omitida para definir os dados de contexto fornecidos diretamente como o contexto.

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)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• store <AsyncLocalStorage> O armazenamento a ser desvinculado do canal.
• Retorna: <boolean> true se o armazenamento foi encontrado, false caso contrário.

Remove um manipulador de mensagens previamente registrado neste canal com 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]])

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• context <any> Mensagem para enviar aos assinantes e vincular aos armazenamentos
• fn <Function> Manipulador para executar dentro do contexto de armazenamento inserido
• thisArg <any> O receptor a ser usado para a chamada da função.
• ...args <any> Argumentos opcionais para passar para a função.

Aplica os dados fornecidos a quaisquer instâncias de AsyncLocalStorage vinculadas ao canal durante a duração da função fornecida e, em seguida, publica no canal dentro do escopo em que esses dados são aplicados aos armazenamentos.

Se uma função de transformação foi fornecida para channel.bindStore(store), ela será aplicada para transformar os dados da mensagem antes que ela se torne o valor de contexto para o armazenamento. O contexto de armazenamento anterior é acessível de dentro da função de transformação nos casos em que a vinculação de contexto é necessária.

O contexto aplicado ao armazenamento deve ser acessível em qualquer código assíncrono que continue a partir da execução que começou durante a função fornecida, no entanto, existem algumas situações em que a perda de contexto pode ocorrer.

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

A classe TracingChannel é uma coleção de Canais TracingChannel que, juntos, expressam uma única ação rastreável. Ela é usada para formalizar e simplificar o processo de produção de eventos para rastrear o fluxo do aplicativo. diagnostics_channel.tracingChannel() é usado para construir um TracingChannel. Assim como com Channel, é recomendado criar e reutilizar um único TracingChannel no nível superior do arquivo, em vez de criá-los dinamicamente.

tracingChannel.subscribe(subscribers)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• subscribers <Objeto> Conjunto de assinantes Canais TracingChannel
  • start <Função> O assinante do evento start
  • end <Função> O assinante do evento end
  • asyncStart <Função> O assinante do evento asyncStart
  • asyncEnd <Função> O assinante do evento asyncEnd
  • error <Função> O assinante do evento error

Auxiliar para assinar uma coleção de funções nos canais correspondentes. Isso é o mesmo que chamar channel.subscribe(onMessage) em cada canal individualmente.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.subscribe({
  start(message) {
    // Lidar com mensagem de início
  },
  end(message) {
    // Lidar com mensagem de fim
  },
  asyncStart(message) {
    // Lidar com mensagem asyncStart
  },
  asyncEnd(message) {
    // Lidar com mensagem asyncEnd
  },
  error(message) {
    // Lidar com mensagem de erro
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.subscribe({
  start(message) {
    // Lidar com mensagem de início
  },
  end(message) {
    // Lidar com mensagem de fim
  },
  asyncStart(message) {
    // Lidar com mensagem asyncStart
  },
  asyncEnd(message) {
    // Lidar com mensagem asyncEnd
  },
  error(message) {
    // Lidar com mensagem de erro
  },
})

tracingChannel.unsubscribe(subscribers)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• subscribers <Object> Conjunto de assinantes de Canais TracingChannel

  • start <Function> O assinante do evento start
  • end <Function> O assinante do evento end
  • asyncStart <Function> O assinante do evento asyncStart
  • asyncEnd <Function> O assinante do evento asyncEnd
  • error <Function> O assinante do evento error

• Retorna: <boolean> true se todos os manipuladores foram cancelados com sucesso, e false caso contrário.

Auxiliar para cancelar a inscrição de uma coleção de funções dos canais correspondentes. Isso é o mesmo que chamar channel.unsubscribe(onMessage) em cada canal individualmente.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.unsubscribe({
  start(message) {
    // Lidar com a mensagem de início
  },
  end(message) {
    // Lidar com a mensagem de fim
  },
  asyncStart(message) {
    // Lidar com a mensagem asyncStart
  },
  asyncEnd(message) {
    // Lidar com a mensagem asyncEnd
  },
  error(message) {
    // Lidar com a mensagem de erro
  },
})

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.unsubscribe({
  start(message) {
    // Lidar com a mensagem de início
  },
  end(message) {
    // Lidar com a mensagem de fim
  },
  asyncStart(message) {
    // Lidar com a mensagem asyncStart
  },
  asyncEnd(message) {
    // Lidar com a mensagem asyncEnd
  },
  error(message) {
    // Lidar com a mensagem de erro
  },
})

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• fn <Function> Função para envolver um rastreamento
• context <Object> Objeto compartilhado para correlacionar eventos
• thisArg <any> O receptor a ser usado para a chamada de função
• ...args <any> Argumentos opcionais a serem passados para a função
• Retorna: <any> O valor de retorno da função fornecida

Rastreia uma chamada de função síncrona. Isso sempre produzirá um evento start e um evento end em torno da execução e pode produzir um evento error se a função fornecida lançar um erro. Isso executará a função fornecida usando channel.runStores(context, ...) no canal start, o que garante que todos os eventos tenham qualquer armazenamento vinculado definido para corresponder a este contexto de rastreamento.

Para garantir que apenas gráficos de rastreamento corretos sejam formados, os eventos só serão publicados se houver assinantes presentes antes do início do rastreamento. As assinaturas que forem adicionadas após o início do rastreamento não receberão eventos futuros desse rastreamento, apenas rastreamentos futuros serão vistos.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

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

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

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

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• fn <Function> Função que retorna uma Promise para envolver um rastreamento
• context <Object> Objeto compartilhado para correlacionar eventos de rastreamento
• thisArg <any> O receptor a ser usado para a chamada de função
• ...args <any> Argumentos opcionais para passar para a função
• Retorna: <Promise> Encadeada da promise retornada pela função dada

Rastreia uma chamada de função que retorna uma promise. Isso sempre produzirá um evento start e um evento end em torno da parte síncrona da execução da função e produzirá um evento asyncStart e um evento asyncEnd quando uma continuação de promise for alcançada. Também pode produzir um evento error se a função fornecida lançar um erro ou se a promise retornada for rejeitada. Isso executará a função fornecida usando channel.runStores(context, ...) no canal start, o que garante que todos os eventos tenham quaisquer armazenamentos vinculados definidos para corresponder a este contexto de rastreamento.

Para garantir que apenas os grafos de rastreamento corretos sejam formados, os eventos só serão publicados se os assinantes estiverem presentes antes de iniciar o rastreamento. Assinaturas que são adicionadas após o início do rastreamento não receberão eventos futuros desse rastreamento, apenas rastreamentos futuros serão vistos.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.tracePromise(
  async () => {
    // Faça algo
  },
  {
    some: 'thing',
  }
)

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.tracePromise(
  async () => {
    // Faça algo
  },
  {
    some: 'thing',
  }
)

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• fn <Function> callback usando a função para envolver um rastreamento
• position <number> Posição do argumento com índice zero do callback esperado (o padrão é o último argumento se undefined for passado)
• context <Object> Objeto compartilhado para correlacionar eventos de rastreamento (o padrão é {} se undefined for passado)
• thisArg <any> O receptor a ser usado para a chamada da função
• ...args <any> argumentos para passar para a função (deve incluir o callback)
• Retorna: <any> O valor de retorno da função fornecida

Rastreie uma chamada de função que recebe um callback. Espera-se que o callback siga a convenção de erro como primeiro argumento normalmente usada. Isso sempre produzirá um evento start e um evento end em torno da porção síncrona da execução da função e produzirá um evento asyncStart e um evento asyncEnd em torno da execução do callback. Também pode produzir um evento error se a função fornecida gerar um erro ou se o primeiro argumento passado para o callback estiver definido. Isso executará a função fornecida usando channel.runStores(context, ...) no canal start, o que garante que todos os eventos tenham quaisquer armazenamentos vinculados definidos para corresponder a este contexto de rastreamento.

Para garantir que apenas gráficos de rastreamento corretos sejam formados, os eventos só serão publicados se os assinantes estiverem presentes antes de iniciar o rastreamento. As assinaturas que são adicionadas após o início do rastreamento não receberão eventos futuros desse rastreamento, apenas rastreamentos futuros serão vistos.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceCallback(
  (arg1, callback) => {
    // Faça algo
    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) => {
    // Faça algo
    callback(null, 'result')
  },
  1,
  {
    some: 'thing',
  },
  thisArg,
  arg1,
  callback
)

O callback também será executado com channel.runStores(context, ...), o que permite a recuperação da perda de contexto em alguns casos.

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

// O canal de início define os dados iniciais da loja para algo
// e armazena esse valor de dados da loja no objeto de contexto de rastreamento
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Então asyncStart pode restaurar a partir desses dados que ele armazenou anteriormente
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()

// O canal de início define os dados iniciais da loja para algo
// e armazena esse valor de dados da loja no objeto de contexto de rastreamento
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// Então asyncStart pode restaurar a partir desses dados que ele armazenou anteriormente
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

tracingChannel.hasSubscribers

Adicionado em: v22.0.0, v20.13.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• Retorna: <boolean> true se algum dos canais individuais tiver um assinante, false caso contrário.

Este é um método auxiliar disponível em uma instância de TracingChannel para verificar se algum dos Canais TracingChannel tem assinantes. Um true é retornado se algum deles tiver pelo menos um assinante, um false é retornado caso contrário.

ESM

import diagnostics_channel from 'node:diagnostics_channel'

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

if (channels.hasSubscribers) {
  // Faça algo
}

CJS

const diagnostics_channel = require('node:diagnostics_channel')

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

if (channels.hasSubscribers) {
  // Faça algo
}

Canais TracingChannel

Um TracingChannel é uma coleção de vários diagnostics_channels representando pontos específicos no ciclo de vida de execução de uma única ação rastreável. O comportamento é dividido em cinco diagnostics_channels consistindo em start, end, asyncStart, asyncEnd e error. Uma única ação rastreável compartilhará o mesmo objeto de evento entre todos os eventos, o que pode ser útil para gerenciar a correlação por meio de um weakmap.

Esses objetos de evento serão estendidos com valores result ou error quando a tarefa "concluir". No caso de uma tarefa síncrona, o result será o valor de retorno e o error será qualquer coisa lançada da função. Com funções assíncronas baseadas em callback, o result será o segundo argumento do callback, enquanto o error será um erro lançado visível no evento end ou o primeiro argumento do callback em qualquer um dos eventos asyncStart ou asyncEnd.

Para garantir que apenas os gráficos de rastreamento corretos sejam formados, os eventos só devem ser publicados se os assinantes estiverem presentes antes de iniciar o rastreamento. Assinaturas que são adicionadas após o início do rastreamento não devem receber eventos futuros desse rastreamento, apenas rastreamentos futuros serão vistos.

Os canais de rastreamento devem seguir um padrão de nomenclatura de:

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

start(event)

• Nome: tracing:${name}:start

O evento start representa o ponto em que uma função é chamada. Neste ponto, os dados do evento podem conter argumentos de função ou qualquer outra coisa disponível no início da execução da função.

end(event)

• Nome: tracing:${name}:end

O evento end representa o ponto em que uma chamada de função retorna um valor. No caso de uma função assíncrona, isso ocorre quando a promessa é retornada, não quando a própria função faz uma instrução de retorno internamente. Neste ponto, se a função rastreada for síncrona, o campo result será definido com o valor de retorno da função. Alternativamente, o campo error pode estar presente para representar quaisquer erros lançados.

É recomendável ouvir especificamente o evento error para rastrear erros, pois pode ser possível que uma ação rastreável produza vários erros. Por exemplo, uma tarefa assíncrona que falha pode ser iniciada internamente antes que a parte síncrona da tarefa lance um erro.

asyncStart(event)

• Nome: tracing:${name}:asyncStart

O evento asyncStart representa o retorno de chamada ou continuação de uma função rastreável sendo alcançada. Neste ponto, coisas como argumentos de retorno de chamada podem estar disponíveis ou qualquer outra coisa que expresse o "resultado" da ação.

Para funções baseadas em retornos de chamada, o primeiro argumento do retorno de chamada será atribuído ao campo error, se não for undefined ou null, e o segundo argumento será atribuído ao campo result.

Para promessas, o argumento para o caminho resolve será atribuído a result ou o argumento para o caminho reject será atribuído a error.

É recomendável ouvir especificamente o evento error para rastrear erros, pois pode ser possível que uma ação rastreável produza vários erros. Por exemplo, uma tarefa assíncrona que falha pode ser iniciada internamente antes que a parte síncrona da tarefa lance um erro.

asyncEnd(event)

• Nome: tracing:${name}:asyncEnd

O evento asyncEnd representa o retorno de chamada de uma função assíncrona retornando. Não é provável que os dados do evento mudem após o evento asyncStart, no entanto, pode ser útil ver o ponto em que o retorno de chamada é concluído.

error(event)

• Nome: tracing:${name}:error

O evento error representa qualquer erro produzido pela função rastreável, seja de forma síncrona ou assíncrona. Se um erro for lançado na parte síncrona da função rastreada, o erro será atribuído ao campo error do evento e o evento error será acionado. Se um erro for recebido de forma assíncrona por meio de um retorno de chamada ou rejeição de promessa, ele também será atribuído ao campo error do evento e acionará o evento error.

É possível que uma única chamada de função rastreável produza erros várias vezes, portanto, isso deve ser considerado ao consumir este evento. Por exemplo, se outra tarefa assíncrona for acionada internamente, falhar e, em seguida, a parte síncrona da função lançar um erro, dois eventos error serão emitidos, um para o erro síncrono e outro para o erro assíncrono.

Canais Internos

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Embora a API diagnostics_channel agora seja considerada estável, os canais internos atualmente disponíveis não são. Cada canal deve ser declarado estável independentemente.

HTTP

http.client.request.created

• request <http.ClientRequest>

Emitido quando o cliente cria um objeto de solicitação. Ao contrário de http.client.request.start, este evento é emitido antes que a solicitação tenha sido enviada.

http.client.request.start

• request <http.ClientRequest>

Emitido quando o cliente inicia uma solicitação.

http.client.request.error

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

Emitido quando ocorre um erro durante uma solicitação do cliente.

http.client.response.finish

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

Emitido quando o cliente recebe uma resposta.

http.server.request.start

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

Emitido quando o servidor recebe uma solicitação.

http.server.response.created

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

Emitido quando o servidor cria uma resposta. O evento é emitido antes que a resposta seja enviada.

http.server.response.finish

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

Emitido quando o servidor envia uma resposta.

Módulos

module.require.start

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para require(). Nome do módulo.
  • parentFilename - Nome do módulo que tentou usar require(id).

Emitido quando require() é executado. Veja o evento start.

module.require.end

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para require(). Nome do módulo.
  • parentFilename - Nome do módulo que tentou usar require(id).

Emitido quando uma chamada a require() retorna. Veja o evento end.

module.require.error

• event <Object> contendo as seguintes propriedades

  • id - Argumento passado para require(). Nome do módulo.
  • parentFilename - Nome do módulo que tentou usar require(id).

• error <Error>

Emitido quando um require() lança um erro. Veja o evento error.

module.import.asyncStart

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para import(). Nome do módulo.
  • parentURL - Objeto URL do módulo que tentou usar import(id).

Emitido quando import() é invocado. Veja o evento asyncStart.

module.import.asyncEnd

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para import(). Nome do módulo.
  • parentURL - Objeto URL do módulo que tentou usar import(id).

Emitido quando import() é concluído. Veja o evento asyncEnd.

module.import.error

• event <Object> contendo as seguintes propriedades

  • id - Argumento passado para import(). Nome do módulo.
  • parentURL - Objeto URL do módulo que tentou usar import(id).

• error <Error>

Emitido quando um import() lança um erro. Veja o evento error.

NET

net.client.socket

• socket <net.Socket>

Emitido quando um novo socket cliente TCP ou pipe é criado.

net.server.socket

• socket <net.Socket>

Emitido quando uma nova conexão TCP ou pipe é recebida.

tracing:net.server.listen:asyncStart

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

Emitido quando net.Server.listen() é invocado, antes que a porta ou o pipe sejam realmente configurados.

tracing:net.server.listen:asyncEnd

• server <net.Server>

Emitido quando net.Server.listen() foi concluído e, portanto, o servidor está pronto para aceitar conexões.

tracing:net.server.listen:error

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

Emitido quando net.Server.listen() está retornando um erro.

UDP

udp.socket

• socket <dgram.Socket>

Emitido quando um novo socket UDP é criado.

Processo

Adicionado em: v16.18.0

child_process

• process <ChildProcess>

Emitido quando um novo processo é criado.

Thread de Trabalho

Adicionado em: v16.18.0

worker_threads

• worker Worker

Emitido quando uma nova thread é criada.